ici::doc::pod3::sdrstring(3)

📦 version 3.2.1, in ubuntu jammy

💖 sdrstring — Simple Data Recorder string functions 💖

okay bestie, welcome to ici::doc::pod3::sdrstring(3), a manual page about strings that live inside an SDR and are, honestly, a little extra about it. it's part of the ICI library functions and it's giving "small but mighty." let's go 🫶

✨ SYNOPSIS ✨

#include "sdr.h"

Object sdr_string_create (Sdr sdr, char *from);
Object sdr_string_dup    (Sdr sdr, Object from);
int    sdr_string_length (Sdr sdr, Object string);
int    sdr_string_read   (Sdr sdr, char *into, Object string);

like, that's the whole cast. four little icons, one header, no notes. 💅

🌸 DESCRIPTION 🌸

so SDR strings are how you record strings of up to 255 ASCII characters in the heap space of an SDR. that's the vibe. that's the whole job.

and here's the tea: unlike standard C strings, which are terminated by a zero byte, SDR strings record the length of the string as part of the string object. so the length is just… baked in. self-delimited. she doesn't need a zero byte to tell her when she's done, she already knows. main character energy fr fr. 👑

bestie listen: to store strings longer than 255 characters, use sdr_malloc() and sdr_write() instead of these functions. don't try to make these ones do it. they won't. that's not their arc. 😭

🎀 Object sdr_string_create(Sdr sdr, char *from)

creates a "self-delimited string" in the heap of the indicated SDR — allocating the required space and copying the indicated content. slay.

from must be a standard C string for which strlen() must not exceed 255. if it does, or if insufficient SDR space is available, 0 is returned. otherwise, you get the address of the newly created SDR string object. 💖

to destroy it? just use sdr_free(). no drama, no ceremony, we love a clean exit.

🦋 Object sdr_string_dup(Sdr sdr, Object from)

creates a duplicate of the SDR string whose address is from — allocating the required space and copying the original string's content. a little copy-paste moment, but make it heap. ✨

if insufficient SDR space is available, 0 is returned. otherwise you get the address of the newly created copy of the original SDR string object. iconic.

to destroy, use sdr_free().

🌈 int sdr_string_length(Sdr sdr, Object string)

returns the length of the indicated self-delimited string (as would be returned by strlen()), or -1 on any error.

that's it. that's the function. she measures and she leaves. ⭐

🍓 int sdr_string_read(Sdr sdr, char *into, Object string)

retrieves the content of the indicated self-delimited string into memory as a standard C string (NULL terminated). so it goes from "I know my own length" back to "I need a NULL to know when I'm done." character development tbh. 🙈

length of into should normally be SDRSTRING_BUFSZ (i.e., 256) to allow for the largest possible SDR string (255 characters) plus the terminating NULL. yes the math is 255 + 1, no we will not be doing mental gymnastics about it.

returns length of string (as would be returned by strlen()), or -1 on any error.

👑 SEE ALSO 👑

go read those too, bestie, they're the friend group. 💜

⚠️ reminder bestie: strlen() over 255 = 0 returned. no space in the SDR = 0 returned. any error on the read/length functions = -1. know the difference, it matters. 🫶

and that's the page!! brought to you by perl v5.24.1, dated 2016-07-07, from the ici::doc::pod3::sdrstring(3) manual. she's been here a while and she still ate. periodt. 💅🎀✨

📦 where this page comes from