File-Raw-JSON
view release on metacpan or search on metacpan
include/yyjson.h view on Meta::CPAN
@warning This Allocator is not thread-safe.
*/
yyjson_api yyjson_alc *yyjson_alc_dyn_new(void);
/**
Free a dynamic allocator which is created by `yyjson_alc_dyn_new()`.
@param alc The dynamic allocator to be destroyed.
*/
yyjson_api void yyjson_alc_dyn_free(yyjson_alc *alc);
/*==============================================================================
* JSON Structure
*============================================================================*/
/**
An immutable document for reading JSON.
This document holds memory for all its JSON values and strings. When it is no
longer used, the user should call `yyjson_doc_free()` to free its memory.
*/
typedef struct yyjson_doc yyjson_doc;
/**
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;
/*==============================================================================
* 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 multiple 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;
/** 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 failure occurs. */
static const yyjson_read_code YYJSON_READ_ERROR_MEMORY_ALLOCATION = 2;
include/yyjson.h view on Meta::CPAN
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, such as unclosed multi-line 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;
/** Error information for JSON reader. */
typedef struct yyjson_read_err {
/** Error code, see `yyjson_read_code` for all possible values. */
yyjson_read_code code;
/** Error message, constant, no need to free (NULL if success). */
const char *msg;
/** Error byte position for input data (0 if success). */
size_t pos;
} yyjson_read_err;
/**
Locate the line and column number for a byte position in a string.
This can be used to get better description for error position.
@param str The input string.
@param len The byte length of the input string.
@param pos The byte position within the input string.
@param line A pointer to receive the line number, starting from 1.
@param col A pointer to receive the column number, starting from 1.
@param chr A pointer to receive the character index, starting from 0.
@return true on success, false if `str` is NULL or `pos` is out of bounds.
@note Line/column/character are calculated based on Unicode characters for
compatibility with text editors. For multi-byte UTF-8 characters,
the returned value may not directly correspond to the byte position.
*/
yyjson_api bool yyjson_locate_pos(const char *str, size_t len, size_t pos,
size_t *line, size_t *col, size_t *chr);
/**
Read JSON with options.
This function is thread-safe when:
1. The `dat` is not modified by other threads.
2. The `alc` is thread-safe or NULL.
@param dat The JSON data (UTF-8 without BOM), null-terminator is not required.
If this parameter is NULL, the function will fail and return NULL.
The `dat` will not be modified without the flag `YYJSON_READ_INSITU`, so you
can pass a `const char *` string and case it to `char *` if you don't use
the `YYJSON_READ_INSITU` flag.
@param len The length of JSON data in bytes.
If this parameter is 0, the function will fail and return NULL.
@param flg The JSON read options.
Multiple options can be combined with `|` operator. 0 means no options.
@param alc The memory allocator used by JSON reader.
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 A new JSON document, or NULL if an error occurs.
When it's no longer needed, it should be freed with `yyjson_doc_free()`.
*/
yyjson_api yyjson_doc *yyjson_read_opts(char *dat,
size_t len,
yyjson_read_flag flg,
const yyjson_alc *alc,
yyjson_read_err *err);
/**
Read a JSON file.
This function is thread-safe when:
1. The file is not modified by other threads.
2. The `alc` is thread-safe or NULL.
@param path The JSON file's path.
If this path is NULL or invalid, the function will fail and return NULL.
@param flg The JSON read options.
Multiple options can be combined with `|` operator. 0 means no options.
@param alc The memory allocator used by JSON reader.
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 A new JSON document, or NULL if an error occurs.
When it's no longer needed, it should be freed with `yyjson_doc_free()`.
@warning On 32-bit operating system, files larger than 2GB may fail to read.
*/
yyjson_api yyjson_doc *yyjson_read_file(const char *path,
yyjson_read_flag flg,
const yyjson_alc *alc,
yyjson_read_err *err);
/**
Read JSON from a file pointer.
@param fp The file pointer.
The data will be read from the current position of the FILE to the end.
If this fp is NULL or invalid, the function will fail and return NULL.
@param flg The JSON read options.
Multiple options can be combined with `|` operator. 0 means no options.
@param alc The memory allocator used by JSON reader.
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 A new JSON document, or NULL if an error occurs.
When it's no longer needed, it should be freed with `yyjson_doc_free()`.
@warning On 32-bit operating system, files larger than 2GB may fail to read.
*/
yyjson_api yyjson_doc *yyjson_read_fp(FILE *fp,
yyjson_read_flag flg,
const yyjson_alc *alc,
yyjson_read_err *err);
/**
Read a JSON string.
This function is thread-safe.
@param dat The JSON data (UTF-8 without BOM), null-terminator is not required.
If this parameter is NULL, the function will fail and return NULL.
@param len The length of JSON data in bytes.
If this parameter is 0, the function will fail and return NULL.
@param flg The JSON read options.
Multiple options can be combined with `|` operator. 0 means no options.
@return A new JSON document, or NULL if an error occurs.
When it's no longer needed, it should be freed with `yyjson_doc_free()`.
*/
yyjson_api_inline yyjson_doc *yyjson_read(const char *dat,
size_t len,
yyjson_read_flag flg) {
flg &= ~YYJSON_READ_INSITU; /* const string cannot be modified */
return yyjson_read_opts((char *)(void *)(size_t)(const void *)dat,
len, flg, NULL, NULL);
}
/**
Returns the size of maximum memory usage to read a JSON data.
You may use this value to avoid malloc() or calloc() call inside the reader
to get better performance, or read multiple JSON with one piece of memory.
@param len The length of JSON data in bytes.
@param flg The JSON read options.
@return The maximum memory size to read this JSON, or 0 if overflow.
@par Example
@code
// read multiple JSON with same pre-allocated memory
char *dat1, *dat2, *dat3; // JSON data
size_t len1, len2, len3; // JSON length
size_t max_len = MAX(len1, MAX(len2, len3));
yyjson_doc *doc;
// use one allocator for multiple JSON
size_t size = yyjson_read_max_memory_usage(max_len, 0);
void *buf = malloc(size);
yyjson_alc alc;
yyjson_alc_pool_init(&alc, buf, size);
// no more alloc() or realloc() call during reading
doc = yyjson_read_opts(dat1, len1, 0, &alc, NULL);
yyjson_doc_free(doc);
doc = yyjson_read_opts(dat2, len2, 0, &alc, NULL);
yyjson_doc_free(doc);
doc = yyjson_read_opts(dat3, len3, 0, &alc, NULL);
yyjson_doc_free(doc);
free(buf);
@endcode
@see yyjson_alc_pool_init()
*/
yyjson_api_inline size_t yyjson_read_max_memory_usage(size_t len,
yyjson_read_flag flg) {
/*
1. The max value count is (json_size / 2 + 1),
for example: "[1,2,3,4]" size is 9, value count is 5.
2. Some broken JSON may cost more memory during reading, but fail at end,
for example: "[[[[[[[[".
3. yyjson use 16 bytes per value, see struct yyjson_val.
4. yyjson use dynamic memory with a growth factor of 1.5.
The max memory size is (json_size / 2 * 16 * 1.5 + padding).
*/
size_t mul = (size_t)12 + !(flg & YYJSON_READ_INSITU);
size_t pad = 256;
size_t max = (size_t)(~(size_t)0);
if (flg & YYJSON_READ_STOP_WHEN_DONE) len = len < 256 ? 256 : len;
if (len >= (max - pad - mul) / mul) return 0;
return len * mul + pad;
}
/**
Read a JSON number.
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);
/**
Read a JSON number.
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_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);
}
/*==============================================================================
* 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;
( run in 1.589 second using v1.01-cache-2.11-cpan-c966e8aa7e8 )