diff options
Diffstat (limited to 'strbuf.h')
| -rw-r--r-- | strbuf.h | 234 |
1 files changed, 170 insertions, 64 deletions
@@ -1,6 +1,8 @@ #ifndef STRBUF_H #define STRBUF_H +struct string_list; + /** * strbuf's are meant to be used with all the usual C string and memory * APIs. Given that the length of the buffer is known, it's often better to @@ -70,6 +72,12 @@ struct strbuf { extern char strbuf_slopbuf[]; #define STRBUF_INIT { .alloc = 0, .len = 0, .buf = strbuf_slopbuf } +/* + * Predeclare this here, since cache.h includes this file before it defines the + * struct. + */ +struct object_id; + /** * Life Cycle Functions * -------------------- @@ -79,7 +87,7 @@ extern char strbuf_slopbuf[]; * Initialize the structure. The second parameter can be zero or a bigger * number to allocate memory, in case you want to prevent further reallocs. */ -extern void strbuf_init(struct strbuf *, size_t); +void strbuf_init(struct strbuf *sb, size_t alloc); /** * Release a string buffer and the memory it used. After this call, the @@ -89,7 +97,7 @@ extern void strbuf_init(struct strbuf *, size_t); * To clear a strbuf in preparation for further use without the overhead * of free()ing and malloc()ing again, use strbuf_reset() instead. */ -extern void strbuf_release(struct strbuf *); +void strbuf_release(struct strbuf *sb); /** * Detach the string from the strbuf and returns it; you now own the @@ -99,7 +107,7 @@ extern void strbuf_release(struct strbuf *); * The strbuf that previously held the string is reset to `STRBUF_INIT` so * it can be reused after calling this function. */ -extern char *strbuf_detach(struct strbuf *, size_t *); +char *strbuf_detach(struct strbuf *sb, size_t *sz); /** * Attach a string to a buffer. You should specify the string to attach, @@ -109,7 +117,7 @@ extern char *strbuf_detach(struct strbuf *, size_t *); * malloc()ed, and after attaching, the pointer cannot be relied upon * anymore, and neither be free()d directly. */ -extern void strbuf_attach(struct strbuf *, void *, size_t, size_t); +void strbuf_attach(struct strbuf *sb, void *str, size_t len, size_t mem); /** * Swap the contents of two string buffers. @@ -140,7 +148,7 @@ static inline size_t strbuf_avail(const struct strbuf *sb) * This is never a needed operation, but can be critical for performance in * some cases. */ -extern void strbuf_grow(struct strbuf *, size_t); +void strbuf_grow(struct strbuf *sb, size_t amount); /** * Set the length of the buffer to a given value. This function does *not* @@ -175,30 +183,33 @@ static inline void strbuf_setlen(struct strbuf *sb, size_t len) * Strip whitespace from the beginning (`ltrim`), end (`rtrim`), or both side * (`trim`) of a string. */ -extern void strbuf_trim(struct strbuf *); -extern void strbuf_rtrim(struct strbuf *); -extern void strbuf_ltrim(struct strbuf *); +void strbuf_trim(struct strbuf *sb); +void strbuf_rtrim(struct strbuf *sb); +void strbuf_ltrim(struct strbuf *sb); /* Strip trailing directory separators */ -extern void strbuf_trim_trailing_dir_sep(struct strbuf *); +void strbuf_trim_trailing_dir_sep(struct strbuf *sb); + +/* Strip trailing LF or CR/LF */ +void strbuf_trim_trailing_newline(struct strbuf *sb); /** * Replace the contents of the strbuf with a reencoded form. Returns -1 * on error, 0 on success. */ -extern int strbuf_reencode(struct strbuf *sb, const char *from, const char *to); +int strbuf_reencode(struct strbuf *sb, const char *from, const char *to); /** * Lowercase each character in the buffer using `tolower`. */ -extern void strbuf_tolower(struct strbuf *sb); +void strbuf_tolower(struct strbuf *sb); /** * Compare two buffers. Returns an integer less than, equal to, or greater * than zero if the first buffer is found, respectively, to be less than, * to match, or be greater than the second buffer. */ -extern int strbuf_cmp(const struct strbuf *, const struct strbuf *); +int strbuf_cmp(const struct strbuf *first, const struct strbuf *second); /** @@ -225,37 +236,59 @@ static inline void strbuf_addch(struct strbuf *sb, int c) /** * Add a character the specified number of times to the buffer. */ -extern void strbuf_addchars(struct strbuf *sb, int c, size_t n); +void strbuf_addchars(struct strbuf *sb, int c, size_t n); /** * Insert data to the given position of the buffer. The remaining contents * will be shifted, not overwritten. */ -extern void strbuf_insert(struct strbuf *, size_t pos, const void *, size_t); +void strbuf_insert(struct strbuf *sb, size_t pos, const void *, size_t); + +/** + * Insert a NUL-terminated string to the given position of the buffer. + * The remaining contents will be shifted, not overwritten. It's an + * inline function to allow the compiler to resolve strlen() calls on + * constants at compile time. + */ +static inline void strbuf_insertstr(struct strbuf *sb, size_t pos, + const char *s) +{ + strbuf_insert(sb, pos, s, strlen(s)); +} + +/** + * Insert data to the given position of the buffer giving a printf format + * string. The contents will be shifted, not overwritten. + */ +void strbuf_vinsertf(struct strbuf *sb, size_t pos, const char *fmt, + va_list ap); + +void strbuf_insertf(struct strbuf *sb, size_t pos, const char *fmt, ...); /** * Remove given amount of data from a given position of the buffer. */ -extern void strbuf_remove(struct strbuf *, size_t pos, size_t len); +void strbuf_remove(struct strbuf *sb, size_t pos, size_t len); /** * Remove the bytes between `pos..pos+len` and replace it with the given * data. */ -extern void strbuf_splice(struct strbuf *, size_t pos, size_t len, - const void *, size_t); +void strbuf_splice(struct strbuf *sb, size_t pos, size_t len, + const void *data, size_t data_len); /** * Add a NUL-terminated string to the buffer. Each line will be prepended * by a comment character and a blank. */ -extern void strbuf_add_commented_lines(struct strbuf *out, const char *buf, size_t size); +void strbuf_add_commented_lines(struct strbuf *out, + const char *buf, size_t size); /** * Add data of given length to the buffer. */ -extern void strbuf_add(struct strbuf *, const void *, size_t); +void strbuf_add(struct strbuf *sb, const void *data, size_t len); /** * Add a NUL-terminated string to the buffer. @@ -274,7 +307,14 @@ static inline void strbuf_addstr(struct strbuf *sb, const char *s) /** * Copy the contents of another buffer at the end of the current one. */ -extern void strbuf_addbuf(struct strbuf *sb, const struct strbuf *sb2); +void strbuf_addbuf(struct strbuf *sb, const struct strbuf *sb2); + +/** + * Join the arguments into a buffer. `delim` is put between every + * two arguments. + */ +const char *strbuf_join_argv(struct strbuf *buf, int argc, + const char **argv, char delim); /** * This function can be used to expand a format string containing @@ -300,8 +340,21 @@ extern void strbuf_addbuf(struct strbuf *sb, const struct strbuf *sb2); * parameters to the callback, `strbuf_expand()` passes a context pointer, * which can be used by the programmer of the callback as she sees fit. */ -typedef size_t (*expand_fn_t) (struct strbuf *sb, const char *placeholder, void *context); -extern void strbuf_expand(struct strbuf *sb, const char *format, expand_fn_t fn, void *context); +typedef size_t (*expand_fn_t) (struct strbuf *sb, + const char *placeholder, + void *context); +void strbuf_expand(struct strbuf *sb, + const char *format, + expand_fn_t fn, + void *context); + +/** + * Used as callback for `strbuf_expand` to only expand literals + * (i.e. %n and %xNN). The context argument is ignored. + */ +size_t strbuf_expand_literal_cb(struct strbuf *sb, + const char *placeholder, + void *context); /** * Used as callback for `strbuf_expand()`, expects an array of @@ -313,7 +366,9 @@ struct strbuf_expand_dict_entry { const char *placeholder; const char *value; }; -extern size_t strbuf_expand_dict_cb(struct strbuf *sb, const char *placeholder, void *context); +size_t strbuf_expand_dict_cb(struct strbuf *sb, + const char *placeholder, + void *context); /** * Append the contents of one strbuf to another, quoting any @@ -321,29 +376,41 @@ extern size_t strbuf_expand_dict_cb(struct strbuf *sb, const char *placeholder, * destination. This is useful for literal data to be fed to either * strbuf_expand or to the *printf family of functions. */ -extern void strbuf_addbuf_percentquote(struct strbuf *dst, const struct strbuf *src); +void strbuf_addbuf_percentquote(struct strbuf *dst, const struct strbuf *src); + +/** + * Append the contents of a string to a strbuf, percent-encoding any characters + * that are needed to be encoded for a URL. + */ +void strbuf_add_percentencode(struct strbuf *dst, const char *src); /** * Append the given byte size as a human-readable string (i.e. 12.23 KiB, * 3.50 MiB). */ -extern void strbuf_humanise_bytes(struct strbuf *buf, off_t bytes); +void strbuf_humanise_bytes(struct strbuf *buf, off_t bytes); + +/** + * Append the given byte rate as a human-readable string (i.e. 12.23 KiB/s, + * 3.50 MiB/s). + */ +void strbuf_humanise_rate(struct strbuf *buf, off_t bytes); /** * Add a formatted string to the buffer. */ __attribute__((format (printf,2,3))) -extern void strbuf_addf(struct strbuf *sb, const char *fmt, ...); +void strbuf_addf(struct strbuf *sb, const char *fmt, ...); /** * Add a formatted string prepended by a comment character and a * blank to the buffer. */ __attribute__((format (printf, 2, 3))) -extern void strbuf_commented_addf(struct strbuf *sb, const char *fmt, ...); +void strbuf_commented_addf(struct strbuf *sb, const char *fmt, ...); __attribute__((format (printf,2,0))) -extern void strbuf_vaddf(struct strbuf *sb, const char *fmt, va_list ap); +void strbuf_vaddf(struct strbuf *sb, const char *fmt, va_list ap); /** * Add the time specified by `tm`, as formatted by `strftime`. @@ -353,9 +420,9 @@ extern void strbuf_vaddf(struct strbuf *sb, const char *fmt, va_list ap); * `suppress_tz_name`, when set, expands %Z internally to the empty * string rather than passing it to `strftime`. */ -extern void strbuf_addftime(struct strbuf *sb, const char *fmt, - const struct tm *tm, int tz_offset, - int suppress_tz_name); +void strbuf_addftime(struct strbuf *sb, const char *fmt, + const struct tm *tm, int tz_offset, + int suppress_tz_name); /** * Read a given size of data from a FILE* pointer to the buffer. @@ -365,14 +432,14 @@ extern void strbuf_addftime(struct strbuf *sb, const char *fmt, * `strbuf_read()`, `strbuf_read_file()` and `strbuf_getline_*()` * family of functions have the same behaviour as well. */ -extern size_t strbuf_fread(struct strbuf *, size_t, FILE *); +size_t strbuf_fread(struct strbuf *sb, size_t size, FILE *file); /** * Read the contents of a given file descriptor. The third argument can be * used to give a hint about the file size, to avoid reallocs. If read fails, * any partial read is undone. */ -extern ssize_t strbuf_read(struct strbuf *, int fd, size_t hint); +ssize_t strbuf_read(struct strbuf *sb, int fd, size_t hint); /** * Read the contents of a given file descriptor partially by using only one @@ -380,7 +447,7 @@ extern ssize_t strbuf_read(struct strbuf *, int fd, size_t hint); * file size, to avoid reallocs. Returns the number of new bytes appended to * the sb. */ -extern ssize_t strbuf_read_once(struct strbuf *, int fd, size_t hint); +ssize_t strbuf_read_once(struct strbuf *sb, int fd, size_t hint); /** * Read the contents of a file, specified by its path. The third argument @@ -388,19 +455,19 @@ extern ssize_t strbuf_read_once(struct strbuf *, int fd, size_t hint); * Return the number of bytes read or a negative value if some error * occurred while opening or reading the file. */ -extern ssize_t strbuf_read_file(struct strbuf *sb, const char *path, size_t hint); +ssize_t strbuf_read_file(struct strbuf *sb, const char *path, size_t hint); /** * Read the target of a symbolic link, specified by its path. The third * argument can be used to give a hint about the size, to avoid reallocs. */ -extern int strbuf_readlink(struct strbuf *sb, const char *path, size_t hint); +int strbuf_readlink(struct strbuf *sb, const char *path, size_t hint); /** * Write the whole content of the strbuf to the stream not stopping at * NUL bytes. */ -extern ssize_t strbuf_write(struct strbuf *sb, FILE *stream); +ssize_t strbuf_write(struct strbuf *sb, FILE *stream); /** * Read a line from a FILE *, overwriting the existing contents of @@ -414,10 +481,10 @@ extern ssize_t strbuf_write(struct strbuf *sb, FILE *stream); typedef int (*strbuf_getline_fn)(struct strbuf *, FILE *); /* Uses LF as the line terminator */ -extern int strbuf_getline_lf(struct strbuf *sb, FILE *fp); +int strbuf_getline_lf(struct strbuf *sb, FILE *fp); /* Uses NUL as the line terminator */ -extern int strbuf_getline_nul(struct strbuf *sb, FILE *fp); +int strbuf_getline_nul(struct strbuf *sb, FILE *fp); /* * Similar to strbuf_getline_lf(), but additionally treats a CR that @@ -426,14 +493,14 @@ extern int strbuf_getline_nul(struct strbuf *sb, FILE *fp); * that can come from platforms whose native text format is CRLF * terminated. */ -extern int strbuf_getline(struct strbuf *, FILE *); +int strbuf_getline(struct strbuf *sb, FILE *file); /** * Like `strbuf_getline`, but keeps the trailing terminator (if * any) in the buffer. */ -extern int strbuf_getwholeline(struct strbuf *, FILE *, int); +int strbuf_getwholeline(struct strbuf *sb, FILE *file, int term); /** * Like `strbuf_getwholeline`, but operates on a file descriptor. @@ -441,19 +508,19 @@ extern int strbuf_getwholeline(struct strbuf *, FILE *, int); * use it unless you need the correct position in the file * descriptor. */ -extern int strbuf_getwholeline_fd(struct strbuf *, int, int); +int strbuf_getwholeline_fd(struct strbuf *sb, int fd, int term); /** * Set the buffer to the path of the current working directory. */ -extern int strbuf_getcwd(struct strbuf *sb); +int strbuf_getcwd(struct strbuf *sb); /** * Add a path to a buffer, converting a relative path to an * absolute one in the process. Symbolic links are not * resolved. */ -extern void strbuf_add_absolute_path(struct strbuf *sb, const char *path); +void strbuf_add_absolute_path(struct strbuf *sb, const char *path); /** * Canonize `path` (make it absolute, resolve symlinks, remove extra @@ -467,7 +534,7 @@ extern void strbuf_add_absolute_path(struct strbuf *sb, const char *path); * Callers that don't mind links should use the more lightweight * strbuf_add_absolute_path() instead. */ -extern void strbuf_add_real_path(struct strbuf *sb, const char *path); +void strbuf_add_real_path(struct strbuf *sb, const char *path); /** @@ -475,13 +542,13 @@ extern void strbuf_add_real_path(struct strbuf *sb, const char *path); * normalize_path_copy() for details. If an error occurs, the contents of "sb" * are left untouched, and -1 is returned. */ -extern int strbuf_normalize_path(struct strbuf *sb); +int strbuf_normalize_path(struct strbuf *sb); /** * Strip whitespace from a buffer. The second parameter controls if * comments are considered contents to be removed or not. */ -extern void strbuf_stripspace(struct strbuf *buf, int skip_comments); +void strbuf_stripspace(struct strbuf *buf, int skip_comments); static inline int strbuf_strip_suffix(struct strbuf *sb, const char *suffix) { @@ -510,8 +577,8 @@ static inline int strbuf_strip_suffix(struct strbuf *sb, const char *suffix) * For lighter-weight alternatives, see string_list_split() and * string_list_split_in_place(). */ -extern struct strbuf **strbuf_split_buf(const char *, size_t, - int terminator, int max); +struct strbuf **strbuf_split_buf(const char *str, size_t len, + int terminator, int max); static inline struct strbuf **strbuf_split_str(const char *str, int terminator, int max) @@ -520,7 +587,7 @@ static inline struct strbuf **strbuf_split_str(const char *str, } static inline struct strbuf **strbuf_split_max(const struct strbuf *sb, - int terminator, int max) + int terminator, int max) { return strbuf_split_buf(sb->buf, sb->len, terminator, max); } @@ -531,19 +598,33 @@ static inline struct strbuf **strbuf_split(const struct strbuf *sb, return strbuf_split_max(sb, terminator, 0); } +/* + * Adds all strings of a string list to the strbuf, separated by the given + * separator. For example, if sep is + * ', ' + * and slist contains + * ['element1', 'element2', ..., 'elementN'], + * then write: + * 'element1, element2, ..., elementN' + * to str. If only one element, just write "element1" to str. + */ +void strbuf_add_separated_string_list(struct strbuf *str, + const char *sep, + struct string_list *slist); + /** * Free a NULL-terminated list of strbufs (for example, the return * values of the strbuf_split*() functions). */ -extern void strbuf_list_free(struct strbuf **); +void strbuf_list_free(struct strbuf **list); /** * Add the abbreviation, as generated by find_unique_abbrev, of `sha1` to * the strbuf `sb`. */ -extern void strbuf_add_unique_abbrev(struct strbuf *sb, - const unsigned char *sha1, - int abbrev_len); +void strbuf_add_unique_abbrev(struct strbuf *sb, + const struct object_id *oid, + int abbrev_len); /** * Launch the user preferred editor to edit a file and fill the buffer @@ -552,15 +633,34 @@ extern void strbuf_add_unique_abbrev(struct strbuf *sb, * run in. If the buffer is NULL the editor is launched as usual but the * file's contents are not read into the buffer upon completion. */ -extern int launch_editor(const char *path, struct strbuf *buffer, const char *const *env); +int launch_editor(const char *path, struct strbuf *buffer, + const char *const *env); -extern void strbuf_add_lines(struct strbuf *sb, const char *prefix, const char *buf, size_t size); +int launch_sequence_editor(const char *path, struct strbuf *buffer, + const char *const *env); + +/* + * In contrast to `launch_editor()`, this function writes out the contents + * of the specified file first, then clears the `buffer`, then launches + * the editor and reads back in the file contents into the `buffer`. + * Finally, it deletes the temporary file. + * + * If `path` is relative, it refers to a file in the `.git` directory. + */ +int strbuf_edit_interactively(struct strbuf *buffer, const char *path, + const char *const *env); + +void strbuf_add_lines(struct strbuf *sb, + const char *prefix, + const char *buf, + size_t size); /** * Append s to sb, with the characters '<', '>', '&' and '"' converted * into XML entities. */ -extern void strbuf_addstr_xml_quoted(struct strbuf *sb, const char *s); +void strbuf_addstr_xml_quoted(struct strbuf *sb, + const char *s); /** * "Complete" the contents of `sb` by ensuring that either it ends with the @@ -590,8 +690,8 @@ static inline void strbuf_complete_line(struct strbuf *sb) * If "allowed" is non-zero, restrict the set of allowed expansions. See * interpret_branch_name() for details. */ -extern void strbuf_branchname(struct strbuf *sb, const char *name, - unsigned allowed); +void strbuf_branchname(struct strbuf *sb, const char *name, + unsigned allowed); /* * Like strbuf_branchname() above, but confirm that the result is @@ -599,17 +699,23 @@ extern void strbuf_branchname(struct strbuf *sb, const char *name, * * The return value is "0" if the result is valid, and "-1" otherwise. */ -extern int strbuf_check_branch_ref(struct strbuf *sb, const char *name); +int strbuf_check_branch_ref(struct strbuf *sb, const char *name); + +typedef int (*char_predicate)(char ch); + +int is_rfc3986_unreserved(char ch); +int is_rfc3986_reserved_or_unreserved(char ch); -extern void strbuf_addstr_urlencode(struct strbuf *, const char *, - int reserved); +void strbuf_addstr_urlencode(struct strbuf *sb, const char *name, + char_predicate allow_unencoded_fn); __attribute__((format (printf,1,2))) -extern int printf_ln(const char *fmt, ...); +int printf_ln(const char *fmt, ...); __attribute__((format (printf,2,3))) -extern int fprintf_ln(FILE *fp, const char *fmt, ...); +int fprintf_ln(FILE *fp, const char *fmt, ...); char *xstrdup_tolower(const char *); +char *xstrdup_toupper(const char *); /** * Create a newly allocated string using printf format. You can do this easily |