1#ifndef STRBUF_H 2#define STRBUF_H 3 4struct string_list; 5 6/** 7 * strbuf's are meant to be used with all the usual C string and memory 8 * APIs. Given that the length of the buffer is known, it's often better to 9 * use the mem* functions than a str* one (memchr vs. strchr e.g.). 10 * Though, one has to be careful about the fact that str* functions often 11 * stop on NULs and that strbufs may have embedded NULs. 12 * 13 * A strbuf is NUL terminated for convenience, but no function in the 14 * strbuf API actually relies on the string being free of NULs. 15 * 16 * strbufs have some invariants that are very important to keep in mind: 17 * 18 * - The `buf` member is never NULL, so it can be used in any usual C 19 * string operations safely. strbuf's _have_ to be initialized either by 20 * `strbuf_init()` or by `= STRBUF_INIT` before the invariants, though. 21 * 22 * Do *not* assume anything on what `buf` really is (e.g. if it is 23 * allocated memory or not), use `strbuf_detach()` to unwrap a memory 24 * buffer from its strbuf shell in a safe way. That is the sole supported 25 * way. This will give you a malloced buffer that you can later `free()`. 26 * 27 * However, it is totally safe to modify anything in the string pointed by 28 * the `buf` member, between the indices `0` and `len-1` (inclusive). 29 * 30 * - The `buf` member is a byte array that has at least `len + 1` bytes 31 * allocated. The extra byte is used to store a `'\0'`, allowing the 32 * `buf` member to be a valid C-string. Every strbuf function ensure this 33 * invariant is preserved. 34 * 35 * NOTE: It is OK to "play" with the buffer directly if you work it this 36 * way: 37 * 38 * strbuf_grow(sb, SOME_SIZE); <1> 39 * strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE); 40 * 41 * <1> Here, the memory array starting at `sb->buf`, and of length 42 * `strbuf_avail(sb)` is all yours, and you can be sure that 43 * `strbuf_avail(sb)` is at least `SOME_SIZE`. 44 * 45 * NOTE: `SOME_OTHER_SIZE` must be smaller or equal to `strbuf_avail(sb)`. 46 * 47 * Doing so is safe, though if it has to be done in many places, adding the 48 * missing API to the strbuf module is the way to go. 49 * 50 * WARNING: Do _not_ assume that the area that is yours is of size `alloc 51 * - 1` even if it's true in the current implementation. Alloc is somehow a 52 * "private" member that should not be messed with. Use `strbuf_avail()` 53 * instead. 54*/ 55 56/** 57 * Data Structures 58 * --------------- 59 */ 60 61/** 62 * This is the string buffer structure. The `len` member can be used to 63 * determine the current length of the string, and `buf` member provides 64 * access to the string itself. 65 */ 66struct strbuf { 67 size_t alloc; 68 size_t len; 69 char *buf; 70}; 71 72extern char strbuf_slopbuf[]; 73#define STRBUF_INIT { .alloc = 0, .len = 0, .buf = strbuf_slopbuf } 74 75/* 76 * Predeclare this here, since cache.h includes this file before it defines the 77 * struct. 78 */ 79struct object_id; 80 81/** 82 * Life Cycle Functions 83 * -------------------- 84 */ 85 86/** 87 * Initialize the structure. The second parameter can be zero or a bigger 88 * number to allocate memory, in case you want to prevent further reallocs. 89 */ 90void strbuf_init(struct strbuf *sb, size_t alloc); 91 92/** 93 * Release a string buffer and the memory it used. After this call, the 94 * strbuf points to an empty string that does not need to be free()ed, as 95 * if it had been set to `STRBUF_INIT` and never modified. 96 * 97 * To clear a strbuf in preparation for further use without the overhead 98 * of free()ing and malloc()ing again, use strbuf_reset() instead. 99 */ 100void strbuf_release(struct strbuf *sb); 101 102/** 103 * Detach the string from the strbuf and returns it; you now own the 104 * storage the string occupies and it is your responsibility from then on 105 * to release it with `free(3)` when you are done with it. 106 * 107 * The strbuf that previously held the string is reset to `STRBUF_INIT` so 108 * it can be reused after calling this function. 109 */ 110char *strbuf_detach(struct strbuf *sb, size_t *sz); 111 112/** 113 * Attach a string to a buffer. You should specify the string to attach, 114 * the current length of the string and the amount of allocated memory. 115 * The amount must be larger than the string length, because the string you 116 * pass is supposed to be a NUL-terminated string. This string _must_ be 117 * malloc()ed, and after attaching, the pointer cannot be relied upon 118 * anymore, and neither be free()d directly. 119 */ 120void strbuf_attach(struct strbuf *sb, void *str, size_t len, size_t mem); 121 122/** 123 * Swap the contents of two string buffers. 124 */ 125static inline void strbuf_swap(struct strbuf *a, struct strbuf *b) 126{ 127 SWAP(*a, *b); 128} 129 130 131/** 132 * Functions related to the size of the buffer 133 * ------------------------------------------- 134 */ 135 136/** 137 * Determine the amount of allocated but unused memory. 138 */ 139static inline size_t strbuf_avail(const struct strbuf *sb) 140{ 141 return sb->alloc ? sb->alloc - sb->len - 1 : 0; 142} 143 144/** 145 * Ensure that at least this amount of unused memory is available after 146 * `len`. This is used when you know a typical size for what you will add 147 * and want to avoid repetitive automatic resizing of the underlying buffer. 148 * This is never a needed operation, but can be critical for performance in 149 * some cases. 150 */ 151void strbuf_grow(struct strbuf *sb, size_t amount); 152 153/** 154 * Set the length of the buffer to a given value. This function does *not* 155 * allocate new memory, so you should not perform a `strbuf_setlen()` to a 156 * length that is larger than `len + strbuf_avail()`. `strbuf_setlen()` is 157 * just meant as a 'please fix invariants from this strbuf I just messed 158 * with'. 159 */ 160static inline void strbuf_setlen(struct strbuf *sb, size_t len) 161{ 162 if (len > (sb->alloc ? sb->alloc - 1 : 0)) 163 die("BUG: strbuf_setlen() beyond buffer"); 164 sb->len = len; 165 if (sb->buf != strbuf_slopbuf) 166 sb->buf[len] = '\0'; 167 else 168 assert(!strbuf_slopbuf[0]); 169} 170 171/** 172 * Empty the buffer by setting the size of it to zero. 173 */ 174#define strbuf_reset(sb) strbuf_setlen(sb, 0) 175 176 177/** 178 * Functions related to the contents of the buffer 179 * ----------------------------------------------- 180 */ 181 182/** 183 * Strip whitespace from the beginning (`ltrim`), end (`rtrim`), or both side 184 * (`trim`) of a string. 185 */ 186void strbuf_trim(struct strbuf *sb); 187void strbuf_rtrim(struct strbuf *sb); 188void strbuf_ltrim(struct strbuf *sb); 189 190/* Strip trailing directory separators */ 191void strbuf_trim_trailing_dir_sep(struct strbuf *sb); 192 193/* Strip trailing LF or CR/LF */ 194void strbuf_trim_trailing_newline(struct strbuf *sb); 195 196/** 197 * Replace the contents of the strbuf with a reencoded form. Returns -1 198 * on error, 0 on success. 199 */ 200int strbuf_reencode(struct strbuf *sb, const char *from, const char *to); 201 202/** 203 * Lowercase each character in the buffer using `tolower`. 204 */ 205void strbuf_tolower(struct strbuf *sb); 206 207/** 208 * Compare two buffers. Returns an integer less than, equal to, or greater 209 * than zero if the first buffer is found, respectively, to be less than, 210 * to match, or be greater than the second buffer. 211 */ 212int strbuf_cmp(const struct strbuf *first, const struct strbuf *second); 213 214 215/** 216 * Adding data to the buffer 217 * ------------------------- 218 * 219 * NOTE: All of the functions in this section will grow the buffer as 220 * necessary. If they fail for some reason other than memory shortage and the 221 * buffer hadn't been allocated before (i.e. the `struct strbuf` was set to 222 * `STRBUF_INIT`), then they will free() it. 223 */ 224 225/** 226 * Add a single character to the buffer. 227 */ 228static inline void strbuf_addch(struct strbuf *sb, int c) 229{ 230 if (!strbuf_avail(sb)) 231 strbuf_grow(sb, 1); 232 sb->buf[sb->len++] = c; 233 sb->buf[sb->len] = '\0'; 234} 235 236/** 237 * Add a character the specified number of times to the buffer. 238 */ 239void strbuf_addchars(struct strbuf *sb, int c, size_t n); 240 241/** 242 * Insert data to the given position of the buffer. The remaining contents 243 * will be shifted, not overwritten. 244 */ 245void strbuf_insert(struct strbuf *sb, size_t pos, const void *, size_t); 246 247/** 248 * Remove given amount of data from a given position of the buffer. 249 */ 250void strbuf_remove(struct strbuf *sb, size_t pos, size_t len); 251 252/** 253 * Remove the bytes between `pos..pos+len` and replace it with the given 254 * data. 255 */ 256void strbuf_splice(struct strbuf *sb, size_t pos, size_t len, 257 const void *data, size_t data_len); 258 259/** 260 * Add a NUL-terminated string to the buffer. Each line will be prepended 261 * by a comment character and a blank. 262 */ 263void strbuf_add_commented_lines(struct strbuf *out, 264 const char *buf, size_t size); 265 266 267/** 268 * Add data of given length to the buffer. 269 */ 270void strbuf_add(struct strbuf *sb, const void *data, size_t len); 271 272/** 273 * Add a NUL-terminated string to the buffer. 274 * 275 * NOTE: This function will *always* be implemented as an inline or a macro 276 * using strlen, meaning that this is efficient to write things like: 277 * 278 * strbuf_addstr(sb, "immediate string"); 279 * 280 */ 281static inline void strbuf_addstr(struct strbuf *sb, const char *s) 282{ 283 strbuf_add(sb, s, strlen(s)); 284} 285 286/** 287 * Copy the contents of another buffer at the end of the current one. 288 */ 289void strbuf_addbuf(struct strbuf *sb, const struct strbuf *sb2); 290 291/** 292 * Join the arguments into a buffer. `delim` is put between every 293 * two arguments. 294 */ 295const char *strbuf_join_argv(struct strbuf *buf, int argc, 296 const char **argv, char delim); 297 298/** 299 * This function can be used to expand a format string containing 300 * placeholders. To that end, it parses the string and calls the specified 301 * function for every percent sign found. 302 * 303 * The callback function is given a pointer to the character after the `%` 304 * and a pointer to the struct strbuf. It is expected to add the expanded 305 * version of the placeholder to the strbuf, e.g. to add a newline 306 * character if the letter `n` appears after a `%`. The function returns 307 * the length of the placeholder recognized and `strbuf_expand()` skips 308 * over it. 309 * 310 * The format `%%` is automatically expanded to a single `%` as a quoting 311 * mechanism; callers do not need to handle the `%` placeholder themselves, 312 * and the callback function will not be invoked for this placeholder. 313 * 314 * All other characters (non-percent and not skipped ones) are copied 315 * verbatim to the strbuf. If the callback returned zero, meaning that the 316 * placeholder is unknown, then the percent sign is copied, too. 317 * 318 * In order to facilitate caching and to make it possible to give 319 * parameters to the callback, `strbuf_expand()` passes a context pointer, 320 * which can be used by the programmer of the callback as she sees fit. 321 */ 322typedef size_t (*expand_fn_t) (struct strbuf *sb, 323 const char *placeholder, 324 void *context); 325void strbuf_expand(struct strbuf *sb, 326 const char *format, 327 expand_fn_t fn, 328 void *context); 329 330/** 331 * Used as callback for `strbuf_expand()`, expects an array of 332 * struct strbuf_expand_dict_entry as context, i.e. pairs of 333 * placeholder and replacement string. The array needs to be 334 * terminated by an entry with placeholder set to NULL. 335 */ 336struct strbuf_expand_dict_entry { 337 const char *placeholder; 338 const char *value; 339}; 340size_t strbuf_expand_dict_cb(struct strbuf *sb, 341 const char *placeholder, 342 void *context); 343 344/** 345 * Append the contents of one strbuf to another, quoting any 346 * percent signs ("%") into double-percents ("%%") in the 347 * destination. This is useful for literal data to be fed to either 348 * strbuf_expand or to the *printf family of functions. 349 */ 350void strbuf_addbuf_percentquote(struct strbuf *dst, const struct strbuf *src); 351 352/** 353 * Append the given byte size as a human-readable string (i.e. 12.23 KiB, 354 * 3.50 MiB). 355 */ 356void strbuf_humanise_bytes(struct strbuf *buf, off_t bytes); 357 358/** 359 * Add a formatted string to the buffer. 360 */ 361__attribute__((format (printf,2,3))) 362void strbuf_addf(struct strbuf *sb, const char *fmt, ...); 363 364/** 365 * Add a formatted string prepended by a comment character and a 366 * blank to the buffer. 367 */ 368__attribute__((format (printf, 2, 3))) 369void strbuf_commented_addf(struct strbuf *sb, const char *fmt, ...); 370 371__attribute__((format (printf,2,0))) 372void strbuf_vaddf(struct strbuf *sb, const char *fmt, va_list ap); 373 374/** 375 * Add the time specified by `tm`, as formatted by `strftime`. 376 * `tz_offset` is in decimal hhmm format, e.g. -600 means six hours west 377 * of Greenwich, and it's used to expand %z internally. However, tokens 378 * with modifiers (e.g. %Ez) are passed to `strftime`. 379 * `suppress_tz_name`, when set, expands %Z internally to the empty 380 * string rather than passing it to `strftime`. 381 */ 382void strbuf_addftime(struct strbuf *sb, const char *fmt, 383 const struct tm *tm, int tz_offset, 384 int suppress_tz_name); 385 386/** 387 * Read a given size of data from a FILE* pointer to the buffer. 388 * 389 * NOTE: The buffer is rewound if the read fails. If -1 is returned, 390 * `errno` must be consulted, like you would do for `read(3)`. 391 * `strbuf_read()`, `strbuf_read_file()` and `strbuf_getline_*()` 392 * family of functions have the same behaviour as well. 393 */ 394size_t strbuf_fread(struct strbuf *sb, size_t size, FILE *file); 395 396/** 397 * Read the contents of a given file descriptor. The third argument can be 398 * used to give a hint about the file size, to avoid reallocs. If read fails, 399 * any partial read is undone. 400 */ 401ssize_t strbuf_read(struct strbuf *sb, int fd, size_t hint); 402 403/** 404 * Read the contents of a given file descriptor partially by using only one 405 * attempt of xread. The third argument can be used to give a hint about the 406 * file size, to avoid reallocs. Returns the number of new bytes appended to 407 * the sb. 408 */ 409ssize_t strbuf_read_once(struct strbuf *sb, int fd, size_t hint); 410 411/** 412 * Read the contents of a file, specified by its path. The third argument 413 * can be used to give a hint about the file size, to avoid reallocs. 414 * Return the number of bytes read or a negative value if some error 415 * occurred while opening or reading the file. 416 */ 417ssize_t strbuf_read_file(struct strbuf *sb, const char *path, size_t hint); 418 419/** 420 * Read the target of a symbolic link, specified by its path. The third 421 * argument can be used to give a hint about the size, to avoid reallocs. 422 */ 423int strbuf_readlink(struct strbuf *sb, const char *path, size_t hint); 424 425/** 426 * Write the whole content of the strbuf to the stream not stopping at 427 * NUL bytes. 428 */ 429ssize_t strbuf_write(struct strbuf *sb, FILE *stream); 430 431/** 432 * Read a line from a FILE *, overwriting the existing contents of 433 * the strbuf. The strbuf_getline*() family of functions share 434 * this signature, but have different line termination conventions. 435 * 436 * Reading stops after the terminator or at EOF. The terminator 437 * is removed from the buffer before returning. Returns 0 unless 438 * there was nothing left before EOF, in which case it returns `EOF`. 439 */ 440typedef int (*strbuf_getline_fn)(struct strbuf *, FILE *); 441 442/* Uses LF as the line terminator */ 443int strbuf_getline_lf(struct strbuf *sb, FILE *fp); 444 445/* Uses NUL as the line terminator */ 446int strbuf_getline_nul(struct strbuf *sb, FILE *fp); 447 448/* 449 * Similar to strbuf_getline_lf(), but additionally treats a CR that 450 * comes immediately before the LF as part of the terminator. 451 * This is the most friendly version to be used to read "text" files 452 * that can come from platforms whose native text format is CRLF 453 * terminated. 454 */ 455int strbuf_getline(struct strbuf *sb, FILE *file); 456 457 458/** 459 * Like `strbuf_getline`, but keeps the trailing terminator (if 460 * any) in the buffer. 461 */ 462int strbuf_getwholeline(struct strbuf *sb, FILE *file, int term); 463 464/** 465 * Like `strbuf_getwholeline`, but operates on a file descriptor. 466 * It reads one character at a time, so it is very slow. Do not 467 * use it unless you need the correct position in the file 468 * descriptor. 469 */ 470int strbuf_getwholeline_fd(struct strbuf *sb, int fd, int term); 471 472/** 473 * Set the buffer to the path of the current working directory. 474 */ 475int strbuf_getcwd(struct strbuf *sb); 476 477/** 478 * Add a path to a buffer, converting a relative path to an 479 * absolute one in the process. Symbolic links are not 480 * resolved. 481 */ 482void strbuf_add_absolute_path(struct strbuf *sb, const char *path); 483 484/** 485 * Canonize `path` (make it absolute, resolve symlinks, remove extra 486 * slashes) and append it to `sb`. Die with an informative error 487 * message if there is a problem. 488 * 489 * The directory part of `path` (i.e., everything up to the last 490 * dir_sep) must denote a valid, existing directory, but the last 491 * component need not exist. 492 * 493 * Callers that don't mind links should use the more lightweight 494 * strbuf_add_absolute_path() instead. 495 */ 496void strbuf_add_real_path(struct strbuf *sb, const char *path); 497 498 499/** 500 * Normalize in-place the path contained in the strbuf. See 501 * normalize_path_copy() for details. If an error occurs, the contents of "sb" 502 * are left untouched, and -1 is returned. 503 */ 504int strbuf_normalize_path(struct strbuf *sb); 505 506/** 507 * Strip whitespace from a buffer. The second parameter controls if 508 * comments are considered contents to be removed or not. 509 */ 510void strbuf_stripspace(struct strbuf *buf, int skip_comments); 511 512static inline int strbuf_strip_suffix(struct strbuf *sb, const char *suffix) 513{ 514 if (strip_suffix_mem(sb->buf, &sb->len, suffix)) { 515 strbuf_setlen(sb, sb->len); 516 return 1; 517 } else 518 return 0; 519} 520 521/** 522 * Split str (of length slen) at the specified terminator character. 523 * Return a null-terminated array of pointers to strbuf objects 524 * holding the substrings. The substrings include the terminator, 525 * except for the last substring, which might be unterminated if the 526 * original string did not end with a terminator. If max is positive, 527 * then split the string into at most max substrings (with the last 528 * substring containing everything following the (max-1)th terminator 529 * character). 530 * 531 * The most generic form is `strbuf_split_buf`, which takes an arbitrary 532 * pointer/len buffer. The `_str` variant takes a NUL-terminated string, 533 * the `_max` variant takes a strbuf, and just `strbuf_split` is a convenience 534 * wrapper to drop the `max` parameter. 535 * 536 * For lighter-weight alternatives, see string_list_split() and 537 * string_list_split_in_place(). 538 */ 539struct strbuf **strbuf_split_buf(const char *str, size_t len, 540 int terminator, int max); 541 542static inline struct strbuf **strbuf_split_str(const char *str, 543 int terminator, int max) 544{ 545 return strbuf_split_buf(str, strlen(str), terminator, max); 546} 547 548static inline struct strbuf **strbuf_split_max(const struct strbuf *sb, 549 int terminator, int max) 550{ 551 return strbuf_split_buf(sb->buf, sb->len, terminator, max); 552} 553 554static inline struct strbuf **strbuf_split(const struct strbuf *sb, 555 int terminator) 556{ 557 return strbuf_split_max(sb, terminator, 0); 558} 559 560/* 561 * Adds all strings of a string list to the strbuf, separated by the given 562 * separator. For example, if sep is 563 * ', ' 564 * and slist contains 565 * ['element1', 'element2', ..., 'elementN'], 566 * then write: 567 * 'element1, element2, ..., elementN' 568 * to str. If only one element, just write "element1" to str. 569 */ 570void strbuf_add_separated_string_list(struct strbuf *str, 571 const char *sep, 572 struct string_list *slist); 573 574/** 575 * Free a NULL-terminated list of strbufs (for example, the return 576 * values of the strbuf_split*() functions). 577 */ 578void strbuf_list_free(struct strbuf **list); 579 580/** 581 * Add the abbreviation, as generated by find_unique_abbrev, of `sha1` to 582 * the strbuf `sb`. 583 */ 584void strbuf_add_unique_abbrev(struct strbuf *sb, 585 const struct object_id *oid, 586 int abbrev_len); 587 588/** 589 * Launch the user preferred editor to edit a file and fill the buffer 590 * with the file's contents upon the user completing their editing. The 591 * third argument can be used to set the environment which the editor is 592 * run in. If the buffer is NULL the editor is launched as usual but the 593 * file's contents are not read into the buffer upon completion. 594 */ 595int launch_editor(const char *path, struct strbuf *buffer, 596 const char *const *env); 597 598int launch_sequence_editor(const char *path, struct strbuf *buffer, 599 const char *const *env); 600 601void strbuf_add_lines(struct strbuf *sb, 602 const char *prefix, 603 const char *buf, 604 size_t size); 605 606/** 607 * Append s to sb, with the characters '<', '>', '&' and '"' converted 608 * into XML entities. 609 */ 610void strbuf_addstr_xml_quoted(struct strbuf *sb, 611 const char *s); 612 613/** 614 * "Complete" the contents of `sb` by ensuring that either it ends with the 615 * character `term`, or it is empty. This can be used, for example, 616 * to ensure that text ends with a newline, but without creating an empty 617 * blank line if there is no content in the first place. 618 */ 619static inline void strbuf_complete(struct strbuf *sb, char term) 620{ 621 if (sb->len && sb->buf[sb->len - 1] != term) 622 strbuf_addch(sb, term); 623} 624 625static inline void strbuf_complete_line(struct strbuf *sb) 626{ 627 strbuf_complete(sb, '\n'); 628} 629 630/* 631 * Copy "name" to "sb", expanding any special @-marks as handled by 632 * interpret_branch_name(). The result is a non-qualified branch name 633 * (so "foo" or "origin/master" instead of "refs/heads/foo" or 634 * "refs/remotes/origin/master"). 635 * 636 * Note that the resulting name may not be a syntactically valid refname. 637 * 638 * If "allowed" is non-zero, restrict the set of allowed expansions. See 639 * interpret_branch_name() for details. 640 */ 641void strbuf_branchname(struct strbuf *sb, const char *name, 642 unsigned allowed); 643 644/* 645 * Like strbuf_branchname() above, but confirm that the result is 646 * syntactically valid to be used as a local branch name in refs/heads/. 647 * 648 * The return value is "0" if the result is valid, and "-1" otherwise. 649 */ 650int strbuf_check_branch_ref(struct strbuf *sb, const char *name); 651 652void strbuf_addstr_urlencode(struct strbuf *sb, const char *name, 653 int reserved); 654 655__attribute__((format (printf,1,2))) 656int printf_ln(const char *fmt, ...); 657__attribute__((format (printf,2,3))) 658int fprintf_ln(FILE *fp, const char *fmt, ...); 659 660char *xstrdup_tolower(const char *); 661char *xstrdup_toupper(const char *); 662 663/** 664 * Create a newly allocated string using printf format. You can do this easily 665 * with a strbuf, but this provides a shortcut to save a few lines. 666 */ 667__attribute__((format (printf, 1, 0))) 668char *xstrvfmt(const char *fmt, va_list ap); 669__attribute__((format (printf, 1, 2))) 670char *xstrfmt(const char *fmt, ...); 671 672#endif /* STRBUF_H */