From 63e7e57237a79d0447b0450a7fd3148c43052299 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Fri, 13 Aug 2021 19:31:26 -0400
Subject: Provide a full output stream implementation for SerdBuffer

Essentially replaces serd_buffer_sink_finish() with serd_buffer_close(), which
makes writing to a buffer consistent with writing to a file or anything else.
---
 include/serd/serd.h | 77 ++++++++++++++++++++++++++++++++---------------------
 1 file changed, 46 insertions(+), 31 deletions(-)

(limited to 'include/serd')

diff --git a/include/serd/serd.h b/include/serd/serd.h
index daf903a2..c3b674b7 100644
--- a/include/serd/serd.h
+++ b/include/serd/serd.h
@@ -199,12 +199,6 @@ typedef struct {
    @}
 */
 
-/// A mutable buffer in memory
-typedef struct {
-  void* SERD_NULLABLE buf; ///< Buffer
-  size_t              len; ///< Size of buffer in bytes
-} SerdBuffer;
-
 /**
    Free memory allocated by Serd.
 
@@ -2385,6 +2379,52 @@ SERD_API
 void
 serd_reader_free(SerdReader* SERD_NULLABLE reader);
 
+/**
+   @}
+   @defgroup serd_buffer Buffer
+
+   The #SerdBuffer type represents a writable area of memory with a known size.
+   An implementation of #SerdWriteFunc, #SerdStreamErrorFunc, and
+   #SerdStreamCloseFunc are provided which allow output to be written to a
+   buffer in memory instead of to a file as with `fwrite`, `ferror`, and
+   `fclose`.
+
+   @{
+*/
+
+/// A mutable buffer in memory
+typedef struct {
+  void* SERD_NULLABLE buf; ///< Buffer
+  size_t              len; ///< Size of buffer in bytes
+} SerdBuffer;
+
+/**
+   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.
+
+   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_write(const void* SERD_NONNULL buf,
+                  size_t                   size,
+                  size_t                   nmemb,
+                  void* SERD_NONNULL       stream);
+
+/**
+   Close the buffer for writing.
+
+   This writes a terminating null byte, so the contents of the buffer are safe
+   to read as a string after this call.
+*/
+SERD_API
+int
+serd_buffer_close(void* SERD_NONNULL stream);
+
 /**
    @}
    @defgroup serd_byte_sink Byte Sink
@@ -2555,31 +2595,6 @@ SERD_CONST_API
 const SerdSink* SERD_NONNULL
 serd_writer_sink(SerdWriter* SERD_NONNULL writer);
 
-/**
-   A convenience sink function for writing to a string.
-
-   This function can be used as a SerdSink 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().
-*/
-SERD_API
-size_t
-serd_buffer_sink(const void* SERD_NONNULL buf,
-                 size_t                   size,
-                 size_t                   nmemb,
-                 void* SERD_NONNULL       stream);
-
-/**
-   Finish writing to a buffer with serd_buffer_sink().
-
-   The returned string is the result of the serialisation, which is null
-   terminated (by this function) and owned by the caller.
-*/
-SERD_API
-char* SERD_NONNULL
-serd_buffer_sink_finish(SerdBuffer* SERD_NONNULL stream);
-
 /**
    Set the current output base URI, and emit a directive if applicable.
 
-- 
cgit v1.2.1