# `./fio-stl/004 json.h`

5 public symbols.

### Macros

#### `FIO_JSON_MAX_DEPTH`

```c
#define FIO_JSON_MAX_DEPTH 128
```

Maximum allowed JSON nesting level. MUST be less then 65536

Values above 65536 might cause the stack to overflow and cause a failure.

_Symbol type:_ `macro`

#### `FIO_JSON_USE_FIO_ATON`

```c
#define FIO_JSON_USE_FIO_ATON 0
```



_Symbol type:_ `macro`

### Types

#### `fio_json_parser_callbacks_s`

```c
typedef struct {
/** NULL object was detected. Returns new object as `void *`. */
void *(*on_null)(void *udata);
/** TRUE object was detected. Returns new object as `void *`. */
void *(*on_true)(void *udata);
/** FALSE object was detected. Returns new object as `void *`. */
void *(*on_false)(void *udata);
/** Number was detected (long long). Returns new object as `void *`. */
void *(*on_number)(void *udata, int64_t i);
/** Float was detected (double).Returns new object as `void *`. */
void *(*on_float)(void *udata, double f);
/** (escaped) String was detected. Returns a new String as `void *`. */
void *(*on_string)(void *udata, const void *start, size_t len);
/** (unescaped) String was detected. Returns a new String as `void *`. */
void *(*on_string_simple)(void *udata, const void *start, size_t len);
/** Dictionary was detected. Returns ctx to hash map or NULL on error. */
void *(*on_map)(void *udata, void *ctx, void *at);
/** Array was detected. Returns ctx to array or NULL on error. */
void *(*on_array)(void *udata, void *ctx, void *at);
/** Map entry detected. Returns non-zero on error. Owns key and value. */
int (*map_push)(void *udata, void *ctx, void *key, void *value);
/** Array entry detected. Returns non-zero on error. Owns value. */
int (*array_push)(void *udata, void *ctx, void *value);
/** Called when an array object (`ctx`) appears done. */
int (*array_finished)(void *udata, void *ctx);
/** Called when a map object (`ctx`) appears done. */
int (*map_finished)(void *udata, void *ctx);
/** Called when context is expected to be an array (i.e., fio_json_update). */
int (*is_array)(void *udata, void *ctx);
/** Called when context is expected to be a map (i.e., fio_json_update). */
int (*is_map)(void *udata, void *ctx);
/** Called for unused objects (e.g., key on error). Must free the object. */
void (*free_unused_object)(void *udata, void *ctx);
/** The JSON parsing encountered an error. Owns ctx, should free or return. */
void *(*on_error)(void *udata, void *ctx);
} fio_json_parser_callbacks_s
```

The JSON parser settings (callbacks).

**Ownership**: Callbacks that return `void *` objects transfer ownership to
the parser. The parser will either pass these objects to `map_push` /
`array_push` (transferring ownership to the container), or call
`free_unused_object` if the object is not used (e.g., on error or NULL map
key). The `on_error` callback receives ownership of any partial result.

_Symbol type:_ `type`

#### `fio_json_result_s`

```c
typedef struct {
void *ctx;
size_t stop_pos;
int err;
} fio_json_result_s
```

The JSON return type.

_Symbol type:_ `type`

### Functions

#### `fio_json_parse`

```c
fio_json_result_s fio_json_parse(fio_json_parser_callbacks_s *settings, void *udata, const char *json_string, const size_t len)
```

The facil.io JSON parser is a non-strict parser, with support for trailing
commas in collections, new-lines in strings, extended escape characters and
octal, hex and binary numbers.

The parser allows for streaming data and decouples the parsing process from
the resulting data-structure by calling static callbacks for JSON related
events.

Returns the number of bytes consumed before parsing stopped (due to either
error or end of data). Stops as close as possible to the end of the buffer or
once an object parsing was completed.

Buffer requirement (guard-byte contract): number / quote-less key scanning
may read the byte at `json_string[len]` while deciding a token ended. The
buffer MUST remain readable through a non-numeric guard byte - pass a
NUL-terminated string (`fio_bstr` qualifies) or append a guard byte.

_Symbol type:_ `function`

-----------------------------------------------------