* 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);
- * ----
+ * 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`.
#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)
__attribute__((format (printf,2,0)))
extern void strbuf_vaddf(struct strbuf *sb, const char *fmt, va_list ap);
+/**
+ * Add the time specified by `tm`, as formatted by `strftime`.
+ */
+extern void strbuf_addftime(struct strbuf *sb, const char *fmt, const struct tm *tm);
+
/**
* Read a given size of data from a FILE* pointer to the buffer.
*
*/
extern ssize_t strbuf_read(struct strbuf *, int fd, size_t hint);
+/**
+ * Read the contents of a given file descriptor partially by using only one
+ * attempt of xread. The third argument can be used to give a hint about the
+ * file size, to avoid reallocs. Returns the number of new bytes appended to
+ * the sb.
+ */
+extern ssize_t strbuf_read_once(struct strbuf *, int fd, size_t hint);
+
/**
* Read the contents of a file, specified by its path. The third argument
* can be used to give a hint about the file size, to avoid reallocs.
*/
-extern int strbuf_read_file(struct strbuf *sb, const char *path, size_t hint);
+extern ssize_t strbuf_read_file(struct strbuf *sb, const char *path, size_t hint);
/**
* Read the target of a symbolic link, specified by its path. The third
* Strip whitespace from a buffer. The second parameter controls if
* comments are considered contents to be removed or not.
*/
-extern void stripspace(struct strbuf *buf, int skip_comments);
+extern void strbuf_stripspace(struct strbuf *buf, int skip_comments);
+
+/**
+ * Temporary alias until all topic branches have switched to use
+ * strbuf_stripspace directly.
+ */
+static inline void stripspace(struct strbuf *buf, int skip_comments)
+{
+ strbuf_stripspace(buf, skip_comments);
+}
static inline int strbuf_strip_suffix(struct strbuf *sb, const char *suffix)
{
* 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)
{
*/
extern void strbuf_list_free(struct strbuf **);
+/**
+ * Add the abbreviation, as generated by find_unique_abbrev, of `sha1` to
+ * the strbuf `sb`.
+ */
+extern void strbuf_add_unique_abbrev(struct strbuf *sb,
+ const unsigned char *sha1,
+ int abbrev_len);
+
/**
* Launch the user preferred editor to edit a file and fill the buffer
* with the file's contents upon the user completing their editing. The
*/
extern void strbuf_addstr_xml_quoted(struct strbuf *sb, const char *s);
+/**
+ * "Complete" the contents of `sb` by ensuring that either it ends with the
+ * character `term`, or it is empty. This can be used, for example,
+ * to ensure that text ends with a newline, but without creating an empty
+ * blank line if there is no content in the first place.
+ */
+static inline void strbuf_complete(struct strbuf *sb, char term)
+{
+ if (sb->len && sb->buf[sb->len - 1] != term)
+ strbuf_addch(sb, term);
+}
+
static inline void strbuf_complete_line(struct strbuf *sb)
{
- if (sb->len && sb->buf[sb->len - 1] != '\n')
- strbuf_addch(sb, '\n');
+ strbuf_complete(sb, '\n');
}
extern int strbuf_branchname(struct strbuf *sb, const char *name);