This section defines a resizable binary buffer type. This class can also be used to construct C strings, when you don’t know the size of the string in advance.
This class is not reference counted; we assume that there’s a single owner of the buffer. The contents of a cork_buffer are fully mutable. If you want to turn the buffer into something that’s safe to pass between threads, you can use the cork_buffer_to_slice() or cork_buffer_to_managed_buffer() functions to create an immutable managed wrapper around the buffer.
You can read the contents of the buffer by accessing the buf and size fields directly. However, to modify the contents of a buffer, you should use the mutator functions described below, since they take care of automatically resizing the underlying buffer when necessary.
This class always creates its own copy of any data added to the buffer; there aren’t any methods for wrapping existing buffers without copying. If you want to do that, you should use Managed binary buffers or Binary slices.
A resizable binary buffer.
The current contents of the buffer.
The current size of the buffer.
Initialize a new buffer instance that you’ve allocated yourself (usually on the stack). The CORK_BUFFER_INIT version can only be used as a static initializer.
The preallocated cork_buffer instance that you provide doesn’t include space for the content of the buffer; this will be allocated automatically as content is added.
Finalize a buffer, freeing any content that it contains. This function should only be used for buffers that you allocated yourself, and initialized using cork_buffer_init() or CORK_BUFFER_INIT(). You must not use this function to free a buffer allocated using cork_buffer_free().
Finalize and deallocate a buffer, freeing any content that it contains. This function should only be used for buffers allocated using cork_buffer_new(). You must not use this function to free a buffer initialized using cork_buffer_init() or CORK_BUFFER_INIT().
Compare two buffers for equality.
Ensure that a buffer has allocated enough space to store at least desired_size bytes. We won’t shrink the size of the buffer’s internal storage; if the buffer has already allocated at least desired_size bytes, the function acts as a no-op.
Return the byte or character at the given index in buffer.
Most of the mutator functions defined in this section come in two variants: a _set function, which clears the buffer before adding new content, and an _append function, which retains the old content, adding the new content to the end of the buffer.
Each mutator function will automatically append an extra NUL byte to the end of whatever content is placed into the buffer. However, this NUL byte will not be included in the size of the buffer. This ensures that the contents of any cork_buffer can be used as a NUL-terminated C string (assuming that there aren’t any internal NULs), even if the buffer is constructed from a data source that doesn’t include NUL terminators.
Clear a buffer. This does not free any storage that the buffer has allocated; this storage will be reused if you add contents back to the buffer.
Truncate a buffer so that contains no more than length bytes. If the buffer is already shorter than this, it is not modified.
Copy the contents of the src buffer into dest. The _set variant clears the buffer first, while the _append variant adds src to whatever content is already there.
Copy the contents of src into a buffer. The _set variant clears the buffer first, while the _append variant adds src to whatever content is already there.
Copy the contents of str (which must be a NUL-terminated C string) into a buffer. The _set variants clears the buffer first, while the _append variants adds str to whatever content is already there. The _literal variants only work when str is a C string literal; we use the sizeof operator to determine the length of the string at compile time. The _string variants work with any C string; we use the builtin strlen function to determine the length of the string.
Format data according to a printf format string, placing the result into a buffer. The _append variants add the formatted string to whatever content is already in the buffer; the non-_append variants clear the buffer first. The _printf variants are vararg functions, and take in the format string’s data as direct parameters. The _vprintf variants can be used within another vararg function, and let you pass in the format string’s data as a C99-standard va_list instance.
We also provide several helper functions for adding pretty-printed content to a cork_buffer.
Append indent spaces to buffer.
Append the C string literal representation of str to buffer. This will include opening and closing double quotes, and any non-printable characters will be escaped. (We will use the standard letter-based escapes where possible, and fall back on "\xXX" hexadecimal escapes for other non-printable characters.) The result is guaranteed to stay on a single line, since any embedded newlines will be converted to a \n escape sequence.
Append a pretty-printed representation of str to buffer. All of these functions can produce multiple lines of output. All lines except for the first will be prefaced with indent space characters. The final line will not have a trailing newline.
The hex_dump variant will output a hex-dump representation of str. This will include the hexadecimal representation of each byte, and the actual character of any printable byte.
The multiline variant appends the raw content of str to the buffer, without making any attempt to sanitize non-printable characters. (That means you should only call this variant if you know that str contains only printable characters.) If str itself spans multiple lines, then we’ll insert indentation to make sure that we satisfy the indentation rules described above.
The binary variant autodetects how to best render str. If it contains any non-printable characters, then we’ll use the hex_dump representation. If it spans multiple lines, we’ll use the multiline representation. Otherwise, we’ll append the content directly without any modification.
The cork_buffer class is the only binary data class that is mutable; this comes at the cost of only being usable by a single owner thread or function at a time. Once you have constructed a binary string or payload using a cork_buffer, you can use the functions in this section to produce a corresponding instance of one of libcork’s sharable, immutable binary data types.
Create a new managed buffer to manage the contents of a cork_buffer instance. buffer must have been allocated on the heap (i.e., using cork_buffer_new(), and not cork_buffer_init()). We take ownership of buffer, regardless of whether we’re able to successfully create a new cork_managed_buffer instance. You must not try to free buffer yourself.
Initialize a new slice to manage the contents of buffer. buffer must have been allocated on the heap (i.e., using cork_buffer_new(), and not cork_buffer_init()). We take ownership of buffer, regardless of whether we’re able to successfully create a new cork_managed_buffer instance. You must not try to free buffer yourself.
The slice will point into the contents of a new managed buffer instance. The managed buffer isn’t returned directly, though you can create additional slices into it using the usual cork_slice methods.
Regardless of whether we can initialize the slice successfully, you must call cork_slice_finish() on slice when you’re done with the slice.
Create a new stream consumer that appends any received data into buffer.
We do not take control of buffer. You retain responsibility for freeing the buffer, and you must ensure that it remains allocated and valid for the entire lifetime of the stream consumer that we return.