This header defines the types and functions your application uses to read or write JSON objects. More...

#include <azure/core/az_result.h>
#include <azure/core/az_span.h>
#include <stdbool.h>
#include <stdint.h>
#include <azure/core/_az_cfg_prefix.h>
#include <azure/core/_az_cfg_suffix.h>

Data Structures
struct	az_json_token
	Represents a JSON token. The kind field indicates the type of the JSON token and the slice represents the portion of the JSON payload that points to the token value. More...

struct	az_json_writer_options
	Allows the user to define custom behavior when writing JSON using the az_json_writer. More...

struct	az_json_writer
	Provides forward-only, non-cached writing of UTF-8 encoded JSON text into the provided buffer. More...

struct	az_json_reader_options
	Allows the user to define custom behavior when reading JSON using the az_json_reader. More...

struct	az_json_reader
	Returns the JSON tokens contained within a JSON buffer, one at a time. More...

Enumerations
enum	az_json_token_kind { AZ_JSON_TOKEN_NONE, AZ_JSON_TOKEN_BEGIN_OBJECT, AZ_JSON_TOKEN_END_OBJECT, AZ_JSON_TOKEN_BEGIN_ARRAY, AZ_JSON_TOKEN_END_ARRAY, AZ_JSON_TOKEN_PROPERTY_NAME, AZ_JSON_TOKEN_STRING, AZ_JSON_TOKEN_NUMBER, AZ_JSON_TOKEN_TRUE, AZ_JSON_TOKEN_FALSE, AZ_JSON_TOKEN_NULL }
	Defines symbols for the various kinds of JSON tokens that make up any JSON text. More...

Functions
az_span	az_json_token_copy_into_span (az_json_token const *json_token, az_span destination)
	Copies the content of the `token` az_json_token to the `destination` az_span. More...

AZ_NODISCARD az_result	az_json_token_get_boolean (az_json_token const json_token, bool out_value)
	Gets the JSON token's boolean. More...

AZ_NODISCARD az_result	az_json_token_get_uint64 (az_json_token const json_token, uint64_t out_value)
	Gets the JSON token's number as a 64-bit unsigned integer. More...

AZ_NODISCARD az_result	az_json_token_get_uint32 (az_json_token const json_token, uint32_t out_value)
	Gets the JSON token's number as a 32-bit unsigned integer. More...

AZ_NODISCARD az_result	az_json_token_get_int64 (az_json_token const json_token, int64_t out_value)
	Gets the JSON token's number as a 64-bit signed integer. More...

AZ_NODISCARD az_result	az_json_token_get_int32 (az_json_token const json_token, int32_t out_value)
	Gets the JSON token's number as a 32-bit signed integer. More...

AZ_NODISCARD az_result	az_json_token_get_double (az_json_token const json_token, double out_value)
	Gets the JSON token's number as a `double`. More...

AZ_NODISCARD az_result	az_json_token_get_string (az_json_token const json_token, char destination, int32_t destination_max_size, int32_t *out_string_length)
	Gets the JSON token's string after unescaping it, if required. More...

AZ_NODISCARD bool	az_json_token_is_text_equal (az_json_token const *json_token, az_span expected_text)
	Determines whether the unescaped JSON token value that the az_json_token points to is equal to the expected text within the provided byte span by doing a case-sensitive comparison. More...

AZ_NODISCARD AZ_INLINE az_json_writer_options	az_json_writer_options_default ()
	Gets the default json writer options which builds minimized JSON (with no extra white space) according to the JSON RFC. More...

AZ_NODISCARD az_result	az_json_writer_init (az_json_writer out_json_writer, az_span destination_buffer, az_json_writer_options const options)
	Initializes an az_json_writer which writes JSON text into a buffer. More...

AZ_NODISCARD az_result	az_json_writer_chunked_init (az_json_writer out_json_writer, az_span first_destination_buffer, az_span_allocator_fn allocator_callback, void user_context, az_json_writer_options const *options)
	Initializes an az_json_writer which writes JSON text into a destination that can contain non-contiguous buffers. More...

