JSON-YY
view release on metacpan or search on metacpan
An immutable value for reading JSON.
A JSON Value has the same lifetime as its document. The memory is held by its
document and and cannot be freed alone.
*/
typedef struct yyjson_val yyjson_val;
/**
A mutable document for building JSON.
This document holds memory for all its JSON values and strings. When it is no
longer used, the user should call `yyjson_mut_doc_free()` to free its memory.
*/
typedef struct yyjson_mut_doc yyjson_mut_doc;
/**
A mutable value for building JSON.
A JSON Value has the same lifetime as its document. The memory is held by its
document and and cannot be freed alone.
*/
typedef struct yyjson_mut_val yyjson_mut_val;
/*==============================================================================
* MARK: - JSON Reader API
*============================================================================*/
/** Run-time options for JSON reader. */
typedef uint32_t yyjson_read_flag;
/** Default option (RFC 8259 compliant):
- Read positive integer as uint64_t.
- Read negative integer as int64_t.
- Read floating-point number as double with round-to-nearest mode.
- Read integer which cannot fit in uint64_t or int64_t as double.
- Report error if double number is infinity.
- Report error if string contains invalid UTF-8 character or BOM.
- Report error on trailing commas, comments, inf and nan literals. */
static const yyjson_read_flag YYJSON_READ_NOFLAG = 0;
/** 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. */
static const yyjson_read_flag YYJSON_READ_INSITU = 1 << 0;
/** 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`. */
static const yyjson_read_flag YYJSON_READ_STOP_WHEN_DONE = 1 << 1;
/** Allow single trailing comma at the end of an object or array,
such as `[1,2,3,]`, `{"a":1,"b":2,}` (non-standard). */
static const yyjson_read_flag YYJSON_READ_ALLOW_TRAILING_COMMAS = 1 << 2;
/** Allow C-style single-line and mult-line comments (non-standard). */
static const yyjson_read_flag YYJSON_READ_ALLOW_COMMENTS = 1 << 3;
/** Allow inf/nan number and literal, case-insensitive,
such as 1e999, NaN, inf, -Infinity (non-standard). */
static const yyjson_read_flag YYJSON_READ_ALLOW_INF_AND_NAN = 1 << 4;
/** Read all numbers as raw strings (value with `YYJSON_TYPE_RAW` type),
inf/nan literal is also read as raw with `ALLOW_INF_AND_NAN` flag. */
static const yyjson_read_flag YYJSON_READ_NUMBER_AS_RAW = 1 << 5;
/** 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.
@warning Strings in JSON values may contain incorrect encoding when this
option is used, you need to handle these strings carefully to avoid security
risks. */
static const yyjson_read_flag YYJSON_READ_ALLOW_INVALID_UNICODE = 1 << 6;
/** 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. */
static const yyjson_read_flag YYJSON_READ_BIGNUM_AS_RAW = 1 << 7;
/** Allow UTF-8 BOM and skip it before parsing if any (non-standard). */
static const yyjson_read_flag YYJSON_READ_ALLOW_BOM = 1 << 8;
/** Allow extended number formats (non-standard):
- Hexadecimal numbers, such as `0x7B`.
- Numbers with leading or trailing decimal point, such as `.123`, `123.`.
- Numbers with a leading plus sign, such as `+123`. */
static const yyjson_read_flag YYJSON_READ_ALLOW_EXT_NUMBER = 1 << 9;
/** Allow extended escape sequences in strings (non-standard):
- Additional escapes: `\a`, `\e`, `\v`, ``\'``, `\?`, `\0`.
- Hex escapes: `\xNN`, such as `\x7B`.
- Line continuation: backslash followed by line terminator sequences.
- Unknown escape: if backslash is followed by an unsupported character,
the backslash will be removed and the character will be kept as-is.
However, `\1`-`\9` will still trigger an error. */
static const yyjson_read_flag YYJSON_READ_ALLOW_EXT_ESCAPE = 1 << 10;
/** Allow extended whitespace characters (non-standard):
- Vertical tab `\v` and form feed `\f`.
- Line separator `\u2028` and paragraph separator `\u2029`.
- Non-breaking space `\xA0`.
- Byte order mark: `\uFEFF`.
- Other Unicode characters in the Zs (Separator, space) category. */
static const yyjson_read_flag YYJSON_READ_ALLOW_EXT_WHITESPACE = 1 << 11;
/** Allow strings enclosed in single quotes (non-standard), such as ``'ab'``. */
static const yyjson_read_flag YYJSON_READ_ALLOW_SINGLE_QUOTED_STR = 1 << 12;
/** Allow object keys without quotes (non-standard), such as `{a:1,b:2}`.
This extends the ECMAScript IdentifierName rule by allowing any
non-whitespace character with code point above `U+007F`. */
static const yyjson_read_flag YYJSON_READ_ALLOW_UNQUOTED_KEY = 1 << 13;
/** Allow JSON5 format, see: [https://json5.org].
This flag supports all JSON5 features with some additional extensions:
- Accepts more escape sequences than JSON5 (e.g. `\a`, `\e`).
- Unquoted keys are not limited to ECMAScript IdentifierName.
- Allow case-insensitive `NaN`, `Inf` and `Infinity` literals. */
static const yyjson_read_flag YYJSON_READ_JSON5 =
(1 << 2) | /* YYJSON_READ_ALLOW_TRAILING_COMMAS */
(1 << 3) | /* YYJSON_READ_ALLOW_COMMENTS */
(1 << 4) | /* YYJSON_READ_ALLOW_INF_AND_NAN */
(1 << 9) | /* YYJSON_READ_ALLOW_EXT_NUMBER */
(1 << 10) | /* YYJSON_READ_ALLOW_EXT_ESCAPE */
(1 << 11) | /* YYJSON_READ_ALLOW_EXT_WHITESPACE */
(1 << 12) | /* YYJSON_READ_ALLOW_SINGLE_QUOTED_STR */
(1 << 13); /* YYJSON_READ_ALLOW_UNQUOTED_KEY */
/** Result code for JSON reader. */
typedef uint32_t yyjson_read_code;
/** Success, no error. */
static const yyjson_read_code YYJSON_READ_SUCCESS = 0;
/** Invalid parameter, such as NULL input string or 0 input length. */
static const yyjson_read_code YYJSON_READ_ERROR_INVALID_PARAMETER = 1;
/** Memory allocation failed. */
static const yyjson_read_code YYJSON_READ_ERROR_MEMORY_ALLOCATION = 2;
/** Input JSON string is empty. */
static const yyjson_read_code YYJSON_READ_ERROR_EMPTY_CONTENT = 3;
/** Unexpected content after document, such as `[123]abc`. */
static const yyjson_read_code YYJSON_READ_ERROR_UNEXPECTED_CONTENT = 4;
/** Unexpected end of input, the parsed part is valid, such as `[123`. */
static const yyjson_read_code YYJSON_READ_ERROR_UNEXPECTED_END = 5;
/** Unexpected character inside the document, such as `[abc]`. */
static const yyjson_read_code YYJSON_READ_ERROR_UNEXPECTED_CHARACTER = 6;
/** Invalid JSON structure, such as `[1,]`. */
static const yyjson_read_code YYJSON_READ_ERROR_JSON_STRUCTURE = 7;
/** Invalid comment, deprecated, use `UNEXPECTED_END` for unclosed comment. */
static const yyjson_read_code YYJSON_READ_ERROR_INVALID_COMMENT = 8;
/** Invalid number, such as `123.e12`, `000`. */
static const yyjson_read_code YYJSON_READ_ERROR_INVALID_NUMBER = 9;
/** Invalid string, such as invalid escaped character inside a string. */
static const yyjson_read_code YYJSON_READ_ERROR_INVALID_STRING = 10;
/** Invalid JSON literal, such as `truu`. */
static const yyjson_read_code YYJSON_READ_ERROR_LITERAL = 11;
/** Failed to open a file. */
static const yyjson_read_code YYJSON_READ_ERROR_FILE_OPEN = 12;
/** Failed to read a file. */
static const yyjson_read_code YYJSON_READ_ERROR_FILE_READ = 13;
/** Incomplete input during incremental parsing; parsing state is preserved. */
static const yyjson_read_code YYJSON_READ_ERROR_MORE = 14;
This function is thread-safe when data is not modified by other threads.
@param dat The JSON data (UTF-8 without BOM), null-terminator is required.
If this parameter is NULL, the function will fail and return NULL.
@param val The output value where result is stored.
If this parameter is NULL, the function will fail and return NULL.
The value will hold either UINT or SINT or REAL number;
@param flg The JSON read options.
Multiple options can be combined with `|` operator. 0 means no options.
Supports `YYJSON_READ_NUMBER_AS_RAW` and `YYJSON_READ_ALLOW_INF_AND_NAN`.
@param alc The memory allocator used for long number.
It is only used when the built-in floating point reader is disabled.
Pass NULL to use the libc's default allocator.
@param err A pointer to receive error information.
Pass NULL if you don't need error information.
@return If successful, a pointer to the character after the last character
used in the conversion, NULL if an error occurs.
*/
yyjson_api const char *yyjson_read_number(const char *dat,
yyjson_val *val,
yyjson_read_flag flg,
const yyjson_alc *alc,
yyjson_read_err *err);
/** Same as `yyjson_read_number()`. */
yyjson_api_inline const char *yyjson_mut_read_number(const char *dat,
yyjson_mut_val *val,
yyjson_read_flag flg,
const yyjson_alc *alc,
yyjson_read_err *err) {
return yyjson_read_number(dat, (yyjson_val *)val, flg, alc, err);
}
#endif /* YYJSON_DISABLE_READER) */
/*==============================================================================
* MARK: - JSON Writer API
*============================================================================*/
/** Run-time options for JSON writer. */
typedef uint32_t yyjson_write_flag;
/** Default option:
- Write JSON minify.
- Report error on inf or nan number.
- Report error on invalid UTF-8 string.
- Do not escape unicode or slash. */
static const yyjson_write_flag YYJSON_WRITE_NOFLAG = 0;
/** Write JSON pretty with 4 space indent. */
static const yyjson_write_flag YYJSON_WRITE_PRETTY = 1 << 0;
/** Escape unicode as `uXXXX`, make the output ASCII only. */
static const yyjson_write_flag YYJSON_WRITE_ESCAPE_UNICODE = 1 << 1;
/** Escape '/' as '\/'. */
static const yyjson_write_flag YYJSON_WRITE_ESCAPE_SLASHES = 1 << 2;
/** Write inf and nan number as 'Infinity' and 'NaN' literal (non-standard). */
static const yyjson_write_flag YYJSON_WRITE_ALLOW_INF_AND_NAN = 1 << 3;
/** Write inf and nan number as null literal.
This flag will override `YYJSON_WRITE_ALLOW_INF_AND_NAN` flag. */
static const yyjson_write_flag YYJSON_WRITE_INF_AND_NAN_AS_NULL = 1 << 4;
/** 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. */
static const yyjson_write_flag YYJSON_WRITE_ALLOW_INVALID_UNICODE = 1 << 5;
/** Write JSON pretty with 2 space indent.
This flag will override `YYJSON_WRITE_PRETTY` flag. */
static const yyjson_write_flag YYJSON_WRITE_PRETTY_TWO_SPACES = 1 << 6;
/** Adds a newline character `\n` at the end of the JSON.
This can be helpful for text editors or NDJSON. */
static const yyjson_write_flag YYJSON_WRITE_NEWLINE_AT_END = 1 << 7;
/** The highest 8 bits of `yyjson_write_flag` and real number value's `tag`
are reserved for controlling the output format of floating-point numbers. */
#define YYJSON_WRITE_FP_FLAG_BITS 8
/** The highest 4 bits of flag are reserved for precision value. */
#define YYJSON_WRITE_FP_PREC_BITS 4
/** Write floating-point number using fixed-point notation.
- This is similar to ECMAScript `Number.prototype.toFixed(prec)`,
but with trailing zeros removed. The `prec` ranges from 1 to 15.
- This will produce shorter output but may lose some precision. */
#define YYJSON_WRITE_FP_TO_FIXED(prec) ((yyjson_write_flag)( \
(uint32_t)((uint32_t)(prec)) << (32 - 4) ))
/** Write floating-point numbers using single-precision (float).
- This casts `double` to `float` before serialization.
- This will produce shorter output, but may lose some precision.
- This flag is ignored if `YYJSON_WRITE_FP_TO_FIXED(prec)` is also used. */
#define YYJSON_WRITE_FP_TO_FLOAT ((yyjson_write_flag)(1 << (32 - 5)))
/** Result code for JSON writer */
typedef uint32_t yyjson_write_code;
/** Success, no error. */
static const yyjson_write_code YYJSON_WRITE_SUCCESS = 0;
/** Invalid parameter, such as NULL document. */
static const yyjson_write_code YYJSON_WRITE_ERROR_INVALID_PARAMETER = 1;
/** Memory allocation failure occurs. */
static const yyjson_write_code YYJSON_WRITE_ERROR_MEMORY_ALLOCATION = 2;
/** Invalid value type in JSON document. */
static const yyjson_write_code YYJSON_WRITE_ERROR_INVALID_VALUE_TYPE = 3;
/** NaN or Infinity number occurs. */
static const yyjson_write_code YYJSON_WRITE_ERROR_NAN_OR_INF = 4;
/** Failed to open a file. */
static const yyjson_write_code YYJSON_WRITE_ERROR_FILE_OPEN = 5;
/** Failed to write a file. */
static const yyjson_write_code YYJSON_WRITE_ERROR_FILE_WRITE = 6;
/** Invalid unicode in string. */
static const yyjson_write_code YYJSON_WRITE_ERROR_INVALID_STRING = 7;
/** Error information for JSON writer. */
typedef struct yyjson_write_err {
/** Error code, see `yyjson_write_code` for all possible values. */
yyjson_write_code code;
/** Error message, constant, no need to free (NULL if success). */
const char *msg;
} yyjson_write_err;
#if !defined(YYJSON_DISABLE_WRITER) || !YYJSON_DISABLE_WRITER
/*==============================================================================
* MARK: - JSON Document Writer API
*============================================================================*/
/**
Write a document to JSON string with options.
This function is thread-safe when:
The `alc` is thread-safe or NULL.
@param doc The JSON document.
If this doc is NULL or has no root, the function will fail and return false.
@param flg The JSON write options.
Multiple options can be combined with `|` operator. 0 means no options.
@param alc The memory allocator used by JSON writer.
Pass NULL to use the libc's default allocator.
@param len A pointer to receive output length in bytes (not including the
null-terminator). Pass NULL if you don't need length information.
@param err A pointer to receive error information.
Pass NULL if you don't need error information.
@return A new JSON string, or NULL if an error occurs.
This string is encoded as UTF-8 with a null-terminator.
When it's no longer needed, it should be freed with free() or alc->free().
*/
yyjson_api char *yyjson_write_opts(const yyjson_doc *doc,
yyjson_write_flag flg,
const yyjson_alc *alc,
size_t *len,
yyjson_write_err *err);
/**
Write a document to JSON file with options.
This function is thread-safe when:
1. The file is not accessed by other threads.
2. The `alc` is thread-safe or NULL.
( run in 1.378 second using v1.01-cache-2.11-cpan-39bf76dae61 )