diff options
Diffstat (limited to 'include/serd/buffer.h')
| -rw-r--r-- | include/serd/buffer.h | 33 |
1 files changed, 19 insertions, 14 deletions
diff --git a/include/serd/buffer.h b/include/serd/buffer.h index d4fd63fb..556e7e1f 100644 --- a/include/serd/buffer.h +++ b/include/serd/buffer.h @@ -17,6 +17,9 @@ SERD_BEGIN_DECLS The #SerdBuffer type represents a writable area of memory with a known size. + A #SerdWriteFunc function is provided which enable writing output to a + memory buffer (as `fwrite` does for files). + @{ */ @@ -27,27 +30,29 @@ typedef struct { } SerdBuffer; /** - A convenience sink function for writing to a string. + A function for writing to a buffer, resizing it if necessary. + + This function can be used as a #SerdWriteFunc to write to a #SerdBuffer + which is resized as necessary with realloc(). The `stream` parameter must + point to an initialized #SerdBuffer. - This function can be used as a #SerdWriteFunc to write to a SerdBuffer which - is resized as necessary with realloc(). The `stream` parameter must point to - an initialized #SerdBuffer. When the write is finished, the string should be - retrieved with serd_buffer_sink_finish(). + Note that when writing a string, the string in the buffer will not be + null-terminated until serd_buffer_close() is called. */ SERD_API size_t -serd_buffer_sink(const void* ZIX_NONNULL buf, - size_t size, - size_t nmemb, - void* ZIX_NONNULL stream); +serd_buffer_write(const void* ZIX_NONNULL buf, + size_t size, + size_t nmemb, + void* ZIX_NONNULL stream); /** - Finish writing to a buffer with serd_buffer_sink(). + Close the buffer for writing. - The returned string is the result of the serialisation, which is null - terminated (by this function) and owned by the caller. + This writes a terminating null byte, so the contents of the buffer are safe + to read as a string after this call. */ -SERD_API char* ZIX_NONNULL -serd_buffer_sink_finish(SerdBuffer* ZIX_NONNULL stream); +SERD_API int +serd_buffer_close(void* ZIX_NONNULL stream); /** @} |