STRBUF(3)

✨ STRBUF(3) ✨

okay bestie, sit DOWN because we're about to talk about the Unidata string-buffer — it's from the UNIDATA LIBRARY FUNCTIONS section of the manual, and honestly? it's giving "strings but with zero size anxiety". 💅

🎀 NAME 🎀

strbuf, sbnew, sbcpy, sbncpy, sbcat, sbncat, sbstr, sblen, sbmax, sbgrow, sbfree — the whole Unidata string-buffer friend group. 🫶

🌸 SYNOPSIS 🌸

#include "udposix.h"
#include <stddef.h>  /* for "size_t" */
#include "strbuf.h"

Strbuf *sbnew(size_t max)
Strbuf *sbensure(Strbuf *sb, size_t max)
Strbuf *sbcpy(Strbuf *sb, const char *string)
Strbuf *sbncpy(Strbuf *sb, const char *string, size_t len)
Strbuf *sbcat(Strbuf *sb, const char *string)
Strbuf *sbncat(Strbuf *sb, const char *string, size_t len)
char   *sbstr(const Strbuf *sb)
size_t sblen(const Strbuf *sb)
size_t sbmax(const Strbuf *sb)
Strbuf *sbgrow(Strbuf *sb)
Strbuf *sbfree(Strbuf *sb)

💖 DESCRIPTION 💖

These routines define the Unidata string-buffer abstraction. What does that even mean? It means you get to operate on strings without ever worrying about size — like, arbitrary concatenation, no mental math, no panic, no nothing. iconic behavior fr fr. 😌

🦋 the functions, one by one 🦋

• sbnew() — creates a brand-new instance of a string buffer. max is the initial maximum size of the string buffer, aka the number of characters the buffer may hold, excluding the terminating \0 character. and yes, the buffer will grow beyond this size if it has to, but bestie, it's literally in your own interest to set max to something appropriate (like, enough to hold 90% of its potential population). This function returns the new string-buffer, or NULL if an error occurs. 💀
• sbensure() — ensures that the string buffer will be able to contain a string having max characters (again, excluding the terminating \0). This function returns the new string-buffer, or NULL if an error occurs.
• sbcpy() — sets the string-buffer to string, which must be 0-terminated. If successful, this function returns the original string-buffer. If an error occurs, this function returns NULL and the string-buffer is unchanged (no half-done mess, we respect boundaries here ✨).
• sbncpy() — sets the string-buffer to string. len is the number of characters in string to use and should exclude any terminating \0 character. If successful, this function returns the original string-buffer. If an error occurs, this function returns NULL and the string-buffer is unchanged.
• sbcat() — appends string, which must be 0-terminated, to the contents of the string-buffer. If the string-buffer has not been set via an earlier call to sbcpy() or sbncpy(), then the result is the same as sbcpy(sb, string). If successful, this function returns the original string-buffer. If an error occurs, this function returns NULL and the string-buffer is unchanged.
• sbncat() — appends string to the contents of the string-buffer. len is the number of characters to append and should exclude any terminating \0 character. If the string-buffer has not been set via an earlier call to sbcpy() or sbncpy(), then the result is the same as sbcpy(sb, string). If successful, this function returns the original string-buffer. If an error occurs, this function returns NULL and the string-buffer is unchanged.
• sbstr() — returns a pointer to the \0-terminated string in the string-buffer. If the string buffer has not been set, then the pointed-to string is empty — NB: the pointer is not NULL, okay, don't come for me. The returned string pointer may be used like any other string pointer, provided the user has ensured the size of the string-buffer via a call to sbensure(), if appropriate. For example:

(void) sbensure(sb, strlen(string));
(void) strcpy(sbstr(sb), string);

When string buffers are used this way, the calling application is responsible for ensuring proper \0-termination. that's on you, bestie. 🫵

• sblen() — returns the number of characters in the string-buffer, excluding the terminating \0 character. If the string-buffer has not been set, then the returned length is zero.
• sbmax() — returns the maximum number of characters that the string-buffer can currently hold, excluding the terminating \0 character.
• sbgrow() — increases the size of the string buffer. this is useful when there's no a priori knowledge of how large the string buffer should be. go forth and grow, queen. 👑
• sbfree() — releases the resources used by the string-buffer back to the operating-system and should be called when the string-buffer is no longer needed. It always returns (Strbuf*)NULL. always. no cap.

🧚 This package uses the UDPOSIX programming environment and the udalloc(3) memory allocation package. iykyk.

👑 MAINTAINER 👑

Steve Emmerson <steve@unidata.ucar.edu>. 🫡

🌈 SEE ALSO 🌈

• udalloc(3)
• udposix(3)

and that's the whole page, babe. 💜 printed 126-10-12, source revision $Date: 2000/08/07 23:15:04 $ — yeah she's an elder but she still ate, and she's still STRBUF(3) in the Unidata library. periodt. 💅✨