ewah: support platforms that require aligned reads
[gitweb.git] / Documentation / technical / api-strbuf.txt
index 3b1da10f263dad08ad327d678da9ada32c83599f..3350d97dda2408f92dc44c1e3216facc50257a50 100644 (file)
@@ -156,6 +156,11 @@ then they will free() it.
        Remove the bytes between `pos..pos+len` and replace it with the given
        data.
 
+`strbuf_add_commented_lines`::
+
+       Add a NUL-terminated string to the buffer. Each line will be prepended
+       by a comment character and a blank.
+
 `strbuf_add`::
 
        Add data of given length to the buffer.
@@ -218,10 +223,27 @@ which can be used by the programmer of the callback as she sees fit.
        placeholder and replacement string.  The array needs to be
        terminated by an entry with placeholder set to NULL.
 
+`strbuf_addbuf_percentquote`::
+
+       Append the contents of one strbuf to another, quoting any
+       percent signs ("%") into double-percents ("%%") in the
+       destination. This is useful for literal data to be fed to either
+       strbuf_expand or to the *printf family of functions.
+
+`strbuf_humanise_bytes`::
+
+       Append the given byte size as a human-readable string (i.e. 12.23 KiB,
+       3.50 MiB).
+
 `strbuf_addf`::
 
        Add a formatted string to the buffer.
 
+`strbuf_commented_addf`::
+
+       Add a formatted string prepended by a comment character and a
+       blank to the buffer.
+
 `strbuf_fread`::
 
        Read a given size of data from a FILE* pointer to the buffer.
@@ -248,14 +270,46 @@ same behaviour as well.
 
 `strbuf_getline`::
 
-       Read a line from a FILE* pointer. The second argument specifies the line
+       Read a line from a FILE *, overwriting the existing contents
+       of the strbuf. The second argument specifies the line
        terminator character, typically `'\n'`.
+       Reading stops after the terminator or at EOF.  The terminator
+       is removed from the buffer before returning.  Returns 0 unless
+       there was nothing left before EOF, in which case it returns `EOF`.
+
+`strbuf_getwholeline`::
+
+       Like `strbuf_getline`, but keeps the trailing terminator (if
+       any) in the buffer.
+
+`strbuf_getwholeline_fd`::
+
+       Like `strbuf_getwholeline`, but operates on a file descriptor.
+       It reads one character at a time, so it is very slow.  Do not
+       use it unless you need the correct position in the file
+       descriptor.
 
 `stripspace`::
 
        Strip whitespace from a buffer. The second parameter controls if
        comments are considered contents to be removed or not.
 
+`strbuf_split_buf`::
+`strbuf_split_str`::
+`strbuf_split_max`::
+`strbuf_split`::
+
+       Split a string or strbuf into a list of strbufs at a specified
+       terminator character.  The returned substrings include the
+       terminator characters.  Some of these functions take a `max`
+       parameter, which, if positive, limits the output to that
+       number of substrings.
+
+`strbuf_list_free`::
+
+       Free a list of strbufs (for example, the return values of the
+       `strbuf_split()` functions).
+
 `launch_editor`::
 
        Launch the user preferred editor to edit a file and fill the buffer