AZ_NODISCARD AZ_INLINE az_span	az_json_writer_get_bytes_used_in_destination (az_json_writer const *json_writer)
	Returns the az_span containing the JSON text written to the underlying buffer so far, in the last provided destination buffer. More...

AZ_NODISCARD az_result	az_json_writer_append_string (az_json_writer *ref_json_writer, az_span value)
	Appends the UTF-8 text value (as a JSON string) into the buffer. More...

AZ_NODISCARD az_result	az_json_writer_append_json_text (az_json_writer *ref_json_writer, az_span json_text)
	Appends an existing UTF-8 encoded JSON text into the buffer, useful for appending nested JSON. More...

AZ_NODISCARD az_result	az_json_writer_append_property_name (az_json_writer *ref_json_writer, az_span name)
	Appends the UTF-8 property name (as a JSON string) which is the first part of a name/value pair of a JSON object. More...

AZ_NODISCARD az_result	az_json_writer_append_bool (az_json_writer *ref_json_writer, bool value)
	Appends a boolean value (as a JSON literal `true` or `false`). More...

AZ_NODISCARD az_result	az_json_writer_append_int32 (az_json_writer *ref_json_writer, int32_t value)
	Appends an `int32_t` number value. More...

AZ_NODISCARD az_result	az_json_writer_append_double (az_json_writer *ref_json_writer, double value, int32_t fractional_digits)
	Appends a `double` number value. More...

AZ_NODISCARD az_result	az_json_writer_append_null (az_json_writer *ref_json_writer)
	Appends the JSON literal `null`. More...

AZ_NODISCARD az_result	az_json_writer_append_begin_object (az_json_writer *ref_json_writer)
	Appends the beginning of a JSON object (i.e. `{`). More...

AZ_NODISCARD az_result	az_json_writer_append_begin_array (az_json_writer *ref_json_writer)
	Appends the beginning of a JSON array (i.e. `[`). More...

AZ_NODISCARD az_result	az_json_writer_append_end_object (az_json_writer *ref_json_writer)
	Appends the end of the current JSON object (i.e. `}`). More...

AZ_NODISCARD az_result	az_json_writer_append_end_array (az_json_writer *ref_json_writer)
	Appends the end of the current JSON array (i.e. `]`). More...

AZ_NODISCARD AZ_INLINE az_json_reader_options	az_json_reader_options_default ()
	Gets the default json reader options which reads the JSON strictly according to the JSON RFC. More...

AZ_NODISCARD az_result	az_json_reader_init (az_json_reader out_json_reader, az_span json_buffer, az_json_reader_options const options)
	Initializes an az_json_reader to read the JSON payload contained within the provided buffer. More...

AZ_NODISCARD az_result	az_json_reader_chunked_init (az_json_reader out_json_reader, az_span json_buffers[], int32_t number_of_buffers, az_json_reader_options const options)
	Initializes an az_json_reader to read the JSON payload contained within the provided set of discontiguous buffers. More...

AZ_NODISCARD az_result	az_json_reader_next_token (az_json_reader *ref_json_reader)
	Reads the next token in the JSON text and updates the reader state. More...

AZ_NODISCARD az_result	az_json_reader_skip_children (az_json_reader *ref_json_reader)
	Reads and skips over any nested JSON elements. More...

AZ_NODISCARD az_span	az_json_string_unescape (az_span json_string, az_span destination)
	Unescapes the JSON string within the provided az_span. More...

Detailed Description

This header defines the types and functions your application uses to read or write JSON objects.

Note: You MUST NOT use any symbols (macros, functions, structures, enums, etc.) prefixed with an underscore ('_') directly in your application code. These symbols are part of Azure SDK's internal implementation; we do not document these symbols and they are subject to change in future versions of the SDK which would break your code.

Enumeration Type Documentation

◆ az_json_token_kind

enum az_json_token_kind

