Split up public API header

1 files changed, 56 insertions, 0 deletions

diff --git a/include/serd/buffer.h b/include/serd/buffer.h
new file mode 100644
index 00000000..90b51a48
--- /dev/null
+++ b/include/serd/buffer.h
@@ -0,0 +1,56 @@
+// Copyright 2011-2022 David Robillard <d@drobilla.net>
+// SPDX-License-Identifier: ISC
+
+#ifndef SERD_BUFFER_H
+#define SERD_BUFFER_H
+
+#include "serd/attributes.h"
+
+#include <stddef.h>
+
+SERD_BEGIN_DECLS
+
+/**
+   @defgroup serd_buffer Dynamic Memory Buffers
+   @ingroup serd_memory
+
+   The #SerdBuffer type represents a writable area of memory with a known size.
+
+   @{
+*/
+
+/// A mutable buffer in memory
+typedef struct {
+  void* SERD_NULLABLE buf; ///< Buffer
+  size_t              len; ///< Size of buffer in bytes
+} SerdBuffer;
+
+/**
+   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                   len,
+                 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);
+
+/**
+   @}
+*/
+
+SERD_END_DECLS
+
+#endif // SERD_BUFFER_H