SString

SString

Header: <cwist/core/sstring/sstring.h>

cwist_sstring is CWIST's growable, binary-safe string. Request and response bodies, paths and header values are sstrings.

cwist_sstring *s = cwist_sstring_create();
cwist_sstring_assign(s, "hello");
cwist_sstring_append(s, ", world");
cwist_sstring_append_len(s, "\0bin", 4);        /* binary-safe */
printf("%zu bytes: %s\n", s->size, s->data);    /* data stays NUL-terminated */
cwist_sstring_destroy(s);

data holds the bytes (always followed by a NUL), size the length. Read them directly; change the contents through the functions below.

Functions

Function	Description
cwist_sstring *cwist_sstring_create(void) / void cwist_sstring_destroy(cwist_sstring *s)	Lifecycle.
cwist_error_t cwist_sstring_init(cwist_sstring *s)	Initialize an sstring you allocated yourself. cwist_sstring_init_escaped() enables escaping on append.
cwist_sstring_assign(s, cstr) / cwist_sstring_assign_len(s, data, len)	Replace the contents (the _len form is binary-safe).
cwist_sstring_append(s, cstr) / cwist_sstring_append_len(s, data, len)	Append.
cwist_sstring_append_sstring(s, from)	Append another sstring.
cwist_sstring_append_escaped(s, cstr) / cwist_sstring_append_sstring_escaped(s, from)	Append with escaping.
cwist_sstring_borrow(s, data, len)	Point at external memory without copying (it must outlive the string); the first change copies it into owned storage.
cwist_sstring_adopt_len(s, buf, len)	Take ownership of a cwist_alloc buffer with room for the NUL at buf[len].
cwist_sstring_adopt_region(s, base, offset, len)	Take ownership of a cwist_alloc allocation and view a region inside it.
cwist_sstring_ltrim(s), _rtrim(s), _trim(s)	Remove leading, trailing or both whitespace in place.
int cwist_sstring_compare(s, cstr) / cwist_sstring_compare_sstring(a, b)	strcmp-style comparison.
cwist_sstring_seek(s, substr, location)	Search for a substring from a position.
cwist_sstring *cwist_sstring_substr(s, start, length)	New sstring with a slice (destroy it).
cwist_sstring_copy(origin, destination) / cwist_sstring_copy_sstring(origin, from)	Copy to a C buffer or another sstring.
size_t cwist_sstring_get_size(s)	Length.
cwist_sstring_change_size(s, size, blow_data)	Resize the buffer; with blow_data the contents are discarded.

All mutating functions return a cwist_error_t; check it with cwist_error_is_ok() (Error Handling).

Inside a request, CWIST may back sstrings with the request arena or borrowed buffers; the copy-on-write behavior above keeps that invisible to handlers.