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 { 67size_t alloc; 68size_t len; 69char*buf; 70}; 71 72externchar 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 */ 90voidstrbuf_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 */ 100voidstrbuf_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 */ 120voidstrbuf_attach(struct strbuf *sb,void*str,size_t len,size_t mem); 121 122/** 123 * Swap the contents of two string buffers. 124 */ 125staticinlinevoidstrbuf_swap(struct strbuf *a,struct strbuf *b) 126{ 127SWAP(*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 */ 139staticinlinesize_tstrbuf_avail(const struct strbuf *sb) 140{ 141return 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 */ 151voidstrbuf_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 */ 160staticinlinevoidstrbuf_setlen(struct strbuf *sb,size_t len) 161{ 162if(len > (sb->alloc ? sb->alloc -1:0)) 163die("BUG: strbuf_setlen() beyond buffer"); 164 sb->len = len; 165if(sb->buf != strbuf_slopbuf) 166 sb->buf[len] ='\0'; 167else 168assert(!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 */ 186voidstrbuf_trim(struct strbuf *sb); 187voidstrbuf_rtrim(struct strbuf *sb); 188voidstrbuf_ltrim(struct strbuf *sb); 189 190/* Strip trailing directory separators */ 191voidstrbuf_trim_trailing_dir_sep(struct strbuf *sb); 192 193/* Strip trailing LF or CR/LF */ 194voidstrbuf_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 */ 200intstrbuf_reencode(struct strbuf *sb,const char*from,const char*to); 201 202/** 203 * Lowercase each character in the buffer using `tolower`. 204 */ 205voidstrbuf_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 */ 212intstrbuf_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 */ 228staticinlinevoidstrbuf_addch(struct strbuf *sb,int c) 229{ 230if(!strbuf_avail(sb)) 231strbuf_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 */ 239voidstrbuf_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 */ 245voidstrbuf_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 */ 250voidstrbuf_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 */ 256voidstrbuf_splice(struct strbuf *sb,size_t pos,size_t len, 257const 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 */ 263voidstrbuf_add_commented_lines(struct strbuf *out, 264const char*buf,size_t size); 265 266 267/** 268 * Add data of given length to the buffer. 269 */ 270voidstrbuf_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 */ 281staticinlinevoidstrbuf_addstr(struct strbuf *sb,const char*s) 282{ 283strbuf_add(sb, s,strlen(s)); 284} 285 286/** 287 * Copy the contents of another buffer at the end of the current one. 288 */ 289voidstrbuf_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, 296const 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 */ 322typedefsize_t(*expand_fn_t) (struct strbuf *sb, 323const char*placeholder, 324void*context); 325voidstrbuf_expand(struct strbuf *sb, 326const char*format, 327 expand_fn_t fn, 328void*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 { 337const char*placeholder; 338const char*value; 339}; 340size_tstrbuf_expand_dict_cb(struct strbuf *sb, 341const char*placeholder, 342void*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 */ 350voidstrbuf_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 */ 356voidstrbuf_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))) 362voidstrbuf_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))) 369voidstrbuf_commented_addf(struct strbuf *sb,const char*fmt, ...); 370 371__attribute__((format(printf,2,0))) 372voidstrbuf_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 */ 382voidstrbuf_addftime(struct strbuf *sb,const char*fmt, 383const struct tm *tm,int tz_offset, 384int 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_tstrbuf_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 */ 423intstrbuf_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 */ 440typedefint(*strbuf_getline_fn)(struct strbuf *,FILE*); 441 442/* Uses LF as the line terminator */ 443intstrbuf_getline_lf(struct strbuf *sb,FILE*fp); 444 445/* Uses NUL as the line terminator */ 446intstrbuf_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 */ 455intstrbuf_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 */ 462intstrbuf_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 */ 470intstrbuf_getwholeline_fd(struct strbuf *sb,int fd,int term); 471 472/** 473 * Set the buffer to the path of the current working directory. 474 */ 475intstrbuf_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 */ 482voidstrbuf_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 */ 496voidstrbuf_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 */ 504intstrbuf_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 */ 510voidstrbuf_stripspace(struct strbuf *buf,int skip_comments); 511 512staticinlineintstrbuf_strip_suffix(struct strbuf *sb,const char*suffix) 513{ 514if(strip_suffix_mem(sb->buf, &sb->len, suffix)) { 515strbuf_setlen(sb, sb->len); 516return1; 517}else 518return0; 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, 540int terminator,int max); 541 542staticinlinestruct strbuf **strbuf_split_str(const char*str, 543int terminator,int max) 544{ 545returnstrbuf_split_buf(str,strlen(str), terminator, max); 546} 547 548staticinlinestruct strbuf **strbuf_split_max(const struct strbuf *sb, 549int terminator,int max) 550{ 551returnstrbuf_split_buf(sb->buf, sb->len, terminator, max); 552} 553 554staticinlinestruct strbuf **strbuf_split(const struct strbuf *sb, 555int terminator) 556{ 557returnstrbuf_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 */ 570voidstrbuf_add_separated_string_list(struct strbuf *str, 571const char*sep, 572struct 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 */ 578voidstrbuf_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 */ 584voidstrbuf_add_unique_abbrev(struct strbuf *sb, 585const struct object_id *oid, 586int 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 */ 595intlaunch_editor(const char*path,struct strbuf *buffer, 596const char*const*env); 597 598intlaunch_sequence_editor(const char*path,struct strbuf *buffer, 599const char*const*env); 600 601voidstrbuf_add_lines(struct strbuf *sb, 602const char*prefix, 603const char*buf, 604size_t size); 605 606/** 607 * Append s to sb, with the characters '<', '>', '&' and '"' converted 608 * into XML entities. 609 */ 610voidstrbuf_addstr_xml_quoted(struct strbuf *sb, 611const 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 */ 619staticinlinevoidstrbuf_complete(struct strbuf *sb,char term) 620{ 621if(sb->len && sb->buf[sb->len -1] != term) 622strbuf_addch(sb, term); 623} 624 625staticinlinevoidstrbuf_complete_line(struct strbuf *sb) 626{ 627strbuf_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 */ 641voidstrbuf_branchname(struct strbuf *sb,const char*name, 642unsigned 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 */ 650intstrbuf_check_branch_ref(struct strbuf *sb,const char*name); 651 652voidstrbuf_addstr_urlencode(struct strbuf *sb,const char*name, 653int reserved); 654 655__attribute__((format(printf,1,2))) 656intprintf_ln(const char*fmt, ...); 657__attribute__((format(printf,2,3))) 658intfprintf_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 */