ewah: support platforms that require aligned reads
[gitweb.git] / Documentation / technical / api-strbuf.txt
index afe27599511c5f6bab6e4f799fd18e7d83bdd454..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.
@@ -225,10 +230,20 @@ which can be used by the programmer of the callback as she sees fit.
        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.
@@ -255,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