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