Azure SDK for Embedded C
Data Structures | Enumerations | Functions
az_json.h File Reference

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>

Go to the source code of this file.

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

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_readerA pointer to an az_json_reader instance to initialize.
[in]json_buffersAn array of non-contiguous byte buffers, as spans, containing the JSON text to read.
[in]number_of_buffersThe 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_OKThe az_json_reader is initialized successfully.
otherInitialization 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_readerA pointer to an az_json_reader instance to initialize.
[in]json_bufferAn 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_OKThe az_json_reader is initialized successfully.
otherInitialization 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_readerA 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_OKThe token was read successfully.
AZ_ERROR_UNEXPECTED_ENDThe end of the JSON document is reached.
AZ_ERROR_UNEXPECTED_CHARAn invalid character is detected.
AZ_ERROR_JSON_READER_DONENo 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_readerA 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_OKThe children of the current JSON token are skipped successfully.
AZ_ERROR_UNEXPECTED_ENDThe end of the JSON document is reached.
AZ_ERROR_UNEXPECTED_CHARAn 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_stringThe az_span that contains the string to be unescaped.
destinationThe 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_tokenA pointer to an az_json_token instance containing the JSON text to copy to the destination.
destinationThe 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_tokenA pointer to an az_json_token instance.
[out]out_valueA pointer to a variable to receive the value.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKThe boolean value is returned.
AZ_ERROR_JSON_INVALID_STATEThe 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_tokenA pointer to an az_json_token instance.
[out]out_valueA pointer to a variable to receive the value.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKThe number is returned.
AZ_ERROR_JSON_INVALID_STATEThe kind is not AZ_JSON_TOKEN_NUMBER.
AZ_ERROR_UNEXPECTED_CHARThe 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_tokenA pointer to an az_json_token instance.
[out]out_valueA pointer to a variable to receive the value.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKThe number is returned.
AZ_ERROR_JSON_INVALID_STATEThe kind is not AZ_JSON_TOKEN_NUMBER.
AZ_ERROR_UNEXPECTED_CHARA 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_tokenA pointer to an az_json_token instance.
[out]out_valueA pointer to a variable to receive the value.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKThe number is returned.
AZ_ERROR_JSON_INVALID_STATEThe kind is not AZ_JSON_TOKEN_NUMBER.
AZ_ERROR_UNEXPECTED_CHARA 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_tokenA pointer to an az_json_token instance.
destinationA pointer to a buffer where the string should be copied into.
[in]destination_max_sizeThe 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_OKThe string is returned.
AZ_ERROR_JSON_INVALID_STATEThe kind is not AZ_JSON_TOKEN_STRING.
AZ_ERROR_NOT_ENOUGH_SPACEdestination 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_tokenA pointer to an az_json_token instance.
[out]out_valueA pointer to a variable to receive the value.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKThe number is returned.
AZ_ERROR_JSON_INVALID_STATEThe kind is not AZ_JSON_TOKEN_NUMBER.
AZ_ERROR_UNEXPECTED_CHARA 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_tokenA pointer to an az_json_token instance.
[out]out_valueA pointer to a variable to receive the value.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKThe number is returned.
AZ_ERROR_JSON_INVALID_STATEThe kind is not AZ_JSON_TOKEN_NUMBER.
AZ_ERROR_UNEXPECTED_CHARA 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_tokenA pointer to an az_json_token instance containing the JSON string token.
[in]expected_textThe 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_writerA 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_OKArray start was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACEThe buffer is too small.
AZ_ERROR_JSON_NESTING_OVERFLOWThe 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_writerA 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_OKObject start was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACEThe buffer is too small.
AZ_ERROR_JSON_NESTING_OVERFLOWThe 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_writerA pointer to an az_json_writer instance containing the buffer to append the boolean to.
[in]valueThe 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_OKThe boolean was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACEThe 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_writerA pointer to an az_json_writer instance containing the buffer to append the number to.
[in]valueThe value to be written as a JSON number.
[in]fractional_digitsThe 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_OKThe number was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACEThe buffer is too small.
AZ_ERROR_NOT_SUPPORTEDThe 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_writerA 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_OKArray end was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACEThe 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_writerA 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_OKObject end was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACEThe 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_writerA pointer to an az_json_writer instance containing the buffer to append the number to.
[in]valueThe 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_OKThe number was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACEThe 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_writerA pointer to an az_json_writer instance containing the buffer to append the JSON text to.
[in]json_textA 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_OKThe provided json_text was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACEThe destination is too small for the provided json_text.
AZ_ERROR_JSON_INVALID_STATEThe ref_json_writer is in a state where the json_text cannot be appended because it would result in invalid JSON.
AZ_ERROR_UNEXPECTED_ENDThe provided json_text is invalid because it is incomplete and ends too early.
AZ_ERROR_UNEXPECTED_CHARThe 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_writerA 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_OKnull was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACEThe 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_writerA pointer to an az_json_writer instance containing the buffer to append the property name to.
[in]nameThe 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_OKThe property name was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACEThe 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_writerA pointer to an az_json_writer instance containing the buffer to append the string value to.
[in]valueThe 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_OKThe string value was appended successfully.
AZ_ERROR_NOT_ENOUGH_SPACEThe 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_writerA pointer to an az_json_writer the instance to initialize.
[in]first_destination_bufferAn az_span over the byte buffer where the JSON text is to be written at the start.
[in]allocator_callbackAn 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_contextA 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_OKThe az_json_writer is initialized successfully.
otherFailure.

◆ 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_writerA 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_writerA pointer to an az_json_writer instance to initialize.
destination_bufferAn 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_OKaz_json_writer is initialized successfully.
otherInitialization 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.