*
* strbufs have 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 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.
*
- * . 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.
- */
+ * 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
#define STRBUF_INIT { 0, 0, strbuf_slopbuf }
/**
- * Functions
- * ---------
- */
-
-/**
- * * Life Cycle
+ * Life Cycle Functions
+ * --------------------
*/
/**
/**
- * * Related to the size of the buffer
+ * Functions related to the size of the buffer
+ * -------------------------------------------
*/
/**
/**
- * * Related to the contents of the buffer
+ * Functions related to the contents of the buffer
+ * -----------------------------------------------
*/
/**
- * Strip whitespace from the beginning and end of a string.
- * Equivalent to performing `strbuf_rtrim()` followed by `strbuf_ltrim()`.
+ * Strip whitespace from the beginning (`ltrim`), end (`rtrim`), or both side
+ * (`trim`) of a string.
*/
extern void strbuf_trim(struct strbuf *);
-
-/**
- * Strip whitespace from the end of a string.
- */
extern void strbuf_rtrim(struct strbuf *);
-
-/**
- * Strip whitespace from the beginning of a string.
- */
extern void strbuf_ltrim(struct strbuf *);
/**
/**
- * * Adding data to the buffer
+ * Adding data to the buffer
+ * -------------------------
*
* NOTE: All of the functions in this section will grow the buffer as
* necessary. If they fail for some reason other than memory shortage and the
*/
static inline void strbuf_addch(struct strbuf *sb, int c)
{
- strbuf_grow(sb, 1);
+ if (!strbuf_avail(sb))
+ strbuf_grow(sb, 1);
sb->buf[sb->len++] = c;
sb->buf[sb->len] = '\0';
}
* NOTE: This function will *always* be implemented as an inline or a macro
* using strlen, meaning that this is efficient to write things like:
*
- * ----
- * strbuf_addstr(sb, "immediate string");
- * ----
+ * strbuf_addstr(sb, "immediate string");
*
*/
static inline void strbuf_addstr(struct strbuf *sb, const char *s)
* substring containing everything following the (max-1)th terminator
* character).
*
+ * The most generic form is `strbuf_split_buf`, which takes an arbitrary
+ * pointer/len buffer. The `_str` variant takes a NUL-terminated string,
+ * the `_max` variant takes a strbuf, and just `strbuf_split` is a convenience
+ * wrapper to drop the `max` parameter.
+ *
* For lighter-weight alternatives, see string_list_split() and
* string_list_split_in_place().
*/
extern struct strbuf **strbuf_split_buf(const char *, size_t,
int terminator, int max);
-/**
- * Split a NUL-terminated string at the specified terminator
- * character. See strbuf_split_buf() for more information.
- */
static inline struct strbuf **strbuf_split_str(const char *str,
int terminator, int max)
{
return strbuf_split_buf(str, strlen(str), terminator, max);
}
-/**
- * Split a strbuf at the specified terminator character. See
- * strbuf_split_buf() for more information.
- */
static inline struct strbuf **strbuf_split_max(const struct strbuf *sb,
int terminator, int max)
{
return strbuf_split_buf(sb->buf, sb->len, terminator, max);
}
-/**
- * Split a strbuf at the specified terminator character. See
- * strbuf_split_buf() for more information.
- */
static inline struct strbuf **strbuf_split(const struct strbuf *sb,
int terminator)
{