Defines symbols for the various kinds of JSON tokens that make up any JSON text.

Enumerator
AZ_JSON_TOKEN_NONE	There is no value (as distinct from AZ_JSON_TOKEN_NULL).
AZ_JSON_TOKEN_BEGIN_OBJECT	The token kind is the start of a JSON object.
AZ_JSON_TOKEN_END_OBJECT	The token kind is the end of a JSON object.
AZ_JSON_TOKEN_BEGIN_ARRAY	The token kind is the start of a JSON array.
AZ_JSON_TOKEN_END_ARRAY	The token kind is the end of a JSON array.
AZ_JSON_TOKEN_PROPERTY_NAME	The token kind is a JSON property name.
AZ_JSON_TOKEN_STRING	The token kind is a JSON string.
AZ_JSON_TOKEN_NUMBER	The token kind is a JSON number.
AZ_JSON_TOKEN_TRUE	The token kind is the JSON literal `true`.
AZ_JSON_TOKEN_FALSE	The token kind is the JSON literal `false`.
AZ_JSON_TOKEN_NULL	The token kind is the JSON literal `null`.

Function Documentation

◆ az_json_reader_chunked_init()

AZ_NODISCARD az_result az_json_reader_chunked_init	(	az_json_reader *	out_json_reader,
		az_span	json_buffers[],
		int32_t	number_of_buffers,
		az_json_reader_options const *	options
	)

Initializes an az_json_reader to read the JSON payload contained within the provided set of discontiguous buffers.

Parameters

[out]	out_json_reader	A pointer to an az_json_reader instance to initialize.
[in]	json_buffers	An array of non-contiguous byte buffers, as spans, containing the JSON text to read.
[in]	number_of_buffers	The number of buffer segments provided, i.e. the length of the `json_buffers` array.
[in]	options	[nullable] A reference to an az_json_reader_options structure which defines custom behavior of the az_json_reader. If `NULL` is passed, the reader will use the default options (i.e. az_json_reader_options_default()).

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The az_json_reader is initialized successfully.
other	Initialization failed.

Remarks: The provided array of json buffers must not be empty, as that is invalid JSON, and therefore number_of_buffers must also be greater than 0. The array must also not contain any empty span segments.; An instance of az_json_reader must not outlive the lifetime of the JSON payload within the json_buffers.

◆ az_json_reader_init()

AZ_NODISCARD az_result az_json_reader_init	(	az_json_reader *	out_json_reader,
		az_span	json_buffer,
		az_json_reader_options const *	options
	)

Initializes an az_json_reader to read the JSON payload contained within the provided buffer.

Parameters

[out]	out_json_reader	A pointer to an az_json_reader instance to initialize.
[in]	json_buffer	An az_span over the byte buffer containing the JSON text to read.
[in]	options	[nullable] A reference to an az_json_reader_options structure which defines custom behavior of the az_json_reader. If `NULL` is passed, the reader will use the default options (i.e. az_json_reader_options_default()).

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The az_json_reader is initialized successfully.
other	Initialization failed.

Remarks: The provided json buffer must not be empty, as that is invalid JSON.; An instance of az_json_reader must not outlive the lifetime of the JSON payload within the json_buffer.

◆ az_json_reader_next_token()

AZ_NODISCARD az_result az_json_reader_next_token ( az_json_reader * ref_json_reader )

Reads the next token in the JSON text and updates the reader state.

Parameters

[in,out] ref_json_reader A pointer to an az_json_reader instance containing the JSON to read.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The token was read successfully.
AZ_ERROR_UNEXPECTED_END	The end of the JSON document is reached.
AZ_ERROR_UNEXPECTED_CHAR	An invalid character is detected.
AZ_ERROR_JSON_READER_DONE	No more JSON text left to process.

◆ az_json_reader_options_default()

AZ_NODISCARD AZ_INLINE az_json_reader_options az_json_reader_options_default ( )

Gets the default json reader options which reads the JSON strictly according to the JSON RFC.

