0 7ˆl–Ãa¾””ËmJq@Šã@¸ÛJbÑ¿Á 0a–Ãa¾””ËmJq@Šã@¸ÛJbÑ¿À, ˆl–Ðz¾”ËmJeAàq¶Ôţà „ ?_‡I|¥ŠèªÀÂ(­ strbuf API ========== strbuf's are meant to be used with all the usual C string and memory APIs. Given that the length of the buffer is known, it's often better to use the mem* functions than a str* one (memchr vs. strchr e.g.). Though, one has to be careful about the fact that str* functions often stop on NULs and that strbufs may have embedded NULs. An strbuf is NUL terminated for convenience, but no function in the strbuf API actually relies on the string being free of NULs. strbufs has some invariants that are very important to keep in mind: . The `buf` member is never NULL, so it can be used in any usual C string operations safely. strbuf's _have_ to be initialized either by `strbuf_init()` or by `= STRBUF_INIT` before the invariants, though. + Do *not* assume anything on what `buf` really is (e.g. if it is allocated memory or not), use `strbuf_detach()` to unwrap a memory buffer from its strbuf shell in a safe way. That is the sole supported way. This will give you a malloced buffer that you can later `free()`. + However, it is totally safe to modify anything in the string pointed by the `buf` member, between the indices `0` and `len-1` (inclusive). . The `buf` member is a byte array that has at least `len + 1` bytes allocated. The extra byte is used to store a `'\0'`, allowing the `buf` member to be a valid C-string. Every strbuf function ensure this invariant is preserved. + NOTE: It is OK to "play" with the buffer directly if you work it this way: + ---- strbuf_grow(sb, SOME_SIZE); <1> strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE); ---- <1> Here, the memory array starting at `sb->buf`, and of length `strbuf_avail(sb)` is all yours, and you can be sure that `strbuf_avail(sb)` is at least `SOME_SIZE`. + NOTE: `SOME_OTHER_SIZE` must be smaller or equal to `strbuf_avail(sb)`. + Doing so is safe, though if it has to be done in many places, adding the missing API to the strbuf module is the way to go. + WARNING: Do _not_ assume that the area that is yours is of size `alloc - 1` even if it's true in the current implementation. Alloc is somehow a "private" member that should not be messed with. Use `strbuf_avail()` instead. Data structures --------------- * `struct strbuf` This is the string buffer structure. The `len` member can be used to determine the current length of the string, and `buf` member provides access to the string itself. Functions --------- * Life cycle `strbuf_init`:: Initialize the structure. The second parameter can be zero or a bigger number to allocate memory, in case you want to prevent further reallocs. `strbuf_release`:: Release a string buffer and the memory it used. You should not use the string buffer after using this function, unless you initialize it again. `strbuf_detach`:: Detach the string from the strbuf and returns it; you now own the storage the string occupies and it is your responsibility from then on to release it with `free(3)` when you are done with it. `strbuf_attach`:: Attach a string to a buffer. You should specify the string to attach, the current length of the string and the amount of allocated memory. The amount must be larger than the string length, because the string you pass is supposed to be a NUL-terminated string. This string _must_ be malloc()ed, and after attaching, the pointer cannot be relied upon anymore, and neither be free()d directly. `strbuf_swap`:: Swap the contents of two string buffers. * Related to the size of the buffer `strbuf_avail`:: Determine the amount of allocated but unused memory. `strbuf_grow`:: Ensure that at least this amount of unused memory is available after `len`. This is used when you know a typical size for what you will add and want to avoid repetitive automatic resizing of the underlying buffer. This is never a needed operation, but can be critical for performance in some cases. `strbuf_setlen`:: Set the length of the buffer to a given value. This fun