Buffers¶
Buffers provide a variable-length area of memory in which data may be held and manipulated. Contained data is not interpreted, and length of it is tracked, so it is possible to add null bytes to a buffer.
Allocating a buffer is done in the stack using the W_BUF
macro.
to initialize it. After initialization, all buffer functions can be used,
and when the buffer is not needed anymore, its contents can be freed using
w_buf_clear()
.
Usage¶
// Initialize the buffer.
w_buf_t b = W_BUF;
// Append some string pieces.
w_buf_append_str (&b, "Too much work ");
w_buf_append_str (&b, "and no joy makes");
w_buf_append_str (&b, " Jack a dull boy");
// Buffer contents can be printed directly using the $B format.
w_print ("$B\n", &b);
// Free the memory used by the contents of the buffer.
w_buf_clear (&b);
Macros¶
-
W_BUF
¶ Initializer for buffers. It can be used to initialize buffers directly on the stack:
w_buf_t buffer = W_BUF;
Functions¶
-
void
w_buf_resize
(w_buf_t* buffer, size_t size)¶ Adjust the size of a buffer keeping contents. This is mostly useful for trimming contents, when shrinking the buffer. When a buffer grows, random data is liklely to appear at the end.
Parameters: - buffer – A w_buf_t buffer
- size – size New size of the buffer
-
void
w_buf_set_str
(w_buf_t *buffer, const char *string)¶ Set the contents of a buffer to a C string.
Parameters: - buffer – A w_buf_t buffer
- string – String to set the buffer to.
-
void
w_buf_append_mem
(w_buf_t *buffer, const void *address, size_t length)¶ Appends the contents of a chunk of memory of length bytes starting at address to a buffer.
Parameters: - buffer – A w_buf_t buffer.
- address – Pointer to the memory block of memory.
- length – Length of the memory block.
-
void
w_buf_append_buf
(w_buf_t *buffer, const w_buf_t *other)¶ Appends the contents of other buffer to another buffer.
-
char*
w_buf_str
(w_buf_t *buffer)¶ Obtains the contents of a buffer as a
NULL
-terminated C string.Warning
If the buffer contains embedded null characters, functions like
strlen()
will not report the full length of the buffer.The returned pointer is owned by the buffer, and there two ways in which the memory region can be freed:
- Clearing the buffer with
w_buf_clear()
. The returned pointer will be invalid afterwards. - Calling
w_free()
on the returned pointer. The buffer will be invalid and must not be used afterwards.
The second way is useful to assemble a string which is returned from a function, for example:
char* concat_strings (const char *s, ...) { w_buf_t buffer = W_BUF; w_buf_set_str (&buffer, s); va_list args; va_start (args, s); while ((s = va_args (args, const char*))) w_buf_append_str (&buffer, s); va_end (args); return w_buf_str (&buffer); }
- Clearing the buffer with
-
w_io_result_t
w_buf_format
(w_buf_t *buffer, const char *format, ...)¶ Appends text with a given format into a buffer, consuming additional arguments as needed by the format.
See Formatted output for the available formatting options.
-
w_io_result_t
w_buf_formatv
(w_buf_t *buffer, const char *format, va_list arguments)¶ Appends text with a given format into a buffer, consuming additional arguments as needed by the format.
See Formatted output for the available formatting options.
-
char*
w_buf_data
(w_buf_t *buffer)¶ Obtains a pointer to the internal data stored by a buffer.
Warning
The returned value may be
NULL
when the buffer is empty.
-
const char*
w_buf_const_data
(const w_buf_t *buffer)¶ Obtains a pointer to the internal data stored by a buffer, returning it as a
const
pointer. This may be used instead ofw_buf_data()
when the data is not going to be modified.Warning
The returned value may be
NULL
when the buffer is empty.