Call this to obtain an initialized az_json_reader_options structure that can be modified and passed to az_json_reader_init().

Returns: The default az_json_reader_options.

◆ az_json_reader_skip_children()

AZ_NODISCARD az_result az_json_reader_skip_children ( az_json_reader * ref_json_reader )

Reads and skips over any nested JSON elements.

Parameters

[in,out] ref_json_reader A pointer to an az_json_reader instance containing the JSON to read.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The children of the current JSON token are skipped successfully.
AZ_ERROR_UNEXPECTED_END	The end of the JSON document is reached.
AZ_ERROR_UNEXPECTED_CHAR	An invalid character is detected.

Remarks: If the current token kind is a property name, the reader first moves to the property value. Then, if the token kind is start of an object or array, the reader moves to the matching end object or array. For all other token kinds, the reader doesn't move and returns AZ_OK.

◆ az_json_string_unescape()

AZ_NODISCARD az_span az_json_string_unescape	(	az_span	json_string,
		az_span	destination
	)

Unescapes the JSON string within the provided az_span.

Parameters

[in]	json_string	The az_span that contains the string to be unescaped.
	destination	The destination buffer used to write the unescaped output into.

Returns: An az_span that is a slice of the destination az_span containing the unescaped JSON string, which denotes the length of the unescaped string.

Remarks: For user-defined or unknown input, the buffer referred to by destination must be at least as large as the json_string az_span. Content is copied from the source buffer, while unescaping.; This function assumes that the json_string input is well-formed JSON.; This function assumes that the destination has a large enough size to hold the unescaped json_string.; This API can also be used to perform in place unescaping. However, doing so, is destructive and the input JSON may no longer be valid or parsable.

◆ az_json_token_copy_into_span()

az_span az_json_token_copy_into_span	(	az_json_token const *	json_token,
		az_span	destination
	)

Copies the content of the token az_json_token to the destination az_span.

Parameters

[in]	json_token	A pointer to an az_json_token instance containing the JSON text to copy to the `destination`.
	destination	The az_span whose bytes will be replaced by the JSON text from the `json_token`.

Returns: An az_span that is a slice of the destination az_span (i.e. the remainder) after the token bytes have been copied.

Remarks: The function assumes that the destination has a large enough size to hold the contents of json_token.; If json_token doesn't contain any text, this function will just return destination.

◆ az_json_token_get_boolean()

AZ_NODISCARD az_result az_json_token_get_boolean	(	az_json_token const *	json_token,
		bool *	out_value
	)

Gets the JSON token's boolean.

Parameters

[in]	json_token	A pointer to an az_json_token instance.
[out]	out_value	A pointer to a variable to receive the value.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The boolean value is returned.
AZ_ERROR_JSON_INVALID_STATE	The kind is not AZ_JSON_TOKEN_TRUE or AZ_JSON_TOKEN_FALSE.

◆ az_json_token_get_double()

AZ_NODISCARD az_result az_json_token_get_double	(	az_json_token const *	json_token,
		double *	out_value
	)

Gets the JSON token's number as a double.

Parameters

[in]	json_token	A pointer to an az_json_token instance.
[out]	out_value	A pointer to a variable to receive the value.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The number is returned.
AZ_ERROR_JSON_INVALID_STATE	The kind is not AZ_JSON_TOKEN_NUMBER.
AZ_ERROR_UNEXPECTED_CHAR	The resulting `out_value` wouldn't be a finite double number.

◆ az_json_token_get_int32()

AZ_NODISCARD az_result az_json_token_get_int32	(	az_json_token const *	json_token,
		int32_t *	out_value
	)

Gets the JSON token's number as a 32-bit signed integer.

Parameters

[in]	json_token	A pointer to an az_json_token instance.
[out]	out_value	A pointer to a variable to receive the value.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The number is returned.
AZ_ERROR_JSON_INVALID_STATE	The kind is not AZ_JSON_TOKEN_NUMBER.
AZ_ERROR_UNEXPECTED_CHAR	A non-ASCII digit is found within the token or if it contains a number that would overflow or underflow `int32_t`.

