Clean up base64 node construction and access API

3 files changed, 83 insertions, 0 deletions

diff --git a/include/serd/node.h b/include/serd/node.h
index 427bbdd1..50108f57 100644
--- a/include/serd/node.h
+++ b/include/serd/node.h
@@ -7,6 +7,7 @@
 #include "serd/attributes.h"
 #include "serd/string_view.h"
 #include "serd/uri.h"
+#include "serd/write_result.h"
 
 #include <stdbool.h>
 #include <stddef.h>
@@ -360,6 +361,37 @@ SERD_API int64_t
 serd_get_integer(const SerdNode* SERD_NONNULL node);
 
 /**
+   Return the maximum size of a decoded binary node in bytes.
+
+   This returns an upper bound on the number of bytes that the node would
+   decode to.  This is calculated as a simple constant-time arithmetic
+   expression based on the length of the encoded string, so may be larger than
+   the actual size of the data due to things like additional whitespace.
+*/
+SERD_PURE_API size_t
+serd_get_base64_size(const SerdNode* SERD_NONNULL node);
+
+/**
+   Decode a base64 node.
+
+   This function can be used to decode a node created with serd_new_base64().
+
+   @param node A literal node which is an encoded base64 string.
+
+   @param buf_size The size of `buf` in bytes.
+
+   @param buf Buffer where decoded data will be written.
+
+   @return On success, #SERD_SUCCESS is returned along with the number of bytes
+   written.  If the output buffer is too small, then #SERD_OVERFLOW is returned
+   along with the number of bytes required for successful decoding.
+*/
+SERD_API SerdWriteResult
+serd_get_base64(const SerdNode* SERD_NONNULL node,
+                size_t                       buf_size,
+                void* SERD_NONNULL           buf);
+
+/**
    @}
    @defgroup serd_node_operators Operators
    @{
diff --git a/include/serd/serd.h b/include/serd/serd.h
index 70168997..03243c76 100644
--- a/include/serd/serd.h
+++ b/include/serd/serd.h
@@ -48,6 +48,7 @@
 #include "serd/string.h"
 #include "serd/string_view.h"
 #include "serd/syntax.h"
+#include "serd/write_result.h"
 
 /**
    @}
diff --git a/include/serd/write_result.h b/include/serd/write_result.h
new file mode 100644
index 00000000..14211354
--- /dev/null
+++ b/include/serd/write_result.h
@@ -0,0 +1,50 @@
+// Copyright 2011-2023 David Robillard <d@drobilla.net>
+// SPDX-License-Identifier: ISC
+
+#ifndef SERD_WRITE_RESULT_H
+#define SERD_WRITE_RESULT_H
+
+#include "serd/attributes.h"
+#include "serd/status.h"
+
+#include <stddef.h>
+
+SERD_BEGIN_DECLS
+
+/**
+   @defgroup serd_write_result Write Result
+   @ingroup serd_utilities
+   @{
+*/
+
+/**
+   A status code with an associated byte count.
+
+   This is returned by functions which write to a buffer to inform the caller
+   about the size written, or in case of overflow, size required.
+*/
+typedef struct {
+  /**
+     Status code.
+
+     This reports the status of the operation as usual, and also dictates the
+     meaning of `count`.
+  */
+  SerdStatus status;
+
+  /**
+     Number of bytes written or required.
+
+     On success, this is the total number of bytes written.  On #SERD_OVERFLOW,
+     this is the number of bytes of output space that are required for success.
+  */
+  size_t count;
+} SerdWriteResult;
+
+/**
+   @}
+*/
+
+SERD_END_DECLS
+
+#endif // SERD_WRITE_RESULT_H