Junio C Hamano | d1df574 | 2005-04-25 18:26:45 -0700 | [diff] [blame] | 1 | #ifndef STRBUF_H |
| 2 | #define STRBUF_H |
Pierre Habouzit | b449f4c | 2007-09-06 13:20:05 +0200 | [diff] [blame] | 3 | |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 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 | * |
Jeff King | aa07cac | 2015-01-16 04:05:10 -0500 | [diff] [blame] | 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. |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 19 | * |
Jeff King | aa07cac | 2015-01-16 04:05:10 -0500 | [diff] [blame] | 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 | * |
Jeff King | 088c9a8 | 2015-01-16 04:05:16 -0500 | [diff] [blame] | 36 | * strbuf_grow(sb, SOME_SIZE); <1> |
| 37 | * strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE); |
| 38 | * |
Jeff King | aa07cac | 2015-01-16 04:05:10 -0500 | [diff] [blame] | 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 | */ |
Pierre Habouzit | b449f4c | 2007-09-06 13:20:05 +0200 | [diff] [blame] | 53 | |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 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 | */ |
Junio C Hamano | d1df574 | 2005-04-25 18:26:45 -0700 | [diff] [blame] | 64 | struct strbuf { |
Pierre Habouzit | b449f4c | 2007-09-06 13:20:05 +0200 | [diff] [blame] | 65 | size_t alloc; |
| 66 | size_t len; |
Brian Gerst | bf0f910 | 2005-05-18 08:14:09 -0400 | [diff] [blame] | 67 | char *buf; |
Junio C Hamano | d1df574 | 2005-04-25 18:26:45 -0700 | [diff] [blame] | 68 | }; |
| 69 | |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 70 | extern char strbuf_slopbuf[]; |
Pierre Habouzit | b315c5c | 2007-09-27 12:58:23 +0200 | [diff] [blame] | 71 | #define STRBUF_INIT { 0, 0, strbuf_slopbuf } |
Pierre Habouzit | b449f4c | 2007-09-06 13:20:05 +0200 | [diff] [blame] | 72 | |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 73 | /** |
Jeff King | 14e2177 | 2015-01-16 04:05:28 -0500 | [diff] [blame] | 74 | * Life Cycle Functions |
| 75 | * -------------------- |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 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 | */ |
Pierre Habouzit | f1696ee | 2007-09-10 12:35:04 +0200 | [diff] [blame] | 82 | extern void strbuf_init(struct strbuf *, size_t); |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 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 | */ |
Pierre Habouzit | b449f4c | 2007-09-06 13:20:05 +0200 | [diff] [blame] | 88 | extern void strbuf_release(struct strbuf *); |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 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 | */ |
Pierre Habouzit | b315c5c | 2007-09-27 12:58:23 +0200 | [diff] [blame] | 95 | extern char *strbuf_detach(struct strbuf *, size_t *); |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 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 | */ |
Pierre Habouzit | 917c9a7 | 2007-09-15 15:56:50 +0200 | [diff] [blame] | 105 | extern void strbuf_attach(struct strbuf *, void *, size_t, size_t); |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 106 | |
| 107 | /** |
| 108 | * Swap the contents of two string buffers. |
| 109 | */ |
Nguyễn Thái Ngọc Duy | 187e290 | 2014-03-01 09:50:55 +0700 | [diff] [blame] | 110 | static inline void strbuf_swap(struct strbuf *a, struct strbuf *b) |
| 111 | { |
Pierre Habouzit | c76689d | 2007-09-20 00:42:12 +0200 | [diff] [blame] | 112 | struct strbuf tmp = *a; |
| 113 | *a = *b; |
| 114 | *b = tmp; |
| 115 | } |
Pierre Habouzit | b449f4c | 2007-09-06 13:20:05 +0200 | [diff] [blame] | 116 | |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 117 | |
| 118 | /** |
Jeff King | 14e2177 | 2015-01-16 04:05:28 -0500 | [diff] [blame] | 119 | * Functions related to the size of the buffer |
| 120 | * ------------------------------------------- |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 121 | */ |
| 122 | |
| 123 | /** |
| 124 | * Determine the amount of allocated but unused memory. |
| 125 | */ |
Nguyễn Thái Ngọc Duy | 187e290 | 2014-03-01 09:50:55 +0700 | [diff] [blame] | 126 | static inline size_t strbuf_avail(const struct strbuf *sb) |
| 127 | { |
Pierre Habouzit | c76689d | 2007-09-20 00:42:12 +0200 | [diff] [blame] | 128 | return sb->alloc ? sb->alloc - sb->len - 1 : 0; |
Pierre Habouzit | b449f4c | 2007-09-06 13:20:05 +0200 | [diff] [blame] | 129 | } |
Junio C Hamano | a8f3e22 | 2007-09-26 02:26:06 -0700 | [diff] [blame] | 130 | |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 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 | */ |
Junio C Hamano | a8f3e22 | 2007-09-26 02:26:06 -0700 | [diff] [blame] | 138 | extern void strbuf_grow(struct strbuf *, size_t); |
| 139 | |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 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 | */ |
Nguyễn Thái Ngọc Duy | 187e290 | 2014-03-01 09:50:55 +0700 | [diff] [blame] | 147 | static inline void strbuf_setlen(struct strbuf *sb, size_t len) |
| 148 | { |
René Scharfe | 7141efa | 2011-04-27 19:24:50 +0200 | [diff] [blame] | 149 | if (len > (sb->alloc ? sb->alloc - 1 : 0)) |
| 150 | die("BUG: strbuf_setlen() beyond buffer"); |
Pierre Habouzit | c76689d | 2007-09-20 00:42:12 +0200 | [diff] [blame] | 151 | sb->len = len; |
| 152 | sb->buf[len] = '\0'; |
Pierre Habouzit | b449f4c | 2007-09-06 13:20:05 +0200 | [diff] [blame] | 153 | } |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 154 | |
| 155 | /** |
| 156 | * Empty the buffer by setting the size of it to zero. |
| 157 | */ |
Pierre Habouzit | b315c5c | 2007-09-27 12:58:23 +0200 | [diff] [blame] | 158 | #define strbuf_reset(sb) strbuf_setlen(sb, 0) |
Pierre Habouzit | b449f4c | 2007-09-06 13:20:05 +0200 | [diff] [blame] | 159 | |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 160 | |
| 161 | /** |
Jeff King | 14e2177 | 2015-01-16 04:05:28 -0500 | [diff] [blame] | 162 | * Functions related to the contents of the buffer |
| 163 | * ----------------------------------------------- |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 164 | */ |
| 165 | |
| 166 | /** |
Jeff King | d468fa2 | 2015-01-16 04:06:04 -0500 | [diff] [blame] | 167 | * Strip whitespace from the beginning (`ltrim`), end (`rtrim`), or both side |
| 168 | * (`trim`) of a string. |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 169 | */ |
Lukas Sandström | eacd6dc | 2008-07-13 20:29:18 +0200 | [diff] [blame] | 170 | extern void strbuf_trim(struct strbuf *); |
Pierre Habouzit | f1696ee | 2007-09-10 12:35:04 +0200 | [diff] [blame] | 171 | extern void strbuf_rtrim(struct strbuf *); |
Lukas Sandström | eacd6dc | 2008-07-13 20:29:18 +0200 | [diff] [blame] | 172 | extern void strbuf_ltrim(struct strbuf *); |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 173 | |
| 174 | /** |
| 175 | * Replace the contents of the strbuf with a reencoded form. Returns -1 |
| 176 | * on error, 0 on success. |
| 177 | */ |
Jeff King | d4241f5 | 2014-05-22 05:30:14 -0400 | [diff] [blame] | 178 | extern int strbuf_reencode(struct strbuf *sb, const char *from, const char *to); |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 179 | |
| 180 | /** |
| 181 | * Lowercase each character in the buffer using `tolower`. |
| 182 | */ |
Jeff King | ffb20ce | 2014-05-23 16:03:47 -0400 | [diff] [blame] | 183 | extern void strbuf_tolower(struct strbuf *sb); |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 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 | */ |
Lukas Sandström | 9b200fd | 2008-07-13 20:28:24 +0200 | [diff] [blame] | 190 | extern int strbuf_cmp(const struct strbuf *, const struct strbuf *); |
Lukas Sandström | eacd6dc | 2008-07-13 20:29:18 +0200 | [diff] [blame] | 191 | |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 192 | |
| 193 | /** |
Jeff King | 14e2177 | 2015-01-16 04:05:28 -0500 | [diff] [blame] | 194 | * Adding data to the buffer |
| 195 | * ------------------------- |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 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 | */ |
| 206 | static inline void strbuf_addch(struct strbuf *sb, int c) |
| 207 | { |
Jeff King | fec501d | 2015-04-16 04:53:56 -0400 | [diff] [blame] | 208 | if (!strbuf_avail(sb)) |
| 209 | strbuf_grow(sb, 1); |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 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 | */ |
| 217 | extern 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 | */ |
| 223 | extern 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 | */ |
| 228 | extern 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 | */ |
| 234 | extern 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 | */ |
| 241 | extern 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 | */ |
| 247 | extern 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 | * |
Jeff King | 088c9a8 | 2015-01-16 04:05:16 -0500 | [diff] [blame] | 255 | * strbuf_addstr(sb, "immediate string"); |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 256 | * |
| 257 | */ |
| 258 | static 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 | */ |
René Scharfe | 31471ba | 2016-07-21 18:46:44 +0200 | [diff] [blame] | 266 | extern void strbuf_addbuf(struct strbuf *sb, const struct strbuf *sb2); |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 267 | |
| 268 | /** |
| 269 | * Copy part of the buffer from a given position till a given length to the |
| 270 | * end of the buffer. |
| 271 | */ |
| 272 | extern void strbuf_adddup(struct strbuf *sb, size_t pos, size_t len); |
| 273 | |
| 274 | /** |
| 275 | * This function can be used to expand a format string containing |
| 276 | * placeholders. To that end, it parses the string and calls the specified |
| 277 | * function for every percent sign found. |
| 278 | * |
| 279 | * The callback function is given a pointer to the character after the `%` |
| 280 | * and a pointer to the struct strbuf. It is expected to add the expanded |
| 281 | * version of the placeholder to the strbuf, e.g. to add a newline |
| 282 | * character if the letter `n` appears after a `%`. The function returns |
| 283 | * the length of the placeholder recognized and `strbuf_expand()` skips |
| 284 | * over it. |
| 285 | * |
| 286 | * The format `%%` is automatically expanded to a single `%` as a quoting |
| 287 | * mechanism; callers do not need to handle the `%` placeholder themselves, |
| 288 | * and the callback function will not be invoked for this placeholder. |
| 289 | * |
| 290 | * All other characters (non-percent and not skipped ones) are copied |
| 291 | * verbatim to the strbuf. If the callback returned zero, meaning that the |
| 292 | * placeholder is unknown, then the percent sign is copied, too. |
| 293 | * |
| 294 | * In order to facilitate caching and to make it possible to give |
| 295 | * parameters to the callback, `strbuf_expand()` passes a context pointer, |
| 296 | * which can be used by the programmer of the callback as she sees fit. |
| 297 | */ |
| 298 | typedef size_t (*expand_fn_t) (struct strbuf *sb, const char *placeholder, void *context); |
| 299 | extern void strbuf_expand(struct strbuf *sb, const char *format, expand_fn_t fn, void *context); |
| 300 | |
| 301 | /** |
| 302 | * Used as callback for `strbuf_expand()`, expects an array of |
| 303 | * struct strbuf_expand_dict_entry as context, i.e. pairs of |
| 304 | * placeholder and replacement string. The array needs to be |
| 305 | * terminated by an entry with placeholder set to NULL. |
| 306 | */ |
| 307 | struct strbuf_expand_dict_entry { |
| 308 | const char *placeholder; |
| 309 | const char *value; |
| 310 | }; |
| 311 | extern size_t strbuf_expand_dict_cb(struct strbuf *sb, const char *placeholder, void *context); |
| 312 | |
| 313 | /** |
| 314 | * Append the contents of one strbuf to another, quoting any |
| 315 | * percent signs ("%") into double-percents ("%%") in the |
| 316 | * destination. This is useful for literal data to be fed to either |
| 317 | * strbuf_expand or to the *printf family of functions. |
| 318 | */ |
| 319 | extern void strbuf_addbuf_percentquote(struct strbuf *dst, const struct strbuf *src); |
| 320 | |
| 321 | /** |
| 322 | * Append the given byte size as a human-readable string (i.e. 12.23 KiB, |
| 323 | * 3.50 MiB). |
| 324 | */ |
| 325 | extern void strbuf_humanise_bytes(struct strbuf *buf, off_t bytes); |
| 326 | |
| 327 | /** |
| 328 | * Add a formatted string to the buffer. |
| 329 | */ |
| 330 | __attribute__((format (printf,2,3))) |
| 331 | extern void strbuf_addf(struct strbuf *sb, const char *fmt, ...); |
| 332 | |
| 333 | /** |
| 334 | * Add a formatted string prepended by a comment character and a |
| 335 | * blank to the buffer. |
| 336 | */ |
| 337 | __attribute__((format (printf, 2, 3))) |
| 338 | extern void strbuf_commented_addf(struct strbuf *sb, const char *fmt, ...); |
| 339 | |
| 340 | __attribute__((format (printf,2,0))) |
| 341 | extern void strbuf_vaddf(struct strbuf *sb, const char *fmt, va_list ap); |
| 342 | |
| 343 | /** |
Jeff King | aa1462c | 2015-06-25 12:55:45 -0400 | [diff] [blame] | 344 | * Add the time specified by `tm`, as formatted by `strftime`. |
| 345 | */ |
| 346 | extern void strbuf_addftime(struct strbuf *sb, const char *fmt, const struct tm *tm); |
| 347 | |
| 348 | /** |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 349 | * Read a given size of data from a FILE* pointer to the buffer. |
| 350 | * |
| 351 | * NOTE: The buffer is rewound if the read fails. If -1 is returned, |
| 352 | * `errno` must be consulted, like you would do for `read(3)`. |
Junio C Hamano | 1a0c8df | 2016-01-13 18:32:23 -0800 | [diff] [blame] | 353 | * `strbuf_read()`, `strbuf_read_file()` and `strbuf_getline_*()` |
| 354 | * family of functions have the same behaviour as well. |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 355 | */ |
| 356 | extern size_t strbuf_fread(struct strbuf *, size_t, FILE *); |
| 357 | |
| 358 | /** |
| 359 | * Read the contents of a given file descriptor. The third argument can be |
| 360 | * used to give a hint about the file size, to avoid reallocs. If read fails, |
| 361 | * any partial read is undone. |
| 362 | */ |
| 363 | extern ssize_t strbuf_read(struct strbuf *, int fd, size_t hint); |
| 364 | |
| 365 | /** |
Stefan Beller | b4e04fb | 2015-12-15 16:04:08 -0800 | [diff] [blame] | 366 | * Read the contents of a given file descriptor partially by using only one |
| 367 | * attempt of xread. The third argument can be used to give a hint about the |
| 368 | * file size, to avoid reallocs. Returns the number of new bytes appended to |
| 369 | * the sb. |
| 370 | */ |
| 371 | extern ssize_t strbuf_read_once(struct strbuf *, int fd, size_t hint); |
| 372 | |
| 373 | /** |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 374 | * Read the contents of a file, specified by its path. The third argument |
| 375 | * can be used to give a hint about the file size, to avoid reallocs. |
Pranit Bauva | ed008d7 | 2016-06-14 11:44:11 +0530 | [diff] [blame] | 376 | * Return the number of bytes read or a negative value if some error |
| 377 | * occurred while opening or reading the file. |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 378 | */ |
Michael Haggerty | 6c8afe4 | 2015-07-03 15:59:32 +0200 | [diff] [blame] | 379 | extern ssize_t strbuf_read_file(struct strbuf *sb, const char *path, size_t hint); |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 380 | |
| 381 | /** |
| 382 | * Read the target of a symbolic link, specified by its path. The third |
| 383 | * argument can be used to give a hint about the size, to avoid reallocs. |
| 384 | */ |
| 385 | extern int strbuf_readlink(struct strbuf *sb, const char *path, size_t hint); |
| 386 | |
| 387 | /** |
Stefan Beller | 2dac9b5 | 2016-02-29 18:07:15 -0800 | [diff] [blame] | 388 | * Write the whole content of the strbuf to the stream not stopping at |
| 389 | * NUL bytes. |
| 390 | */ |
| 391 | extern ssize_t strbuf_write(struct strbuf *sb, FILE *stream); |
| 392 | |
| 393 | /** |
Junio C Hamano | 1a0c8df | 2016-01-13 18:32:23 -0800 | [diff] [blame] | 394 | * Read a line from a FILE *, overwriting the existing contents of |
| 395 | * the strbuf. The strbuf_getline*() family of functions share |
| 396 | * this signature, but have different line termination conventions. |
| 397 | * |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 398 | * Reading stops after the terminator or at EOF. The terminator |
| 399 | * is removed from the buffer before returning. Returns 0 unless |
| 400 | * there was nothing left before EOF, in which case it returns `EOF`. |
| 401 | */ |
Junio C Hamano | 8f309ae | 2016-01-13 15:31:17 -0800 | [diff] [blame] | 402 | typedef int (*strbuf_getline_fn)(struct strbuf *, FILE *); |
| 403 | |
| 404 | /* Uses LF as the line terminator */ |
| 405 | extern int strbuf_getline_lf(struct strbuf *sb, FILE *fp); |
| 406 | |
| 407 | /* Uses NUL as the line terminator */ |
| 408 | extern int strbuf_getline_nul(struct strbuf *sb, FILE *fp); |
| 409 | |
Junio C Hamano | c8aa9fd | 2015-10-28 13:17:29 -0700 | [diff] [blame] | 410 | /* |
Junio C Hamano | 8f309ae | 2016-01-13 15:31:17 -0800 | [diff] [blame] | 411 | * Similar to strbuf_getline_lf(), but additionally treats a CR that |
| 412 | * comes immediately before the LF as part of the terminator. |
Junio C Hamano | 1a0c8df | 2016-01-13 18:32:23 -0800 | [diff] [blame] | 413 | * This is the most friendly version to be used to read "text" files |
| 414 | * that can come from platforms whose native text format is CRLF |
| 415 | * terminated. |
Junio C Hamano | c8aa9fd | 2015-10-28 13:17:29 -0700 | [diff] [blame] | 416 | */ |
Junio C Hamano | 1a0c8df | 2016-01-13 18:32:23 -0800 | [diff] [blame] | 417 | extern int strbuf_getline(struct strbuf *, FILE *); |
Junio C Hamano | c8aa9fd | 2015-10-28 13:17:29 -0700 | [diff] [blame] | 418 | |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 419 | |
| 420 | /** |
| 421 | * Like `strbuf_getline`, but keeps the trailing terminator (if |
| 422 | * any) in the buffer. |
| 423 | */ |
| 424 | extern int strbuf_getwholeline(struct strbuf *, FILE *, int); |
| 425 | |
| 426 | /** |
| 427 | * Like `strbuf_getwholeline`, but operates on a file descriptor. |
| 428 | * It reads one character at a time, so it is very slow. Do not |
| 429 | * use it unless you need the correct position in the file |
| 430 | * descriptor. |
| 431 | */ |
| 432 | extern int strbuf_getwholeline_fd(struct strbuf *, int, int); |
| 433 | |
| 434 | /** |
| 435 | * Set the buffer to the path of the current working directory. |
| 436 | */ |
| 437 | extern int strbuf_getcwd(struct strbuf *sb); |
| 438 | |
| 439 | /** |
| 440 | * Add a path to a buffer, converting a relative path to an |
| 441 | * absolute one in the process. Symbolic links are not |
| 442 | * resolved. |
| 443 | */ |
| 444 | extern void strbuf_add_absolute_path(struct strbuf *sb, const char *path); |
| 445 | |
Jeff King | 670c359 | 2016-10-03 16:34:17 -0400 | [diff] [blame] | 446 | |
| 447 | /** |
| 448 | * Normalize in-place the path contained in the strbuf. See |
| 449 | * normalize_path_copy() for details. If an error occurs, the contents of "sb" |
| 450 | * are left untouched, and -1 is returned. |
| 451 | */ |
| 452 | extern int strbuf_normalize_path(struct strbuf *sb); |
| 453 | |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 454 | /** |
| 455 | * Strip whitespace from a buffer. The second parameter controls if |
| 456 | * comments are considered contents to be removed or not. |
| 457 | */ |
Tobias Klauser | 63af4a8 | 2015-10-16 17:16:42 +0200 | [diff] [blame] | 458 | extern void strbuf_stripspace(struct strbuf *buf, int skip_comments); |
| 459 | |
| 460 | /** |
| 461 | * Temporary alias until all topic branches have switched to use |
| 462 | * strbuf_stripspace directly. |
| 463 | */ |
| 464 | static inline void stripspace(struct strbuf *buf, int skip_comments) |
| 465 | { |
| 466 | strbuf_stripspace(buf, skip_comments); |
| 467 | } |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 468 | |
Jeff King | 6dda4e6 | 2014-06-30 13:01:51 -0400 | [diff] [blame] | 469 | static inline int strbuf_strip_suffix(struct strbuf *sb, const char *suffix) |
| 470 | { |
| 471 | if (strip_suffix_mem(sb->buf, &sb->len, suffix)) { |
| 472 | strbuf_setlen(sb, sb->len); |
| 473 | return 1; |
| 474 | } else |
| 475 | return 0; |
| 476 | } |
| 477 | |
Stefan Beller | 6afbbdd | 2015-01-16 04:04:51 -0500 | [diff] [blame] | 478 | /** |
Michael Haggerty | 06379a6 | 2012-11-04 07:46:54 +0100 | [diff] [blame] | 479 | * Split str (of length slen) at the specified terminator character. |
| 480 | * Return a null-terminated array of pointers to strbuf objects |
| 481 | * holding the substrings. The substrings include the terminator, |
| 482 | * except for the last substring, which might be unterminated if the |
| 483 | * original string did not end with a terminator. If max is positive, |
| 484 | * then split the string into at most max substrings (with the last |
| 485 | * substring containing everything following the (max-1)th terminator |
| 486 | * character). |
| 487 | * |
Jeff King | f20e56e | 2015-01-16 04:05:57 -0500 | [diff] [blame] | 488 | * The most generic form is `strbuf_split_buf`, which takes an arbitrary |
| 489 | * pointer/len buffer. The `_str` variant takes a NUL-terminated string, |
| 490 | * the `_max` variant takes a strbuf, and just `strbuf_split` is a convenience |
| 491 | * wrapper to drop the `max` parameter. |
| 492 | * |
Michael Haggerty | 06379a6 | 2012-11-04 07:46:54 +0100 | [diff] [blame] | 493 | * For lighter-weight alternatives, see string_list_split() and |
| 494 | * string_list_split_in_place(). |
| 495 | */ |
Jeff King | 2f1d9e2 | 2011-06-09 11:54:58 -0400 | [diff] [blame] | 496 | extern struct strbuf **strbuf_split_buf(const char *, size_t, |
Michael Haggerty | 17b73dc | 2012-11-04 07:46:53 +0100 | [diff] [blame] | 497 | int terminator, int max); |
Michael Haggerty | 06379a6 | 2012-11-04 07:46:54 +0100 | [diff] [blame] | 498 | |
Jeff King | 2f1d9e2 | 2011-06-09 11:54:58 -0400 | [diff] [blame] | 499 | static inline struct strbuf **strbuf_split_str(const char *str, |
Michael Haggerty | 17b73dc | 2012-11-04 07:46:53 +0100 | [diff] [blame] | 500 | int terminator, int max) |
Jeff King | 2f1d9e2 | 2011-06-09 11:54:58 -0400 | [diff] [blame] | 501 | { |
Michael Haggerty | 17b73dc | 2012-11-04 07:46:53 +0100 | [diff] [blame] | 502 | return strbuf_split_buf(str, strlen(str), terminator, max); |
Jeff King | 2f1d9e2 | 2011-06-09 11:54:58 -0400 | [diff] [blame] | 503 | } |
Michael Haggerty | 06379a6 | 2012-11-04 07:46:54 +0100 | [diff] [blame] | 504 | |
Jeff King | 2f1d9e2 | 2011-06-09 11:54:58 -0400 | [diff] [blame] | 505 | static inline struct strbuf **strbuf_split_max(const struct strbuf *sb, |
Michael Haggerty | 17b73dc | 2012-11-04 07:46:53 +0100 | [diff] [blame] | 506 | int terminator, int max) |
Jeff King | 2f1d9e2 | 2011-06-09 11:54:58 -0400 | [diff] [blame] | 507 | { |
Michael Haggerty | 17b73dc | 2012-11-04 07:46:53 +0100 | [diff] [blame] | 508 | return strbuf_split_buf(sb->buf, sb->len, terminator, max); |
Jeff King | 2f1d9e2 | 2011-06-09 11:54:58 -0400 | [diff] [blame] | 509 | } |
Michael Haggerty | 06379a6 | 2012-11-04 07:46:54 +0100 | [diff] [blame] | 510 | |
Michael Haggerty | 17b73dc | 2012-11-04 07:46:53 +0100 | [diff] [blame] | 511 | static inline struct strbuf **strbuf_split(const struct strbuf *sb, |
| 512 | int terminator) |
Jeff King | 28fc3a6 | 2011-06-09 11:51:22 -0400 | [diff] [blame] | 513 | { |
Michael Haggerty | 17b73dc | 2012-11-04 07:46:53 +0100 | [diff] [blame] | 514 | return strbuf_split_max(sb, terminator, 0); |
Jeff King | 28fc3a6 | 2011-06-09 11:51:22 -0400 | [diff] [blame] | 515 | } |
Michael Haggerty | 06379a6 | 2012-11-04 07:46:54 +0100 | [diff] [blame] | 516 | |
Stefan Beller | 6afbbdd | 2015-01-16 04:04:51 -0500 | [diff] [blame] | 517 | /** |
Michael Haggerty | 06379a6 | 2012-11-04 07:46:54 +0100 | [diff] [blame] | 518 | * Free a NULL-terminated list of strbufs (for example, the return |
| 519 | * values of the strbuf_split*() functions). |
| 520 | */ |
Lukas Sandström | eacd6dc | 2008-07-13 20:29:18 +0200 | [diff] [blame] | 521 | extern void strbuf_list_free(struct strbuf **); |
Pierre Habouzit | f1696ee | 2007-09-10 12:35:04 +0200 | [diff] [blame] | 522 | |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 523 | /** |
Jeff King | af49c6d | 2015-09-24 17:05:45 -0400 | [diff] [blame] | 524 | * Add the abbreviation, as generated by find_unique_abbrev, of `sha1` to |
| 525 | * the strbuf `sb`. |
| 526 | */ |
| 527 | extern void strbuf_add_unique_abbrev(struct strbuf *sb, |
| 528 | const unsigned char *sha1, |
| 529 | int abbrev_len); |
| 530 | |
| 531 | /** |
Jeff King | bdfdaa4 | 2015-01-16 04:04:04 -0500 | [diff] [blame] | 532 | * Launch the user preferred editor to edit a file and fill the buffer |
| 533 | * with the file's contents upon the user completing their editing. The |
| 534 | * third argument can be used to set the environment which the editor is |
| 535 | * run in. If the buffer is NULL the editor is launched as usual but the |
| 536 | * file's contents are not read into the buffer upon completion. |
| 537 | */ |
| 538 | extern int launch_editor(const char *path, struct strbuf *buffer, const char *const *env); |
Pierre Habouzit | b449f4c | 2007-09-06 13:20:05 +0200 | [diff] [blame] | 539 | |
Junio C Hamano | 895680f | 2011-11-04 21:06:30 -0700 | [diff] [blame] | 540 | extern void strbuf_add_lines(struct strbuf *sb, const char *prefix, const char *buf, size_t size); |
| 541 | |
Stefan Beller | 6afbbdd | 2015-01-16 04:04:51 -0500 | [diff] [blame] | 542 | /** |
Michael Haggerty | 5963c03 | 2012-11-25 12:08:34 +0100 | [diff] [blame] | 543 | * Append s to sb, with the characters '<', '>', '&' and '"' converted |
| 544 | * into XML entities. |
| 545 | */ |
| 546 | extern void strbuf_addstr_xml_quoted(struct strbuf *sb, const char *s); |
| 547 | |
Jeff King | 399ad55 | 2015-09-24 17:05:43 -0400 | [diff] [blame] | 548 | /** |
| 549 | * "Complete" the contents of `sb` by ensuring that either it ends with the |
| 550 | * character `term`, or it is empty. This can be used, for example, |
| 551 | * to ensure that text ends with a newline, but without creating an empty |
| 552 | * blank line if there is no content in the first place. |
| 553 | */ |
| 554 | static inline void strbuf_complete(struct strbuf *sb, char term) |
| 555 | { |
| 556 | if (sb->len && sb->buf[sb->len - 1] != term) |
| 557 | strbuf_addch(sb, term); |
| 558 | } |
| 559 | |
Junio C Hamano | 895680f | 2011-11-04 21:06:30 -0700 | [diff] [blame] | 560 | static inline void strbuf_complete_line(struct strbuf *sb) |
| 561 | { |
Jeff King | 399ad55 | 2015-09-24 17:05:43 -0400 | [diff] [blame] | 562 | strbuf_complete(sb, '\n'); |
Junio C Hamano | 895680f | 2011-11-04 21:06:30 -0700 | [diff] [blame] | 563 | } |
| 564 | |
Junio C Hamano | a552de7 | 2009-03-21 13:17:30 -0700 | [diff] [blame] | 565 | extern int strbuf_branchname(struct strbuf *sb, const char *name); |
Junio C Hamano | a2fab53 | 2009-03-21 14:35:51 -0700 | [diff] [blame] | 566 | extern int strbuf_check_branch_ref(struct strbuf *sb, const char *name); |
Junio C Hamano | a552de7 | 2009-03-21 13:17:30 -0700 | [diff] [blame] | 567 | |
Jeff King | c505116 | 2011-12-10 05:34:20 -0500 | [diff] [blame] | 568 | extern void strbuf_addstr_urlencode(struct strbuf *, const char *, |
| 569 | int reserved); |
René Scharfe | 679eebe | 2014-07-28 20:33:55 +0200 | [diff] [blame] | 570 | |
Nguyễn Thái Ngọc Duy | 9a0a30a | 2012-04-23 19:30:22 +0700 | [diff] [blame] | 571 | __attribute__((format (printf,1,2))) |
| 572 | extern int printf_ln(const char *fmt, ...); |
| 573 | __attribute__((format (printf,2,3))) |
| 574 | extern int fprintf_ln(FILE *fp, const char *fmt, ...); |
| 575 | |
Jeff King | 88d5a6f | 2014-05-22 05:44:09 -0400 | [diff] [blame] | 576 | char *xstrdup_tolower(const char *); |
| 577 | |
Stefan Beller | 6afbbdd | 2015-01-16 04:04:51 -0500 | [diff] [blame] | 578 | /** |
Jeff King | 30a0ddb | 2014-06-18 16:01:34 -0400 | [diff] [blame] | 579 | * Create a newly allocated string using printf format. You can do this easily |
| 580 | * with a strbuf, but this provides a shortcut to save a few lines. |
| 581 | */ |
| 582 | __attribute__((format (printf, 1, 0))) |
| 583 | char *xstrvfmt(const char *fmt, va_list ap); |
| 584 | __attribute__((format (printf, 1, 2))) |
| 585 | char *xstrfmt(const char *fmt, ...); |
| 586 | |
Junio C Hamano | d1df574 | 2005-04-25 18:26:45 -0700 | [diff] [blame] | 587 | #endif /* STRBUF_H */ |