Mutable JSON value, 24 bytes.
The ‘tag’ and ‘uni’ field is same as immutable value.
The ‘next’ field links all elements inside the container to be a cycle.
Allow reading invalid unicode when parsing string values (non-standard).
Invalid characters will be allowed to appear in the string values, but
invalid escape sequences will still be reported as errors.
This flag does not affect the performance of correctly encoded strings.
Read big numbers as raw strings. These big numbers include integers that
cannot be represented by int64_t and uint64_t, and floating-point
numbers that cannot be represented by finite double.
The flag will be overridden by YYJSON_READ_NUMBER_AS_RAW flag.
Read the input data in-situ.
This option allows the reader to modify and use input data to store string
values, which can increase reading speed slightly.
The caller should hold the input data before free the document.
The input data must be padded by at least YYJSON_PADDING_SIZE bytes.
For example: [1,2] should be [1,2]\0\0\0\0, input length should be 5.
Stop when done instead of issuing an error if there’s additional content
after a JSON document. This option may be used to parse small pieces of JSON
in larger data, such as NDJSON.
Allow invalid unicode when encoding string values (non-standard).
Invalid characters in string value will be copied byte by byte.
If YYJSON_WRITE_ESCAPE_UNICODE flag is also set, invalid character will be
escaped as U+FFFD (replacement character).
This flag does not affect the performance of correctly encoded strings.
Returns the element at the specified position in this array.
Returns NULL if array is NULL/empty or the index is out of bounds.
@warning This function takes a linear search time if array is not flat.
For example: [1,{},3] is flat, [1,[2],3] is not flat.
Returns the last element of this array.
Returns NULL if arr is NULL/empty or type is not array.
@warning This function takes a linear search time if array is not flat.
For example: [1,{},3] is flat, [1,[2],3] is not flat.
Release the JSON document and free the memory.
After calling this function, the doc and all values from the doc are no
longer available. This function will do nothing if the doc is NULL.
Copies and returns a new mutable document from input, returns NULL on error.
This makes a deep-copy on the immutable document.
If allocator is NULL, the default allocator will be used.
@note imut_doc -> mut_doc.
Returns whether two JSON values are equal (deep compare).
Returns false if input is NULL.
@note the result may be inaccurate if object has duplicate keys.
@warning This function is recursive and may cause a stack overflow
if the object level is too deep.
Returns whether the JSON value is equals to a string.
The str should be a UTF-8 string, null-terminator is not required.
Returns false if input is NULL or type is not string.
Returns the JSON value’s type description.
The return value should be one of these strings: “raw”, “null”, “string”,
“array”, “object”, “true”, “false”, “uint”, “sint”, “real”, “unknown”.
Creates and returns an empty mutable array.
@param doc A mutable document, used for memory allocation only.
@return The new array. NULL if input is NULL or memory allocation failed.
Creates and adds a new array at the end of the array.
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@return The new array, or NULL on error.
Adds a bool value at the end of the array.
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param val The bool value to be added.
@return Whether successful.
Adds a double value at the end of the array.
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param num The number to be added.
@return Whether successful.
Adds a false value at the end of the array.
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@return Whether successful.
Adds a float value at the end of the array.
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param num The number to be added.
@return Whether successful.
Adds an integer value at the end of the array.
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param num The number to be added.
@return Whether successful.
Adds a null value at the end of the array.
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@return Whether successful.
Creates and adds a new object at the end of the array.
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@return The new object, or NULL on error.
Adds a double value at the end of the array.
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param num The number to be added.
@return Whether successful.
Adds a signed integer value at the end of the array.
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param num The number to be added.
@return Whether successful.
Adds a string value at the end of the array (no copy).
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param str A null-terminated UTF-8 string.
@return Whether successful.
@warning The input string is not copied, you should keep this string unmodified
for the lifetime of this JSON document.
Adds a string value at the end of the array (copied).
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param str A null-terminated UTF-8 string.
@return Whether successful.
Adds a string value at the end of the array (no copy).
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param str A UTF-8 string, null-terminator is not required.
@param len The length of the string, in bytes.
@return Whether successful.
@warning The input string is not copied, you should keep this string unmodified
for the lifetime of this JSON document.
Adds a string value at the end of the array (copied).
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param str A UTF-8 string, null-terminator is not required.
@param len The length of the string, in bytes.
@return Whether successful.
Adds a true value at the end of the array.
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@return Whether successful.
Adds an unsigned integer value at the end of the array.
@param doc The doc is only used for memory allocation.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param num The number to be added.
@return Whether successful.
Adds a value at the end of the array.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param val The value to be inserted. Returns false if it is NULL.
@return Whether successful.
Inserts a value at the end of the array.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param val The value to be inserted. Returns false if it is NULL.
@return Whether successful.
Removes all values in this array.
@param arr The array from which all of the values are to be removed.
Returns false if it is NULL or not an array.
@return Whether successful.
Returns the element at the specified position in this array.
Returns NULL if array is NULL/empty or the index is out of bounds.
@warning This function takes a linear search time.
Inserts a value into an array at a given index.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param val The value to be inserted. Returns false if it is NULL.
@param idx The index to which to insert the new value.
Returns false if the index is out of range.
@return Whether successful.
@warning This function takes a linear search time.
Inserts a value at the head of the array.
@param arr The array to which the value is to be inserted.
Returns false if it is NULL or not an array.
@param val The value to be inserted. Returns false if it is NULL.
@return Whether successful.
Removes and returns a value at index.
@param arr The array from which the value is to be removed.
Returns false if it is NULL or not an array.
@param idx The index from which to remove the value.
Returns false if the index is out of range.
@return Old value, or NULL on error.
@warning This function takes a linear search time.
Removes and returns the first value in this array.
@param arr The array from which the value is to be removed.
Returns false if it is NULL or not an array.
@return The first value, or NULL on error.
Removes and returns the last value in this array.
@param arr The array from which the value is to be removed.
Returns false if it is NULL or not an array.
@return The last value, or NULL on error.
Removes all values within a specified range in the array.
@param arr The array from which the value is to be removed.
Returns false if it is NULL or not an array.
@param idx The start index of the range (0 is the first).
@param len The number of items in the range (can be 0).
@return Whether successful.
@warning This function takes a linear search time.
Replaces a value at index and returns old value.
@param arr The array to which the value is to be replaced.
Returns false if it is NULL or not an array.
@param idx The index to which to replace the value.
Returns false if the index is out of range.
@param val The new value to replace. Returns false if it is NULL.
@return Old value, or NULL on error.
@warning This function takes a linear search time.
Rotates values in this array for the given number of times.
For example: [1,2,3,4,5] rotate 2 is [3,4,5,1,2].
@param arr The array to be rotated.
@param idx Index (or times) to rotate.
@warning This function takes a linear search time.
Release the JSON document and free the memory.
After calling this function, the doc and all values from the doc are no
longer available. This function will do nothing if the doc is NULL.
Copies and returns a new immutable document from input,
returns NULL on error. This makes a deep-copy on the mutable document.
The returned document should be freed with yyjson_doc_free().
@note mut_doc -> imut_doc.
@warning This function is recursive and may cause a stack overflow
if the object level is too deep.
Copies and returns a new mutable document from input, returns NULL on error.
This makes a deep-copy on the mutable document.
If allocator is NULL, the default allocator will be used.
@note mut_doc -> mut_doc.
Set the string pool size for a mutable document.
This function does not allocate memory immediately, but uses the size when
the next memory allocation is needed.
Set the value pool size for a mutable document.
This function does not allocate memory immediately, but uses the size when
the next memory allocation is needed.
Returns whether two JSON values are equal (deep compare).
Returns false if input is NULL.
@note the result may be inaccurate if object has duplicate keys.
@warning This function is recursive and may cause a stack overflow
if the object level is too deep.
Returns whether the JSON value is equals to a string.
The str should be a null-terminated UTF-8 string.
Returns false if input is NULL or type is not string.
Returns whether the JSON value is equals to a string.
The str should be a UTF-8 string, null-terminator is not required.
Returns false if input is NULL or type is not string.
Returns the JSON value’s type description.
The return value should be one of these strings: “raw”, “null”, “string”,
“array”, “object”, “true”, “false”, “uint”, “sint”, “real”, “unknown”.
Adds a key-value pair at the end of the object.
This function allows duplicated key in one object.
@param obj The object to which the new key-value pair is to be added.
@param key The key, should be a string which is created by yyjson_mut_str(),
yyjson_mut_strn(), yyjson_mut_strcpy() or yyjson_mut_strncpy().
@param val The value to add to the object.
@return Whether successful.
Creates and adds a new array to the target object.
The key should be a null-terminated UTF-8 string.
This function allows duplicated key in one object.
Creates and adds a new object to the target object.
The key should be a null-terminated UTF-8 string.
This function allows duplicated key in one object.
Adds a signed integer value at the end of the object.
The key should be a null-terminated UTF-8 string.
This function allows duplicated key in one object.
Adds a string value at the end of the object.
The key and val should be null-terminated UTF-8 strings.
This function allows duplicated key in one object.
Adds a string value at the end of the object.
The key and val should be null-terminated UTF-8 strings.
The value string is copied.
This function allows duplicated key in one object.
Adds a string value at the end of the object.
The key should be a null-terminated UTF-8 string.
The val should be a UTF-8 string, null-terminator is not required.
The len should be the length of the val, in bytes.
This function allows duplicated key in one object.
Adds a string value at the end of the object.
The key should be a null-terminated UTF-8 string.
The val should be a UTF-8 string, null-terminator is not required.
The len should be the length of the val, in bytes.
This function allows duplicated key in one object.
Adds an unsigned integer value at the end of the object.
The key should be a null-terminated UTF-8 string.
This function allows duplicated key in one object.
Returns the value to which the specified key is mapped.
Returns NULL if this object contains no mapping for the key.
Returns NULL if obj/key is NULL, or type is not object.
Returns the value to which the specified key is mapped.
Returns NULL if this object contains no mapping for the key.
Returns NULL if obj/key is NULL, or type is not object.
Inserts a key-value pair to the object at the given position.
This function allows duplicated key in one object.
@param obj The object to which the new key-value pair is to be added.
@param key The key, should be a string which is created by yyjson_mut_str(),
yyjson_mut_strn(), yyjson_mut_strcpy() or yyjson_mut_strncpy().
@param val The value to add to the object.
@param idx The index to which to insert the new pair.
@return Whether successful.
Sets a key-value pair at the end of the object.
This function may remove all key-value pairs for the given key before add.
@param obj The object to which the new key-value pair is to be added.
@param key The key, should be a string which is created by yyjson_mut_str(),
yyjson_mut_strn(), yyjson_mut_strcpy() or yyjson_mut_strncpy().
@param val The value to add to the object. If this value is null, the behavior
is same as yyjson_mut_obj_remove().
@return Whether successful.
Removes all key-value pair from the object with given key.
@param obj The object from which the key-value pair is to be removed.
@param key The key, should be a string value.
@return The first matched value, or NULL if no matched value.
@warning This function takes a linear search time.
Removes all key-value pair from the object with given key.
@param obj The object from which the key-value pair is to be removed.
@param key The key, should be a UTF-8 string with null-terminator.
@return The first matched value, or NULL if no matched value.
@warning This function takes a linear search time.
Removes all key-value pair from the object with given key.
@param obj The object from which the key-value pair is to be removed.
@param key The key, should be a UTF-8 string, null-terminator is not required.
@param key_len The length of the key.
@return The first matched value, or NULL if no matched value.
@warning This function takes a linear search time.
Removes all key-value pairs for the given key.
Returns the first value to which the specified key is mapped or NULL if this
object contains no mapping for the key.
The key should be a null-terminated UTF-8 string.
Removes all key-value pairs for the given key.
Returns the first value to which the specified key is mapped or NULL if this
object contains no mapping for the key.
The key should be a UTF-8 string, null-terminator is not required.
The len should be the length of the key, in bytes.
Replaces all matching keys with the new key.
Returns true if at least one key was renamed.
The key and new_key should be a null-terminated UTF-8 string.
The new_key is copied and held by doc.
Replaces all matching keys with the new key.
Returns true if at least one key was renamed.
The key and new_key should be a UTF-8 string,
null-terminator is not required. The new_key is copied and held by doc.
Replaces value from the object with given key.
If the key is not exist, or the value is NULL, it will fail.
@param obj The object to which the value is to be replaced.
@param key The key, should be a string value.
@param val The value to replace into the object.
@return Whether successful.
@warning This function takes a linear search time.
Rotates key-value pairs in the object for the given number of times.
For example: {"a":1,"b":2,"c":3,"d":4} rotate 1 is
{"b":2,"c":3,"d":4,"a":1}.
@param obj The object to be rotated.
@param idx Index (or times) to rotate.
@return Whether successful.
@warning This function takes a linear search time.
Creates and returns a mutable object with key-value pairs and pair count,
returns NULL on error. The keys and values are not copied. The strings should
be a null-terminated UTF-8 string.
Creates and returns a mutable object with keys and values, returns NULL on
error. The keys and values are not copied. The strings should be a
null-terminated UTF-8 string.
Creates and returns a raw value, returns NULL on error.
The str should be a null-terminated UTF-8 string.
The input string is copied and held by the document.
Creates and returns a raw value, returns NULL on error.
The str should be a UTF-8 string, null-terminator is not required.
The input string is copied and held by the document.
Set the floating-point number’s output format to fixed-point notation.
Returns false if input is NULL or val is not real type.
@see YYJSON_WRITE_FP_TO_FIXED flag.
@warning This will modify the immutable value, use with caution.
Set the floating-point number’s output format to single-precision.
Returns false if input is NULL or val is not real type.
@see YYJSON_WRITE_FP_TO_FLOAT flag.
@warning This will modify the immutable value, use with caution.
Marks this string as not needing to be escaped during JSON writing.
This can be used to avoid the overhead of escaping if the string contains
only characters that do not require escaping.
Returns false if input is NULL or val is not string.
@see YYJSON_SUBTYPE_NOESC subtype.
@warning This will modify the immutable value, use with caution.
Creates and returns a string value, returns NULL on error.
The str should be a null-terminated UTF-8 string.
@warning The input string is not copied, you should keep this string
unmodified for the lifetime of this JSON document.
Creates and returns a string value, returns NULL on error.
The str should be a null-terminated UTF-8 string.
The input string is copied and held by the document.
Creates and returns a string value, returns NULL on error.
The str should be a UTF-8 string, null-terminator is not required.
@warning The input string is not copied, you should keep this string
unmodified for the lifetime of this JSON document.
Creates and returns a string value, returns NULL on error.
The str should be a UTF-8 string, null-terminator is not required.
The input string is copied and held by the document.
Copies and returns a new immutable document from input,
returns NULL on error. This makes a deep-copy on the mutable value.
The returned document should be freed with yyjson_doc_free().
@note mut_val -> imut_doc.
@warning This function is recursive and may cause a stack overflow
if the object level is too deep.
Copies and returns a new mutable value from input, returns NULL on error.
This makes a deep-copy on the mutable value.
The memory was managed by mutable document.
@note mut_val -> mut_val.
@warning This function is recursive and may cause a stack overflow
if the object level is too deep.
Returns the value to which the specified key is mapped.
Returns NULL if this object contains no mapping for the key.
Returns NULL if obj/key is NULL, or type is not object.
Returns the value to which the specified key is mapped.
Returns NULL if this object contains no mapping for the key.
Returns NULL if obj/key is NULL, or type is not object.
Set the floating-point number’s output format to fixed-point notation.
Returns false if input is NULL or val is not real type.
@see YYJSON_WRITE_FP_TO_FIXED flag.
@warning This will modify the immutable value, use with caution.
Set the floating-point number’s output format to single-precision.
Returns false if input is NULL or val is not real type.
@see YYJSON_WRITE_FP_TO_FLOAT flag.
@warning This will modify the immutable value, use with caution.
Set the value to string (null-terminated).
Returns false if input is NULL or val is object or array.
@warning This will modify the immutable value, use with caution.
Marks this string as not needing to be escaped during JSON writing.
This can be used to avoid the overhead of escaping if the string contains
only characters that do not require escaping.
Returns false if input is NULL or val is not string.
@see YYJSON_SUBTYPE_NOESC subtype.
@warning This will modify the immutable value, use with caution.
Set the value to string (with length).
Returns false if input is NULL or val is object or array.
@warning This will modify the immutable value, use with caution.
Copies and returns a new mutable value from input, returns NULL on error.
This makes a deep-copy on the immutable value.
The memory was managed by mutable document.
@note imut_val -> mut_val.