◆ az_json_token_get_int64()

AZ_NODISCARD az_result az_json_token_get_int64	(	az_json_token const *	json_token,
		int64_t *	out_value
	)

Gets the JSON token's number as a 64-bit signed integer.

Parameters

[in]	json_token	A pointer to an az_json_token instance.
[out]	out_value	A pointer to a variable to receive the value.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The number is returned.
AZ_ERROR_JSON_INVALID_STATE	The kind is not AZ_JSON_TOKEN_NUMBER.
AZ_ERROR_UNEXPECTED_CHAR	A non-ASCII digit is found within the token or if it contains a number that would overflow or underflow `int64_t`.

◆ az_json_token_get_string()

AZ_NODISCARD az_result az_json_token_get_string	(	az_json_token const *	json_token,
		char *	destination,
		int32_t	destination_max_size,
		int32_t *	out_string_length
	)

Gets the JSON token's string after unescaping it, if required.

Parameters

[in]	json_token	A pointer to an az_json_token instance.
	destination	A pointer to a buffer where the string should be copied into.
[in]	destination_max_size	The maximum available space within the buffer referred to by `destination`.
[out]	out_string_length	[nullable] Contains the number of bytes written to the `destination` which denote the length of the unescaped string. If `NULL` is passed, the parameter is ignored.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The string is returned.
AZ_ERROR_JSON_INVALID_STATE	The kind is not AZ_JSON_TOKEN_STRING.
AZ_ERROR_NOT_ENOUGH_SPACE	`destination` does not have enough size.

◆ az_json_token_get_uint32()

AZ_NODISCARD az_result az_json_token_get_uint32	(	az_json_token const *	json_token,
		uint32_t *	out_value
	)

Gets the JSON token's number as a 32-bit unsigned integer.

Parameters

[in]	json_token	A pointer to an az_json_token instance.
[out]	out_value	A pointer to a variable to receive the value.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The number is returned.
AZ_ERROR_JSON_INVALID_STATE	The kind is not AZ_JSON_TOKEN_NUMBER.
AZ_ERROR_UNEXPECTED_CHAR	A non-ASCII digit is found within the token or if it contains a number that would overflow or underflow `uint32_t`.

◆ az_json_token_get_uint64()

AZ_NODISCARD az_result az_json_token_get_uint64	(	az_json_token const *	json_token,
		uint64_t *	out_value
	)

Gets the JSON token's number as a 64-bit unsigned integer.

Parameters

[in]	json_token	A pointer to an az_json_token instance.
[out]	out_value	A pointer to a variable to receive the value.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The number is returned.
AZ_ERROR_JSON_INVALID_STATE	The kind is not AZ_JSON_TOKEN_NUMBER.
AZ_ERROR_UNEXPECTED_CHAR	A non-ASCII digit is found within the `json_token` or `json_token` contains a number that would overflow or underflow `uint64_t`.

◆ az_json_token_is_text_equal()

AZ_NODISCARD bool az_json_token_is_text_equal	(	az_json_token const *	json_token,
		az_span	expected_text
	)

Determines whether the unescaped JSON token value that the az_json_token points to is equal to the expected text within the provided byte span by doing a case-sensitive comparison.

Parameters

[in]	json_token	A pointer to an az_json_token instance containing the JSON string token.
[in]	expected_text	The lookup text to compare the token against.

Returns: true if the current JSON token value in the JSON source semantically matches the expected lookup text, with the exact casing; otherwise, false.

Remarks: This operation is only valid for the string and property name token kinds. For all other token kinds, it returns false.

◆ az_json_writer_append_begin_array()

AZ_NODISCARD az_result az_json_writer_append_begin_array ( az_json_writer * ref_json_writer )

