54 lines
2 KiB
Text
54 lines
2 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.
|
|
|
|
->alloc_size and ->len should not be messed with, only strbuf_* functions will know how to handle those properly.
|
|
|
|
-- Functions
|
|
|
|
strbuf_append():
|
|
|
|
Like strncat() this function will append the buffer with the contents of 'str'
|
|
and will always copy exactly 'len' bytes. (if memory can be obtained ofcourse)
|
|
|
|
strbuf_reduce():
|
|
|
|
Will reduce ->buf by 'len' bytes from the end, Note that this don'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_rev():
|
|
|
|
Reverses the ->buf string.
|
|
|
|
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.
|
|
|