comparison: docs/Writerside/topics/json.h.md
docs/Writerside/topics/json.h.md
- changeset 1694
- a2757c6427cc
- parent 1607
- 0ecb13118cac
equal
deleted
inserted
replaced
| 1693:c2d05cf1a062 | 1694:a2757c6427cc |
|---|---|
| 1 # JSON | 1 # JSON |
| 2 | 2 |
| 3 The UCX JSON API allows [parsing](#parser) and [formatting](#writer) of JSON data. | 3 The UCX JSON API allows [parsing](#parser) and [formatting](#writer) of JSON data. |
| 4 | 4 |
| 5 The parser API is similar to the [properties](properties.h.md) parser, | 5 The parser API is similar to the [properties](properties.h.md) parser, |
| 6 but - due to the nature of JSON - is not allocation-free. | 6 but - due to the nature of JSON - it is not allocation-free. |
| 7 | 7 |
| 8 ## Parser | 8 ## Parser |
| 9 | 9 |
| 10 The following listing shows the JSON parser API. | 10 The following listing shows the JSON parser API. |
| 11 | 11 |
| 39 Specifying `NULL` as `allocator` is allowed, in which case the `cxDefaultAllocator` will be used. | 39 Specifying `NULL` as `allocator` is allowed, in which case the `cxDefaultAllocator` will be used. |
| 40 | 40 |
| 41 The actual parsing is an interleaving invocation of the `cxJsonFill()` (or `cxJsonFilln()`) and `cxJsonNext()` functions. | 41 The actual parsing is an interleaving invocation of the `cxJsonFill()` (or `cxJsonFilln()`) and `cxJsonNext()` functions. |
| 42 The `cxJsonFill()` function is a convenience function that accepts UCX strings and normal zero-terminated C strings. | 42 The `cxJsonFill()` function is a convenience function that accepts UCX strings and normal zero-terminated C strings. |
| 43 | 43 |
| 44 Calling `cxJsonNext()` will return with `CX_JSON_NO_ERROR` (= zero) for each JSON value that is successfully parsed, | 44 Calling `cxJsonNext()` will return with `CX_JSON_NO_ERROR` (= zero) for each JSON value that is successfully parsed |
| 45 and stores the pointer to the allocated value in the variable pointed to by `value`. | 45 and stores the pointer to the allocated value in the variable pointed to by `value`. |
| 46 | 46 |
| 47 > The parser is capable of parsing multiple consecutive JSON values. | 47 > The parser is capable of parsing multiple consecutive JSON values. |
| 48 > If those values are not objects or arrays, they must, however, be separated by any whitespace character. | 48 > If those values are not objects or arrays, they must, however, be separated by any whitespace character. |
| 49 | 49 |
| 50 When all the data from the input buffer was successfully consumed, `cxJsonNext()` returns `CX_JSON_NO_DATA`. | 50 When all the data from the input buffer was successfully consumed, `cxJsonNext()` returns `CX_JSON_NO_DATA`. |
| 51 | 51 |
| 52 If `cxJsonNext()` returns `CX_JSON_INCOMPLETE_DATA` it means that the input buffer is exhausted, | 52 If `cxJsonNext()` returns `CX_JSON_INCOMPLETE_DATA`, the input buffer is exhausted, |
| 53 but the parsed input does not constitute a complete JSON value. | 53 but the parsed input does not constitute a complete JSON value. |
| 54 In that case, you can call `cxJsonFill()` again to add more data and continue with `cxJsonNext()`. | 54 In that case, you can call `cxJsonFill()` again to add more data and continue with `cxJsonNext()`. |
| 55 | 55 |
| 56 A complete list of all status codes can be seen [below](#list-of-status-codes). | 56 A complete list of all status codes can be seen [below](#list-of-status-codes). |
| 57 | 57 |
| 142 > | 142 > |
| 143 > Additionally, UCX does implement the JavaScript concept of a "falsy" value, meaning that | 143 > Additionally, UCX does implement the JavaScript concept of a "falsy" value, meaning that |
| 144 > `cxJsonIsFalse()` _only_ returns true, if the value is a literal `false`. | 144 > `cxJsonIsFalse()` _only_ returns true, if the value is a literal `false`. |
| 145 >{style="note"} | 145 >{style="note"} |
| 146 | 146 |
| 147 The `cxJsonAsXYZ()` family of functions return the value with its corresponding C type. | 147 The `cxJsonAsXYZ()` functions return the value with its corresponding plain type. |
| 148 | 148 |
| 149 The functions `cxJsonAsInteger()` and `cxJsonAsDouble()` can be used for any number value. | 149 The functions `cxJsonAsInteger()` and `cxJsonAsDouble()` can be used for any number value. |
| 150 For example, if `cxJsonAsInteger()` is used on a non-integral number, a double-to-int conversion is performed. | 150 For example, if `cxJsonAsInteger()` is used on a non-integral number, a double-to-int conversion is performed. |
| 151 | 151 |
| 152 The function `cxJsonArraySize()` returns the number of items in an array value, | 152 The function `cxJsonArraySize()` returns the number of items in an array value, |
