128 lines
4 KiB
Text
128 lines
4 KiB
Text
String buffer API
|
|
=================
|
|
|
|
First off, the major design choices. the most important thing to keep in mind
|
|
when using the API is that it is designed for low-level usage, The basic error checking
|
|
is removed (like checking if the input strbuf pointer is null). +
|
|
This is not done to gain speed, but because this is a buffer API, you should in almost every case allocate
|
|
the structure on the stack or have it passed from a function that has it allocated on the stack. +
|
|
Other types of skipped error checking is for example if the ->len member is in range of
|
|
the allocated block. (obviously this is checked in functions that may need to expand the memory)
|
|
|
|
Data structures
|
|
---------------
|
|
|
|
* `strbuf_t`
|
|
|
|
The ->buf member is yours to mess with if you want, but you should never go beyond ->len. +
|
|
A `NULL` terminating character is located at ->len+1 at all times so it is safe to use the ->buf member
|
|
on any function that relies on the input being a valid C string. The API will never rely on this
|
|
and it's possible to have embedded `NULL`'s because of that.
|
|
|
|
NOTE: ->alloc_size and ->len should *not* be messed with, only `strbuf_*` functions will know how to handle those properly.
|
|
|
|
Functions
|
|
---------
|
|
|
|
`strbuf_setlen()`::
|
|
|
|
Sets the length of the buffer. +
|
|
This function will not allocate memory, it only sets ->len and
|
|
assure that the string is null-terminated at the new position.
|
|
|
|
`strbuf_avail()`::
|
|
|
|
Returns the number of characters that are allocated but not used in the buffer.
|
|
|
|
`strbuf_append()`::
|
|
|
|
This function will append the buffer with the contents of 'ptr'
|
|
and will always copy exactly 'len' bytes. (if memory can be obtained ofcourse)
|
|
|
|
`strbuf_appendf()`::
|
|
|
|
Adds the formated-string 'fmt' to the end of ->buf.
|
|
|
|
`strbuf_append_va()`::
|
|
|
|
Adds the formated-string 'fmt' (generated by a `va_list`) to the end of ->buf. +
|
|
Returns the number of characters that should have been written if ->buf was large enough. +
|
|
Therefor if the function returns zero. all characters has been written. +
|
|
+
|
|
Example usage:
|
|
+
|
|
----
|
|
va_start(va, fmt);
|
|
len = strbuf_append_va(s, fmt, va);
|
|
va_end(va);
|
|
|
|
if (len > 0) {
|
|
strbuf_expand(s, len);
|
|
va_start(va, fmt);
|
|
strbuf_append_va(s, fmt, va);
|
|
va_end(va);
|
|
}
|
|
----
|
|
`strbuf_append_str()`::
|
|
|
|
Will add the 'str' C-string to the end of ->buf
|
|
|
|
`strbuf_append_ch()`::
|
|
|
|
Adds one character 'ch' to the end of ->buf
|
|
|
|
`strbuf_append_repeat()`::
|
|
|
|
Adds 'len' characters of 'ch' to the end of ->buf
|
|
|
|
`strbuf_reduce()`::
|
|
|
|
Will reduce ->buf by 'len' bytes from the end.
|
|
+
|
|
NOTE: This doesn't shrink the memory block
|
|
just changes the size and properly `NULL` terminates the now reduced space.
|
|
|
|
`strbuf_trim()`::
|
|
`strbuf_rtrim()`::
|
|
`strbuf_ltrim()`::
|
|
|
|
Removes space characters from the beginning (ltrim) of the ->buf string, the end (rtrim) or both (trim).
|
|
|
|
`strbuf_rchop()`::
|
|
|
|
Chops off everything to the right of the rightmost 'ch' encountered in the string. +
|
|
Returns a pointer to the where the rightmost 'ch' was located (that now is \'\0') or `NULL` if 'ch' does not exists in ->buf.
|
|
|
|
`strbuf_rev()`::
|
|
|
|
Reverses the ->buf string.
|
|
|
|
`strbuf_squeeze()`::
|
|
|
|
Squeezes "together" sequences of 'ch' into one character.
|
|
|
|
`strbuf_term()`::
|
|
|
|
ensure that ->buf is terminated with 'ch'. Will not change ->buf if it is already terminated.
|
|
|
|
`strbuf_explode()`::
|
|
|
|
Returns a NULL terminated list of string buffers, each containing a substring of 'str' splitted by delimiter'. +
|
|
Returns `NULL` if 'delimiter' does not exists in 'str'.
|
|
+
|
|
TIP: use `strbuf_free_list()` to free the entire list.
|
|
+
|
|
NOTE: 'delimiter' is not included in the list.
|
|
|
|
`strbuf_release()`::
|
|
|
|
This function should be used to detach the ->buf member from the `strbuf_t` structure. +
|
|
A `malloc()`'ed C string of size `strlen()+1` is returned that you are now responsible for.
|
|
|
|
`strbuf_free()`::
|
|
|
|
Free's all the memory (allocated on the heap) associted with the `strbuf_t` structure.
|
|
|
|
`strbuf_free_list()`::
|
|
|
|
Free's all the memory from an NULL terminated list of string buffers.
|