Appends the beginning of a JSON array (i.e. [).

Parameters

[in,out] ref_json_writer A pointer to an az_json_writer instance containing the buffer to append the start of array to.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	Array start was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.
AZ_ERROR_JSON_NESTING_OVERFLOW	The depth of the JSON exceeds the maximum allowed depth of 64.

◆ az_json_writer_append_begin_object()

AZ_NODISCARD az_result az_json_writer_append_begin_object ( az_json_writer * ref_json_writer )

Appends the beginning of a JSON object (i.e. {).

Parameters

[in,out] ref_json_writer A pointer to an az_json_writer instance containing the buffer to append the start of object to.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	Object start was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.
AZ_ERROR_JSON_NESTING_OVERFLOW	The depth of the JSON exceeds the maximum allowed depth of 64.

◆ az_json_writer_append_bool()

AZ_NODISCARD az_result az_json_writer_append_bool	(	az_json_writer *	ref_json_writer,
		bool	value
	)

Appends a boolean value (as a JSON literal true or false).

Parameters

[in,out]	ref_json_writer	A pointer to an az_json_writer instance containing the buffer to append the boolean to.
[in]	value	The value to be written as a JSON literal `true` or `false`.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The boolean was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ az_json_writer_append_double()

AZ_NODISCARD az_result az_json_writer_append_double	(	az_json_writer *	ref_json_writer,
		double	value,
		int32_t	fractional_digits
	)

Appends a double number value.

Parameters

[in,out]	ref_json_writer	A pointer to an az_json_writer instance containing the buffer to append the number to.
[in]	value	The value to be written as a JSON number.
[in]	fractional_digits	The number of digits of the `value` to write after the decimal point and truncate the rest.

Note: If you receive an AZ_ERROR_NOT_ENOUGH_SPACE result while appending data for which there is sufficient space, note that the JSON writer requires at least 64 bytes of slack within the output buffer, above the theoretical minimal space needed. The JSON writer pessimistically requires this extra space because it tries to write formatted text in chunks rather than one character at a time, whenever the input data is dynamic in size.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The number was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.
AZ_ERROR_NOT_SUPPORTED	The `value` contains an integer component that is too large and would overflow beyond `2^53 - 1`.

Remarks: Only finite double values are supported. Values such as NAN and INFINITY are not allowed and would lead to invalid JSON being written.; Non-significant trailing zeros (after the decimal point) are not written, even if fractional_digits is large enough to allow the zero padding.; The fractional_digits must be between 0 and 15 (inclusive). Any value passed in that is larger will be clamped down to 15.

◆ az_json_writer_append_end_array()

AZ_NODISCARD az_result az_json_writer_append_end_array ( az_json_writer * ref_json_writer )

Appends the end of the current JSON array (i.e. ]).

Parameters

[in,out] ref_json_writer A pointer to an az_json_writer instance containing the buffer to append the closing character to.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	Array end was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ az_json_writer_append_end_object()

AZ_NODISCARD az_result az_json_writer_append_end_object ( az_json_writer * ref_json_writer )

Appends the end of the current JSON object (i.e. }).

Parameters

[in,out] ref_json_writer A pointer to an az_json_writer instance containing the buffer to append the closing character to.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	Object end was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ az_json_writer_append_int32()

AZ_NODISCARD az_result az_json_writer_append_int32	(	az_json_writer *	ref_json_writer,
		int32_t	value
	)

Appends an int32_t number value.

Parameters

[in,out]	ref_json_writer	A pointer to an az_json_writer instance containing the buffer to append the number to.
[in]	value	The value to be written as a JSON number.

Note: If you receive an AZ_ERROR_NOT_ENOUGH_SPACE result while appending data for which there is sufficient space, note that the JSON writer requires at least 64 bytes of slack within the output buffer, above the theoretical minimal space needed. The JSON writer pessimistically requires this extra space because it tries to write formatted text in chunks rather than one character at a time, whenever the input data is dynamic in size.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The number was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ az_json_writer_append_json_text()

AZ_NODISCARD az_result az_json_writer_append_json_text	(	az_json_writer *	ref_json_writer,
		az_span	json_text
	)

