JSON-YY
view release on metacpan or search on metacpan
#ifndef YYJSON_DISABLE_FAST_FP_CONV
#endif
/*
Define as 1 to disable non-standard JSON features support at compile-time,
such as YYJSON_READ_ALLOW_XXX and YYJSON_WRITE_ALLOW_XXX.
This reduces binary size by about 10%, and slightly improves performance.
*/
#ifndef YYJSON_DISABLE_NON_STANDARD
#endif
/*
Define as 1 to disable UTF-8 validation at compile-time.
Use this if all input strings are guaranteed to be valid UTF-8
(e.g. language-level String types are already validated).
Disabling UTF-8 validation improves performance for non-ASCII strings by about
3% to 7%.
Note: If this flag is enabled while passing illegal UTF-8 strings,
the following errors may occur:
- Escaped characters may be ignored when parsing JSON strings.
- Ending quotes may be ignored when parsing JSON strings, causing the
string to merge with the next value.
- When serializing with `yyjson_mut_val`, the string's end may be accessed
out of bounds, potentially causing a segmentation fault.
*/
#ifndef YYJSON_DISABLE_UTF8_VALIDATION
#endif
/*
Define as 1 to improve performance on architectures that do not support
unaligned memory access.
Normally, this does not need to be set manually. See the C file for details.
*/
#ifndef YYJSON_DISABLE_UNALIGNED_MEMORY_ACCESS
#endif
/* Define as 1 to export symbols when building this library as a Windows DLL. */
#ifndef YYJSON_EXPORTS
#endif
/* Define as 1 to import symbols when using this library as a Windows DLL. */
#ifndef YYJSON_IMPORTS
#endif
/* Define as 1 to include <stdint.h> for compilers without C99 support. */
#ifndef YYJSON_HAS_STDINT_H
#endif
/* Define as 1 to include <stdbool.h> for compilers without C99 support. */
#ifndef YYJSON_HAS_STDBOOL_H
#endif
/*==============================================================================
* MARK: - Compiler Macros
*============================================================================*/
/** compiler version (MSVC) */
#ifdef _MSC_VER
# define YYJSON_MSC_VER _MSC_VER
#else
# define YYJSON_MSC_VER 0
#endif
/** compiler version (GCC) */
#ifdef __GNUC__
# define YYJSON_GCC_VER __GNUC__
# if defined(__GNUC_PATCHLEVEL__)
# define yyjson_gcc_available(major, minor, patch) \
((__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__) \
>= (major * 10000 + minor * 100 + patch))
# else
# define yyjson_gcc_available(major, minor, patch) \
((__GNUC__ * 10000 + __GNUC_MINOR__ * 100) \
>= (major * 10000 + minor * 100 + patch))
# endif
#else
# define YYJSON_GCC_VER 0
# define yyjson_gcc_available(major, minor, patch) 0
#endif
/** real gcc check */
#if defined(__GNUC__) && defined(__GNUC_MINOR__) && \
!defined(__clang__) && !defined(__llvm__) && \
!defined(__INTEL_COMPILER) && !defined(__ICC) && \
!defined(__NVCC__) && !defined(__PGI) && !defined(__TINYC__)
# define YYJSON_IS_REAL_GCC 1
#else
# define YYJSON_IS_REAL_GCC 0
#endif
/** C version (STDC) */
#if defined(__STDC__) && (__STDC__ >= 1) && defined(__STDC_VERSION__)
# define YYJSON_STDC_VER __STDC_VERSION__
#else
# define YYJSON_STDC_VER 0
#endif
/** C++ version */
#if defined(__cplusplus)
# define YYJSON_CPP_VER __cplusplus
#else
# define YYJSON_CPP_VER 0
#endif
/** compiler builtin check (since gcc 10.0, clang 2.6, icc 2021) */
#ifndef yyjson_has_builtin
# ifdef __has_builtin
# define yyjson_has_builtin(x) __has_builtin(x)
# else
# define yyjson_has_builtin(x) 0
# endif
#endif
/** compiler attribute check (since gcc 5.0, clang 2.9, icc 17) */
/*==============================================================================
* MARK: - JSON Array Iterator API
*============================================================================*/
/**
A JSON array iterator.
@b Example
@code
yyjson_val *val;
yyjson_arr_iter iter = yyjson_arr_iter_with(arr);
while ((val = yyjson_arr_iter_next(&iter))) {
your_func(val);
}
@endcode
*/
typedef struct yyjson_arr_iter {
size_t idx; /**< next value's index */
size_t max; /**< maximum index (arr.size) */
yyjson_val *cur; /**< next value */
} yyjson_arr_iter;
/**
Initialize an iterator for this array.
@param arr The array to be iterated over.
If this parameter is NULL or not an array, `iter` will be set to empty.
@param iter The iterator to be initialized.
If this parameter is NULL, the function will fail and return false.
@return true if the `iter` has been successfully initialized.
@note The iterator does not need to be destroyed.
*/
yyjson_api_inline bool yyjson_arr_iter_init(yyjson_val *arr,
yyjson_arr_iter *iter);
/**
Create an iterator with an array , same as `yyjson_arr_iter_init()`.
@param arr The array to be iterated over.
If this parameter is NULL or not an array, an empty iterator will returned.
@return A new iterator for the array.
@note The iterator does not need to be destroyed.
*/
yyjson_api_inline yyjson_arr_iter yyjson_arr_iter_with(yyjson_val *arr);
/**
Returns whether the iteration has more elements.
If `iter` is NULL, this function will return false.
*/
yyjson_api_inline bool yyjson_arr_iter_has_next(yyjson_arr_iter *iter);
/**
Returns the next element in the iteration, or NULL on end.
If `iter` is NULL, this function will return NULL.
*/
yyjson_api_inline yyjson_val *yyjson_arr_iter_next(yyjson_arr_iter *iter);
/**
Macro for iterating over an array.
It works like iterator, but with a more intuitive API.
@b Example
@code
size_t idx, max;
yyjson_val *val;
yyjson_arr_foreach(arr, idx, max, val) {
your_func(idx, val);
}
@endcode
*/
#define yyjson_arr_foreach(arr, idx, max, val) \
for ((idx) = 0, \
(max) = yyjson_arr_size(arr), \
(val) = yyjson_arr_get_first(arr); \
(idx) < (max); \
(idx)++, \
(val) = unsafe_yyjson_get_next(val))
/*==============================================================================
* MARK: - JSON Object API
*============================================================================*/
/** Returns the number of key-value pairs in this object.
Returns 0 if `obj` is NULL or type is not object. */
yyjson_api_inline size_t yyjson_obj_size(yyjson_val *obj);
/** 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.
The `key` should be a null-terminated UTF-8 string.
@warning This function takes a linear search time. */
yyjson_api_inline yyjson_val *yyjson_obj_get(yyjson_val *obj, const char *key);
/** 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.
The `key` should be a UTF-8 string, null-terminator is not required.
The `key_len` should be the length of the key, in bytes.
@warning This function takes a linear search time. */
yyjson_api_inline yyjson_val *yyjson_obj_getn(yyjson_val *obj, const char *key,
size_t key_len);
/*==============================================================================
* MARK: - JSON Object Iterator API
*============================================================================*/
/**
A JSON object iterator.
@b Example
@code
/**
Returns whether the iteration has more elements.
If `iter` is NULL, this function will return false.
*/
yyjson_api_inline bool yyjson_obj_iter_has_next(yyjson_obj_iter *iter);
/**
Returns the next key in the iteration, or NULL on end.
If `iter` is NULL, this function will return NULL.
*/
yyjson_api_inline yyjson_val *yyjson_obj_iter_next(yyjson_obj_iter *iter);
/**
Returns the value for key inside the iteration.
If `iter` is NULL, this function will return NULL.
*/
yyjson_api_inline yyjson_val *yyjson_obj_iter_get_val(yyjson_val *key);
/**
Iterates to a specified key and returns the value.
This function does the same thing as `yyjson_obj_get()`, but is much faster
if the ordering of the keys is known at compile-time and you are using the same
order to look up the values. If the key exists in this object, then the
iterator will stop at the next key, otherwise the iterator will not change and
NULL is returned.
@param iter The object iterator, should not be NULL.
@param key The key, should be a UTF-8 string with null-terminator.
@return The value to which the specified key is mapped.
NULL if this object contains no mapping for the key or input is invalid.
@warning This function takes a linear search time if the key is not nearby.
*/
yyjson_api_inline yyjson_val *yyjson_obj_iter_get(yyjson_obj_iter *iter,
const char *key);
/**
Iterates to a specified key and returns the value.
This function does the same thing as `yyjson_obj_getn()`, but is much faster
if the ordering of the keys is known at compile-time and you are using the same
order to look up the values. If the key exists in this object, then the
iterator will stop at the next key, otherwise the iterator will not change and
NULL is returned.
@param iter The object iterator, should not be NULL.
@param key The key, should be a UTF-8 string, null-terminator is not required.
@param key_len The the length of `key`, in bytes.
@return The value to which the specified key is mapped.
NULL if this object contains no mapping for the key or input is invalid.
@warning This function takes a linear search time if the key is not nearby.
*/
yyjson_api_inline yyjson_val *yyjson_obj_iter_getn(yyjson_obj_iter *iter,
const char *key,
size_t key_len);
/**
Macro for iterating over an object.
It works like iterator, but with a more intuitive API.
@b Example
@code
size_t idx, max;
yyjson_val *key, *val;
yyjson_obj_foreach(obj, idx, max, key, val) {
your_func(key, val);
}
@endcode
*/
#define yyjson_obj_foreach(obj, idx, max, key, val) \
for ((idx) = 0, \
(max) = yyjson_obj_size(obj), \
(key) = (obj) ? unsafe_yyjson_get_first(obj) : NULL, \
(val) = (key) + 1; \
(idx) < (max); \
(idx)++, \
(key) = unsafe_yyjson_get_next(val), \
(val) = (key) + 1)
/*==============================================================================
* MARK: - Mutable JSON Document API
*============================================================================*/
/** Returns the root value of this JSON document.
Returns NULL if `doc` is NULL. */
yyjson_api_inline yyjson_mut_val *yyjson_mut_doc_get_root(yyjson_mut_doc *doc);
/** Sets the root value of this JSON document.
Pass NULL to clear root value of the document. */
yyjson_api_inline void yyjson_mut_doc_set_root(yyjson_mut_doc *doc,
yyjson_mut_val *root);
/**
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.
If the caller knows the approximate bytes of strings that the document needs to
store (e.g. copy string with `yyjson_mut_strcpy` function), setting a larger
size can avoid multiple memory allocations and improve performance.
@param doc The mutable document.
@param len The desired string pool size in bytes (total string length).
@return true if successful, false if size is 0 or overflow.
*/
yyjson_api bool yyjson_mut_doc_set_str_pool_size(yyjson_mut_doc *doc,
size_t len);
/**
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.
If the caller knows the approximate number of values that the document needs to
store (e.g. create new value with `yyjson_mut_xxx` functions), setting a larger
size can avoid multiple memory allocations and improve performance.
}
}
@endcode
*/
typedef struct yyjson_mut_arr_iter {
size_t idx; /**< next value's index */
size_t max; /**< maximum index (arr.size) */
yyjson_mut_val *cur; /**< current value */
yyjson_mut_val *pre; /**< previous value */
yyjson_mut_val *arr; /**< the array being iterated */
} yyjson_mut_arr_iter;
/**
Initialize an iterator for this array.
@param arr The array to be iterated over.
If this parameter is NULL or not an array, `iter` will be set to empty.
@param iter The iterator to be initialized.
If this parameter is NULL, the function will fail and return false.
@return true if the `iter` has been successfully initialized.
@note The iterator does not need to be destroyed.
*/
yyjson_api_inline bool yyjson_mut_arr_iter_init(yyjson_mut_val *arr,
yyjson_mut_arr_iter *iter);
/**
Create an iterator with an array , same as `yyjson_mut_arr_iter_init()`.
@param arr The array to be iterated over.
If this parameter is NULL or not an array, an empty iterator will returned.
@return A new iterator for the array.
@note The iterator does not need to be destroyed.
*/
yyjson_api_inline yyjson_mut_arr_iter yyjson_mut_arr_iter_with(
yyjson_mut_val *arr);
/**
Returns whether the iteration has more elements.
If `iter` is NULL, this function will return false.
*/
yyjson_api_inline bool yyjson_mut_arr_iter_has_next(
yyjson_mut_arr_iter *iter);
/**
Returns the next element in the iteration, or NULL on end.
If `iter` is NULL, this function will return NULL.
*/
yyjson_api_inline yyjson_mut_val *yyjson_mut_arr_iter_next(
yyjson_mut_arr_iter *iter);
/**
Removes and returns current element in the iteration.
If `iter` is NULL, this function will return NULL.
*/
yyjson_api_inline yyjson_mut_val *yyjson_mut_arr_iter_remove(
yyjson_mut_arr_iter *iter);
/**
Macro for iterating over an array.
It works like iterator, but with a more intuitive API.
@warning You should not modify the array while iterating over it.
@b Example
@code
size_t idx, max;
yyjson_mut_val *val;
yyjson_mut_arr_foreach(arr, idx, max, val) {
your_func(idx, val);
}
@endcode
*/
#define yyjson_mut_arr_foreach(arr, idx, max, val) \
for ((idx) = 0, \
(max) = yyjson_mut_arr_size(arr), \
(val) = yyjson_mut_arr_get_first(arr); \
(idx) < (max); \
(idx)++, \
(val) = (val)->next)
/*==============================================================================
* MARK: - Mutable JSON Array Creation API
*============================================================================*/
/**
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.
*/
yyjson_api_inline yyjson_mut_val *yyjson_mut_arr(yyjson_mut_doc *doc);
/**
Creates and returns a new mutable array with the given boolean values.
@param doc A mutable document, used for memory allocation only.
If this parameter is NULL, the function will fail and return NULL.
@param vals A C array of boolean values.
@param count The value count. If this value is 0, an empty array will return.
@return The new array. NULL if input is invalid or memory allocation failed.
@b Example
@code
const bool vals[3] = { true, false, true };
yyjson_mut_val *arr = yyjson_mut_arr_with_bool(doc, vals, 3);
@endcode
*/
yyjson_api_inline yyjson_mut_val *yyjson_mut_arr_with_bool(
yyjson_mut_doc *doc, const bool *vals, size_t count);
/**
Creates and returns a new mutable array with the given sint numbers.
@param doc A mutable document, used for memory allocation only.
If this parameter is NULL, the function will fail and return NULL.
@param vals A C array of sint numbers.
@param count The number count. If this value is 0, an empty array will return.
@return The new array. NULL if input is invalid or memory allocation failed.
Returns the next key in the iteration, or NULL on end.
If `iter` is NULL, this function will return NULL.
*/
yyjson_api_inline yyjson_mut_val *yyjson_mut_obj_iter_next(
yyjson_mut_obj_iter *iter);
/**
Returns the value for key inside the iteration.
If `iter` is NULL, this function will return NULL.
*/
yyjson_api_inline yyjson_mut_val *yyjson_mut_obj_iter_get_val(
yyjson_mut_val *key);
/**
Removes current key-value pair in the iteration, returns the removed value.
If `iter` is NULL, this function will return NULL.
*/
yyjson_api_inline yyjson_mut_val *yyjson_mut_obj_iter_remove(
yyjson_mut_obj_iter *iter);
/**
Iterates to a specified key and returns the value.
This function does the same thing as `yyjson_mut_obj_get()`, but is much faster
if the ordering of the keys is known at compile-time and you are using the same
order to look up the values. If the key exists in this object, then the
iterator will stop at the next key, otherwise the iterator will not change and
NULL is returned.
@param iter The object iterator, should not be NULL.
@param key The key, should be a UTF-8 string with null-terminator.
@return The value to which the specified key is mapped.
NULL if this object contains no mapping for the key or input is invalid.
@warning This function takes a linear search time if the key is not nearby.
*/
yyjson_api_inline yyjson_mut_val *yyjson_mut_obj_iter_get(
yyjson_mut_obj_iter *iter, const char *key);
/**
Iterates to a specified key and returns the value.
This function does the same thing as `yyjson_mut_obj_getn()` but is much faster
if the ordering of the keys is known at compile-time and you are using the same
order to look up the values. If the key exists in this object, then the
iterator will stop at the next key, otherwise the iterator will not change and
NULL is returned.
@param iter The object iterator, should not be NULL.
@param key The key, should be a UTF-8 string, null-terminator is not required.
@param key_len The the length of `key`, in bytes.
@return The value to which the specified key is mapped.
NULL if this object contains no mapping for the key or input is invalid.
@warning This function takes a linear search time if the key is not nearby.
*/
yyjson_api_inline yyjson_mut_val *yyjson_mut_obj_iter_getn(
yyjson_mut_obj_iter *iter, const char *key, size_t key_len);
/**
Macro for iterating over an object.
It works like iterator, but with a more intuitive API.
@warning You should not modify the object while iterating over it.
@b Example
@code
size_t idx, max;
yyjson_mut_val *key, *val;
yyjson_mut_obj_foreach(obj, idx, max, key, val) {
your_func(key, val);
}
@endcode
*/
#define yyjson_mut_obj_foreach(obj, idx, max, key, val) \
for ((idx) = 0, \
(max) = yyjson_mut_obj_size(obj), \
(key) = (max) ? ((yyjson_mut_val *)(obj)->uni.ptr)->next->next : NULL, \
(val) = (key) ? (key)->next : NULL; \
(idx) < (max); \
(idx)++, \
(key) = (val)->next, \
(val) = (key)->next)
/*==============================================================================
* MARK: - Mutable JSON Object Creation API
*============================================================================*/
/** Creates and returns a mutable object, returns NULL on error. */
yyjson_api_inline yyjson_mut_val *yyjson_mut_obj(yyjson_mut_doc *doc);
/**
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.
@warning The input string is not copied, you should keep this string
unmodified for the lifetime of this JSON document.
@b Example
@code
const char *keys[2] = { "id", "name" };
const char *vals[2] = { "01", "Harry" };
yyjson_mut_val *obj = yyjson_mut_obj_with_str(doc, keys, vals, 2);
@endcode
*/
yyjson_api_inline yyjson_mut_val *yyjson_mut_obj_with_str(yyjson_mut_doc *doc,
const char **keys,
const char **vals,
size_t count);
/**
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.
@warning The input string is not copied, you should keep this string
unmodified for the lifetime of this JSON document.
( run in 0.461 second using v1.01-cache-2.11-cpan-d7a12ab2c7f )