Add JSON_EMBED encoding flag

The JSON_EMBED encoding flag causes the opening and closing characters
of the top-level array ('[', ']') or object ('{', '}') to be omitted
during encoding. This feature makes it possible to concatenate multiple
arrays or objects in the stream output. It also makes it possible to
perform outputs of partial composes.

One such example of a partial compose is when outputting a JWE object.
The output is a JSON object. But it has one top-level attribute
("ciphertext") that can grow out of proportion with the rest of the
metadata. With the JSON_EMBED flag, the other metadata can be composed
ahead of time and dumped during the beginning of output, where the
"ciphertext" and "tag" attributes can be streamed out in chunks. Thus,
the header material can be composed with Jansson and the ciphertext
itself can be composed manually.

1 files changed, 7 insertions, 0 deletions

diff --git a/doc/apiref.rst b/doc/apiref.rst
index f104ad5..bec4088 100644
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -940,6 +940,13 @@ can be ORed together to obtain *flags*.
 
    .. versionadded:: 2.7
 
+``JSON_EMBED``
+   If this flag is used, the opening and closing characters of the top-level
+   array ('[', ']') or object ('{', '}') are omitted during encoding. This
+   flag is useful when concatenating multiple arrays or objects into a stream.
+
+   .. versionadded:: 2.10
+
 These functions output UTF-8:
 
 .. function:: char *json_dumps(const json_t *json, size_t flags)