Appends an existing UTF-8 encoded JSON text into the buffer, useful for appending nested JSON.

Parameters

[in,out]	ref_json_writer	A pointer to an az_json_writer instance containing the buffer to append the JSON text to.
[in]	json_text	A single, possibly nested, valid, UTF-8 encoded, JSON value to be written as is, without any formatting or spacing changes. No modifications are made to this text, including escaping.

Note: If you receive an AZ_ERROR_NOT_ENOUGH_SPACE result while appending data for which there is sufficient space, note that the JSON writer requires at least 64 bytes of slack within the output buffer, above the theoretical minimal space needed. The JSON writer pessimistically requires this extra space because it tries to write formatted text in chunks rather than one character at a time, whenever the input data is dynamic in size.

Remarks: A single, possibly nested, JSON value is one that starts and ends with {} or [] or is a single primitive token. The JSON cannot start with an end object or array, or a property name, or be incomplete.; The function validates that the provided JSON to be appended is valid and properly escaped, and fails otherwise.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The provided `json_text` was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The destination is too small for the provided `json_text`.
AZ_ERROR_JSON_INVALID_STATE	The `ref_json_writer` is in a state where the `json_text` cannot be appended because it would result in invalid JSON.
AZ_ERROR_UNEXPECTED_END	The provided `json_text` is invalid because it is incomplete and ends too early.
AZ_ERROR_UNEXPECTED_CHAR	The provided `json_text` is invalid because of an unexpected character.

◆ az_json_writer_append_null()

AZ_NODISCARD az_result az_json_writer_append_null ( az_json_writer * ref_json_writer )

Appends the JSON literal null.

Parameters

[in,out] ref_json_writer A pointer to an az_json_writer instance containing the buffer to append the null literal to.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	`null` was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ az_json_writer_append_property_name()

AZ_NODISCARD az_result az_json_writer_append_property_name	(	az_json_writer *	ref_json_writer,
		az_span	name
	)

Appends the UTF-8 property name (as a JSON string) which is the first part of a name/value pair of a JSON object.

Parameters

[in,out]	ref_json_writer	A pointer to an az_json_writer instance containing the buffer to append the property name to.
[in]	name	The UTF-8 encoded property name of the JSON value to be written. The name is escaped before writing.

Note: If you receive an AZ_ERROR_NOT_ENOUGH_SPACE result while appending data for which there is sufficient space, note that the JSON writer requires at least 64 bytes of slack within the output buffer, above the theoretical minimal space needed. The JSON writer pessimistically requires this extra space because it tries to write formatted text in chunks rather than one character at a time, whenever the input data is dynamic in size.

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The property name was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ az_json_writer_append_string()

AZ_NODISCARD az_result az_json_writer_append_string	(	az_json_writer *	ref_json_writer,
		az_span	value
	)

Appends the UTF-8 text value (as a JSON string) into the buffer.

Parameters

[in,out]	ref_json_writer	A pointer to an az_json_writer instance containing the buffer to append the string value to.
[in]	value	The UTF-8 encoded value to be written as a JSON string. The value is escaped before writing.

Note: If you receive an AZ_ERROR_NOT_ENOUGH_SPACE result while appending data for which there is sufficient space, note that the JSON writer requires at least 64 bytes of slack within the output buffer, above the theoretical minimal space needed. The JSON writer pessimistically requires this extra space because it tries to write formatted text in chunks rather than one character at a time, whenever the input data is dynamic in size.

Remarks: If value is AZ_SPAN_EMPTY, the empty JSON string value is written (i.e. "").

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The string value was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACE	The buffer is too small.

◆ az_json_writer_chunked_init()

AZ_NODISCARD az_result az_json_writer_chunked_init	(	az_json_writer *	out_json_writer,
		az_span	first_destination_buffer,
		az_span_allocator_fn	allocator_callback,
		void *	user_context,
		az_json_writer_options const *	options
	)

Initializes an az_json_writer which writes JSON text into a destination that can contain non-contiguous buffers.

