strbuf.hon commit t7063: fix flaky untracked-cache test (9b680fb)
   1#ifndef STRBUF_H
   2#define STRBUF_H
   3
   4/**
   5 * strbuf's are meant to be used with all the usual C string and memory
   6 * APIs. Given that the length of the buffer is known, it's often better to
   7 * use the mem* functions than a str* one (memchr vs. strchr e.g.).
   8 * Though, one has to be careful about the fact that str* functions often
   9 * stop on NULs and that strbufs may have embedded NULs.
  10 *
  11 * A strbuf is NUL terminated for convenience, but no function in the
  12 * strbuf API actually relies on the string being free of NULs.
  13 *
  14 * strbufs have some invariants that are very important to keep in mind:
  15 *
  16 *  - The `buf` member is never NULL, so it can be used in any usual C
  17 *    string operations safely. strbuf's _have_ to be initialized either by
  18 *    `strbuf_init()` or by `= STRBUF_INIT` before the invariants, though.
  19 *
  20 *    Do *not* assume anything on what `buf` really is (e.g. if it is
  21 *    allocated memory or not), use `strbuf_detach()` to unwrap a memory
  22 *    buffer from its strbuf shell in a safe way. That is the sole supported
  23 *    way. This will give you a malloced buffer that you can later `free()`.
  24 *
  25 *    However, it is totally safe to modify anything in the string pointed by
  26 *    the `buf` member, between the indices `0` and `len-1` (inclusive).
  27 *
  28 *  - The `buf` member is a byte array that has at least `len + 1` bytes
  29 *    allocated. The extra byte is used to store a `'\0'`, allowing the
  30 *    `buf` member to be a valid C-string. Every strbuf function ensure this
  31 *    invariant is preserved.
  32 *
  33 *    NOTE: It is OK to "play" with the buffer directly if you work it this
  34 *    way:
  35 *
  36 *        strbuf_grow(sb, SOME_SIZE); <1>
  37 *        strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE);
  38 *
  39 *    <1> Here, the memory array starting at `sb->buf`, and of length
  40 *    `strbuf_avail(sb)` is all yours, and you can be sure that
  41 *    `strbuf_avail(sb)` is at least `SOME_SIZE`.
  42 *
  43 *    NOTE: `SOME_OTHER_SIZE` must be smaller or equal to `strbuf_avail(sb)`.
  44 *
  45 *    Doing so is safe, though if it has to be done in many places, adding the
  46 *    missing API to the strbuf module is the way to go.
  47 *
  48 *    WARNING: Do _not_ assume that the area that is yours is of size `alloc
  49 *    - 1` even if it's true in the current implementation. Alloc is somehow a
  50 *    "private" member that should not be messed with. Use `strbuf_avail()`
  51 *    instead.
  52*/
  53
  54/**
  55 * Data Structures
  56 * ---------------
  57 */
  58
  59/**
  60 * This is the string buffer structure. The `len` member can be used to
  61 * determine the current length of the string, and `buf` member provides
  62 * access to the string itself.
  63 */
  64struct strbuf {
  65        size_t alloc;
  66        size_t len;
  67        char *buf;
  68};
  69
  70extern char strbuf_slopbuf[];
  71#define STRBUF_INIT  { 0, 0, strbuf_slopbuf }
  72
  73/**
  74 * Life Cycle Functions
  75 * --------------------
  76 */
  77
  78/**
  79 * Initialize the structure. The second parameter can be zero or a bigger
  80 * number to allocate memory, in case you want to prevent further reallocs.
  81 */
  82extern void strbuf_init(struct strbuf *, size_t);
  83
  84/**
  85 * Release a string buffer and the memory it used. You should not use the
  86 * string buffer after using this function, unless you initialize it again.
  87 */
  88extern void strbuf_release(struct strbuf *);
  89
  90/**
  91 * Detach the string from the strbuf and returns it; you now own the
  92 * storage the string occupies and it is your responsibility from then on
  93 * to release it with `free(3)` when you are done with it.
  94 */
  95extern char *strbuf_detach(struct strbuf *, size_t *);
  96
  97/**
  98 * Attach a string to a buffer. You should specify the string to attach,
  99 * the current length of the string and the amount of allocated memory.
 100 * The amount must be larger than the string length, because the string you
 101 * pass is supposed to be a NUL-terminated string.  This string _must_ be
 102 * malloc()ed, and after attaching, the pointer cannot be relied upon
 103 * anymore, and neither be free()d directly.
 104 */
 105extern void strbuf_attach(struct strbuf *, void *, size_t, size_t);
 106
 107/**
 108 * Swap the contents of two string buffers.
 109 */
 110static inline void strbuf_swap(struct strbuf *a, struct strbuf *b)
 111{
 112        struct strbuf tmp = *a;
 113        *a = *b;
 114        *b = tmp;
 115}
 116
 117
 118/**
 119 * Functions related to the size of the buffer
 120 * -------------------------------------------
 121 */
 122
 123/**
 124 * Determine the amount of allocated but unused memory.
 125 */
 126static inline size_t strbuf_avail(const struct strbuf *sb)
 127{
 128        return sb->alloc ? sb->alloc - sb->len - 1 : 0;
 129}
 130
 131/**
 132 * Ensure that at least this amount of unused memory is available after
 133 * `len`. This is used when you know a typical size for what you will add
 134 * and want to avoid repetitive automatic resizing of the underlying buffer.
 135 * This is never a needed operation, but can be critical for performance in
 136 * some cases.
 137 */
 138extern void strbuf_grow(struct strbuf *, size_t);
 139
 140/**
 141 * Set the length of the buffer to a given value. This function does *not*
 142 * allocate new memory, so you should not perform a `strbuf_setlen()` to a
 143 * length that is larger than `len + strbuf_avail()`. `strbuf_setlen()` is
 144 * just meant as a 'please fix invariants from this strbuf I just messed
 145 * with'.
 146 */
 147static inline void strbuf_setlen(struct strbuf *sb, size_t len)
 148{
 149        if (len > (sb->alloc ? sb->alloc - 1 : 0))
 150                die("BUG: strbuf_setlen() beyond buffer");
 151        sb->len = len;
 152        sb->buf[len] = '\0';
 153}
 154
 155/**
 156 * Empty the buffer by setting the size of it to zero.
 157 */
 158#define strbuf_reset(sb)  strbuf_setlen(sb, 0)
 159
 160
 161/**
 162 * Functions related to the contents of the buffer
 163 * -----------------------------------------------
 164 */
 165
 166/**
 167 * Strip whitespace from the beginning (`ltrim`), end (`rtrim`), or both side
 168 * (`trim`) of a string.
 169 */
 170extern void strbuf_trim(struct strbuf *);
 171extern void strbuf_rtrim(struct strbuf *);
 172extern void strbuf_ltrim(struct strbuf *);
 173
 174/**
 175 * Replace the contents of the strbuf with a reencoded form.  Returns -1
 176 * on error, 0 on success.
 177 */
 178extern int strbuf_reencode(struct strbuf *sb, const char *from, const char *to);
 179
 180/**
 181 * Lowercase each character in the buffer using `tolower`.
 182 */
 183extern void strbuf_tolower(struct strbuf *sb);
 184
 185/**
 186 * Compare two buffers. Returns an integer less than, equal to, or greater
 187 * than zero if the first buffer is found, respectively, to be less than,
 188 * to match, or be greater than the second buffer.
 189 */
 190extern int strbuf_cmp(const struct strbuf *, const struct strbuf *);
 191
 192
 193/**
 194 * Adding data to the buffer
 195 * -------------------------
 196 *
 197 * NOTE: All of the functions in this section will grow the buffer as
 198 * necessary.  If they fail for some reason other than memory shortage and the
 199 * buffer hadn't been allocated before (i.e. the `struct strbuf` was set to
 200 * `STRBUF_INIT`), then they will free() it.
 201 */
 202
 203/**
 204 * Add a single character to the buffer.
 205 */
 206static inline void strbuf_addch(struct strbuf *sb, int c)
 207{
 208        if (!strbuf_avail(sb))
 209                strbuf_grow(sb, 1);
 210        sb->buf[sb->len++] = c;
 211        sb->buf[sb->len] = '\0';
 212}
 213
 214/**
 215 * Add a character the specified number of times to the buffer.
 216 */
 217extern void strbuf_addchars(struct strbuf *sb, int c, size_t n);
 218
 219/**
 220 * Insert data to the given position of the buffer. The remaining contents
 221 * will be shifted, not overwritten.
 222 */
 223extern void strbuf_insert(struct strbuf *, size_t pos, const void *, size_t);
 224
 225/**
 226 * Remove given amount of data from a given position of the buffer.
 227 */
 228extern void strbuf_remove(struct strbuf *, size_t pos, size_t len);
 229
 230/**
 231 * Remove the bytes between `pos..pos+len` and replace it with the given
 232 * data.
 233 */
 234extern void strbuf_splice(struct strbuf *, size_t pos, size_t len,
 235                          const void *, size_t);
 236
 237/**
 238 * Add a NUL-terminated string to the buffer. Each line will be prepended
 239 * by a comment character and a blank.
 240 */
 241extern void strbuf_add_commented_lines(struct strbuf *out, const char *buf, size_t size);
 242
 243
 244/**
 245 * Add data of given length to the buffer.
 246 */
 247extern void strbuf_add(struct strbuf *, const void *, size_t);
 248
 249/**
 250 * Add a NUL-terminated string to the buffer.
 251 *
 252 * NOTE: This function will *always* be implemented as an inline or a macro
 253 * using strlen, meaning that this is efficient to write things like:
 254 *
 255 *     strbuf_addstr(sb, "immediate string");
 256 *
 257 */
 258static inline void strbuf_addstr(struct strbuf *sb, const char *s)
 259{
 260        strbuf_add(sb, s, strlen(s));
 261}
 262
 263/**
 264 * Copy the contents of another buffer at the end of the current one.
 265 */
 266static inline void strbuf_addbuf(struct strbuf *sb, const struct strbuf *sb2)
 267{
 268        strbuf_grow(sb, sb2->len);
 269        strbuf_add(sb, sb2->buf, sb2->len);
 270}
 271
 272/**
 273 * Copy part of the buffer from a given position till a given length to the
 274 * end of the buffer.
 275 */
 276extern void strbuf_adddup(struct strbuf *sb, size_t pos, size_t len);
 277
 278/**
 279 * This function can be used to expand a format string containing
 280 * placeholders. To that end, it parses the string and calls the specified
 281 * function for every percent sign found.
 282 *
 283 * The callback function is given a pointer to the character after the `%`
 284 * and a pointer to the struct strbuf.  It is expected to add the expanded
 285 * version of the placeholder to the strbuf, e.g. to add a newline
 286 * character if the letter `n` appears after a `%`.  The function returns
 287 * the length of the placeholder recognized and `strbuf_expand()` skips
 288 * over it.
 289 *
 290 * The format `%%` is automatically expanded to a single `%` as a quoting
 291 * mechanism; callers do not need to handle the `%` placeholder themselves,
 292 * and the callback function will not be invoked for this placeholder.
 293 *
 294 * All other characters (non-percent and not skipped ones) are copied
 295 * verbatim to the strbuf.  If the callback returned zero, meaning that the
 296 * placeholder is unknown, then the percent sign is copied, too.
 297 *
 298 * In order to facilitate caching and to make it possible to give
 299 * parameters to the callback, `strbuf_expand()` passes a context pointer,
 300 * which can be used by the programmer of the callback as she sees fit.
 301 */
 302typedef size_t (*expand_fn_t) (struct strbuf *sb, const char *placeholder, void *context);
 303extern void strbuf_expand(struct strbuf *sb, const char *format, expand_fn_t fn, void *context);
 304
 305/**
 306 * Used as callback for `strbuf_expand()`, expects an array of
 307 * struct strbuf_expand_dict_entry as context, i.e. pairs of
 308 * placeholder and replacement string.  The array needs to be
 309 * terminated by an entry with placeholder set to NULL.
 310 */
 311struct strbuf_expand_dict_entry {
 312        const char *placeholder;
 313        const char *value;
 314};
 315extern size_t strbuf_expand_dict_cb(struct strbuf *sb, const char *placeholder, void *context);
 316
 317/**
 318 * Append the contents of one strbuf to another, quoting any
 319 * percent signs ("%") into double-percents ("%%") in the
 320 * destination. This is useful for literal data to be fed to either
 321 * strbuf_expand or to the *printf family of functions.
 322 */
 323extern void strbuf_addbuf_percentquote(struct strbuf *dst, const struct strbuf *src);
 324
 325/**
 326 * Append the given byte size as a human-readable string (i.e. 12.23 KiB,
 327 * 3.50 MiB).
 328 */
 329extern void strbuf_humanise_bytes(struct strbuf *buf, off_t bytes);
 330
 331/**
 332 * Add a formatted string to the buffer.
 333 */
 334__attribute__((format (printf,2,3)))
 335extern void strbuf_addf(struct strbuf *sb, const char *fmt, ...);
 336
 337/**
 338 * Add a formatted string prepended by a comment character and a
 339 * blank to the buffer.
 340 */
 341__attribute__((format (printf, 2, 3)))
 342extern void strbuf_commented_addf(struct strbuf *sb, const char *fmt, ...);
 343
 344__attribute__((format (printf,2,0)))
 345extern void strbuf_vaddf(struct strbuf *sb, const char *fmt, va_list ap);
 346
 347/**
 348 * Read a given size of data from a FILE* pointer to the buffer.
 349 *
 350 * NOTE: The buffer is rewound if the read fails. If -1 is returned,
 351 * `errno` must be consulted, like you would do for `read(3)`.
 352 * `strbuf_read()`, `strbuf_read_file()` and `strbuf_getline()` has the
 353 * same behaviour as well.
 354 */
 355extern size_t strbuf_fread(struct strbuf *, size_t, FILE *);
 356
 357/**
 358 * Read the contents of a given file descriptor. The third argument can be
 359 * used to give a hint about the file size, to avoid reallocs.  If read fails,
 360 * any partial read is undone.
 361 */
 362extern ssize_t strbuf_read(struct strbuf *, int fd, size_t hint);
 363
 364/**
 365 * Read the contents of a file, specified by its path. The third argument
 366 * can be used to give a hint about the file size, to avoid reallocs.
 367 */
 368extern ssize_t strbuf_read_file(struct strbuf *sb, const char *path, size_t hint);
 369
 370/**
 371 * Read the target of a symbolic link, specified by its path.  The third
 372 * argument can be used to give a hint about the size, to avoid reallocs.
 373 */
 374extern int strbuf_readlink(struct strbuf *sb, const char *path, size_t hint);
 375
 376/**
 377 * Read a line from a FILE *, overwriting the existing contents
 378 * of the strbuf. The second argument specifies the line
 379 * terminator character, typically `'\n'`.
 380 * Reading stops after the terminator or at EOF.  The terminator
 381 * is removed from the buffer before returning.  Returns 0 unless
 382 * there was nothing left before EOF, in which case it returns `EOF`.
 383 */
 384extern int strbuf_getline(struct strbuf *, FILE *, int);
 385
 386/**
 387 * Like `strbuf_getline`, but keeps the trailing terminator (if
 388 * any) in the buffer.
 389 */
 390extern int strbuf_getwholeline(struct strbuf *, FILE *, int);
 391
 392/**
 393 * Like `strbuf_getwholeline`, but operates on a file descriptor.
 394 * It reads one character at a time, so it is very slow.  Do not
 395 * use it unless you need the correct position in the file
 396 * descriptor.
 397 */
 398extern int strbuf_getwholeline_fd(struct strbuf *, int, int);
 399
 400/**
 401 * Set the buffer to the path of the current working directory.
 402 */
 403extern int strbuf_getcwd(struct strbuf *sb);
 404
 405/**
 406 * Add a path to a buffer, converting a relative path to an
 407 * absolute one in the process.  Symbolic links are not
 408 * resolved.
 409 */
 410extern void strbuf_add_absolute_path(struct strbuf *sb, const char *path);
 411
 412/**
 413 * Strip whitespace from a buffer. The second parameter controls if
 414 * comments are considered contents to be removed or not.
 415 */
 416extern void stripspace(struct strbuf *buf, int skip_comments);
 417
 418static inline int strbuf_strip_suffix(struct strbuf *sb, const char *suffix)
 419{
 420        if (strip_suffix_mem(sb->buf, &sb->len, suffix)) {
 421                strbuf_setlen(sb, sb->len);
 422                return 1;
 423        } else
 424                return 0;
 425}
 426
 427/**
 428 * Split str (of length slen) at the specified terminator character.
 429 * Return a null-terminated array of pointers to strbuf objects
 430 * holding the substrings.  The substrings include the terminator,
 431 * except for the last substring, which might be unterminated if the
 432 * original string did not end with a terminator.  If max is positive,
 433 * then split the string into at most max substrings (with the last
 434 * substring containing everything following the (max-1)th terminator
 435 * character).
 436 *
 437 * The most generic form is `strbuf_split_buf`, which takes an arbitrary
 438 * pointer/len buffer. The `_str` variant takes a NUL-terminated string,
 439 * the `_max` variant takes a strbuf, and just `strbuf_split` is a convenience
 440 * wrapper to drop the `max` parameter.
 441 *
 442 * For lighter-weight alternatives, see string_list_split() and
 443 * string_list_split_in_place().
 444 */
 445extern struct strbuf **strbuf_split_buf(const char *, size_t,
 446                                        int terminator, int max);
 447
 448static inline struct strbuf **strbuf_split_str(const char *str,
 449                                               int terminator, int max)
 450{
 451        return strbuf_split_buf(str, strlen(str), terminator, max);
 452}
 453
 454static inline struct strbuf **strbuf_split_max(const struct strbuf *sb,
 455                                                int terminator, int max)
 456{
 457        return strbuf_split_buf(sb->buf, sb->len, terminator, max);
 458}
 459
 460static inline struct strbuf **strbuf_split(const struct strbuf *sb,
 461                                           int terminator)
 462{
 463        return strbuf_split_max(sb, terminator, 0);
 464}
 465
 466/**
 467 * Free a NULL-terminated list of strbufs (for example, the return
 468 * values of the strbuf_split*() functions).
 469 */
 470extern void strbuf_list_free(struct strbuf **);
 471
 472/**
 473 * Launch the user preferred editor to edit a file and fill the buffer
 474 * with the file's contents upon the user completing their editing. The
 475 * third argument can be used to set the environment which the editor is
 476 * run in. If the buffer is NULL the editor is launched as usual but the
 477 * file's contents are not read into the buffer upon completion.
 478 */
 479extern int launch_editor(const char *path, struct strbuf *buffer, const char *const *env);
 480
 481extern void strbuf_add_lines(struct strbuf *sb, const char *prefix, const char *buf, size_t size);
 482
 483/**
 484 * Append s to sb, with the characters '<', '>', '&' and '"' converted
 485 * into XML entities.
 486 */
 487extern void strbuf_addstr_xml_quoted(struct strbuf *sb, const char *s);
 488
 489static inline void strbuf_complete_line(struct strbuf *sb)
 490{
 491        if (sb->len && sb->buf[sb->len - 1] != '\n')
 492                strbuf_addch(sb, '\n');
 493}
 494
 495extern int strbuf_branchname(struct strbuf *sb, const char *name);
 496extern int strbuf_check_branch_ref(struct strbuf *sb, const char *name);
 497
 498extern void strbuf_addstr_urlencode(struct strbuf *, const char *,
 499                                    int reserved);
 500
 501__attribute__((format (printf,1,2)))
 502extern int printf_ln(const char *fmt, ...);
 503__attribute__((format (printf,2,3)))
 504extern int fprintf_ln(FILE *fp, const char *fmt, ...);
 505
 506char *xstrdup_tolower(const char *);
 507
 508/**
 509 * Create a newly allocated string using printf format. You can do this easily
 510 * with a strbuf, but this provides a shortcut to save a few lines.
 511 */
 512__attribute__((format (printf, 1, 0)))
 513char *xstrvfmt(const char *fmt, va_list ap);
 514__attribute__((format (printf, 1, 2)))
 515char *xstrfmt(const char *fmt, ...);
 516
 517#endif /* STRBUF_H */