Parameters

[out]	out_json_writer	A pointer to an az_json_writer the instance to initialize.
[in]	first_destination_buffer	An az_span over the byte buffer where the JSON text is to be written at the start.
[in]	allocator_callback	An az_span_allocator_fn callback function that provides the destination span to write the JSON text to once the previous buffer is full or too small to contain the next token.
	user_context	A context specific user-defined struct or set of fields that is passed through to calls to the az_span_allocator_fn.
[in]	options	[nullable] A reference to an az_json_writer_options structure which defines custom behavior of the az_json_writer. If `NULL` is passed, the writer will use the default options (i.e. az_json_writer_options_default()).

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	The az_json_writer is initialized successfully.
other	Failure.

◆ az_json_writer_get_bytes_used_in_destination()

AZ_NODISCARD AZ_INLINE az_span az_json_writer_get_bytes_used_in_destination ( az_json_writer const * json_writer )

Returns the az_span containing the JSON text written to the underlying buffer so far, in the last provided destination buffer.

Parameters

[in] json_writer A pointer to an az_json_writer instance wrapping the destination buffer.

Note: Do NOT modify or override the contents of the returned az_span unless you are no longer writing JSON text into it.

Returns: An az_span containing the JSON text built so far.

Remarks: This function returns the entire JSON text when it fits in the first provided buffer, where the destination is a single, contiguous buffer. When the destination can be a set of non-contiguous buffers (using az_json_writer_chunked_init()), and the JSON is larger than the first provided destination span, this function only returns the text written into the last provided destination buffer from the allocator callback.

◆ az_json_writer_init()

AZ_NODISCARD az_result az_json_writer_init	(	az_json_writer *	out_json_writer,
		az_span	destination_buffer,
		az_json_writer_options const *	options
	)

Initializes an az_json_writer which writes JSON text into a buffer.

Parameters

[out]	out_json_writer	A pointer to an az_json_writer instance to initialize.
	destination_buffer	An az_span over the byte buffer where the JSON text is to be written.
[in]	options	[nullable] A reference to an az_json_writer_options structure which defines custom behavior of the az_json_writer. If `NULL` is passed, the writer will use the default options (i.e. az_json_writer_options_default()).

Returns: An az_result value indicating the result of the operation.

Return values

AZ_OK	az_json_writer is initialized successfully.
other	Initialization failed.

◆ az_json_writer_options_default()

AZ_NODISCARD AZ_INLINE az_json_writer_options az_json_writer_options_default ( )

Gets the default json writer options which builds minimized JSON (with no extra white space) according to the JSON RFC.

Call this to obtain an initialized az_json_writer_options structure that can be modified and passed to az_json_writer_init().

Returns: The default az_json_writer_options.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ az_json_token_kind

Function Documentation

◆ az_json_reader_chunked_init()

◆ az_json_reader_init()

◆ az_json_reader_next_token()

◆ az_json_reader_options_default()

◆ az_json_reader_skip_children()

◆ az_json_string_unescape()

◆ az_json_token_copy_into_span()

◆ az_json_token_get_boolean()

◆ az_json_token_get_double()

◆ az_json_token_get_int32()

◆ az_json_token_get_int64()

◆ az_json_token_get_string()

◆ az_json_token_get_uint32()

◆ az_json_token_get_uint64()

◆ az_json_token_is_text_equal()

◆ az_json_writer_append_begin_array()

◆ az_json_writer_append_begin_object()

◆ az_json_writer_append_bool()

◆ az_json_writer_append_double()

◆ az_json_writer_append_end_array()

◆ az_json_writer_append_end_object()

◆ az_json_writer_append_int32()

◆ az_json_writer_append_json_text()

◆ az_json_writer_append_null()

◆ az_json_writer_append_property_name()

◆ az_json_writer_append_string()

◆ az_json_writer_chunked_init()

◆ az_json_writer_get_bytes_used_in_destination()

◆ az_json_writer_init()

◆ az_json_writer_options_default()