Mercurial > hg > ucx / file comparison

comparison: docs/Writerside/topics/json.h.md

docs/Writerside/topics/json.h.md

changeset 1258
a12e102ff67f
parent 1257
946cadf95ea4
equal deleted inserted replaced
1257:946cadf95ea4 1258:a12e102ff67f
26 TODO: document 26 TODO: document
27 </warning> 27 </warning>
28 28
29 ### List of Status Codes 29 ### List of Status Codes
30 30
31 <!-- 31 Below is a full list of status codes for `cxJsonNext()`.
32 /** 32
33 * Everything is fine. 33 | Status Code | Meaning |
34 */ 34 |---------------------------------------|---------------------------------------------------------------------------------------------------|
35 CX_JSON_NO_ERROR, 35 | CX_JSON_NO_ERROR | A value was successfully parsed. | |
36 /** 36 | CX_JSON_NO_DATA | The input buffer does not contain more data. |
37 * The input buffer does not contain more data. 37 | CX_JSON_INCOMPLETE_DATA | The input ends unexpectedly. Use `cxJsonFill()` to add more data before retrying. |
38 */ 38 | CX_JSON_NULL_DATA | The input buffer was never initialized. Probably you forgot to call `cxJsonFill()` at least once. |
39 CX_JSON_NO_DATA, 39 | CX_JSON_BUFFER_ALLOC_FAILED | More internal buffer was needed, but could not be allocated. |
40 /** 40 | CX_JSON_VALUE_ALLOC_FAILED | Allocating memory for a json value failed. |
41 * The input ends unexpectedly. 41 | CX_JSON_FORMAT_ERROR_NUMBER | A number value is incorrectly formatted. |
42 * 42 | CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN | The tokenizer found something unexpected, i.e. the JSON string contains a syntax error. |
43 * Refill the buffer with cxJsonFill() to complete the json data.
44 */
45 CX_JSON_INCOMPLETE_DATA,
46 /**
47 * Not used as a status and never returned by any function.
48 *
49 * You can use this enumerator to check for all "good" status results
50 * by checking if the status is less than @c CX_JSON_OK.
51 *
52 * A "good" status means, that you can refill data and continue parsing.
53 */
54 CX_JSON_OK,
55 /**
56 * The input buffer has never been filled.
57 */
58 CX_JSON_NULL_DATA,
59 /**
60 * Allocating memory for the internal buffer failed.
61 */
62 CX_JSON_BUFFER_ALLOC_FAILED,
63 /**
64 * Allocating memory for a json value failed.
65 */
66 CX_JSON_VALUE_ALLOC_FAILED,
67 /**
68 * A number value is incorrectly formatted.
69 */
70 CX_JSON_FORMAT_ERROR_NUMBER,
71 /**
72 * The tokenizer found something unexpected.
73 */
74 CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN
75 -->
76 43
77 ## Access Values 44 ## Access Values
78 45
79 ```C 46 ```C
80 #include <cx/json.h> 47 #include <cx/json.h>
120 CxIterator cxJsonArrIter(const CxJsonValue *value); 87 CxIterator cxJsonArrIter(const CxJsonValue *value);
121 88
122 CxIterator cxJsonObjIter(const CxJsonValue *value); 89 CxIterator cxJsonObjIter(const CxJsonValue *value);
123 ``` 90 ```
124 91
125 <warning> 92 The `cxJsonIsXYZ()` family functions check the type of the specified JSON value.
126 TODO: document 93
127 </warning> 94 The JSON specification only defines numbers, therefore `cxJsonIsNumber()` returns true for both floating point and integer numbers.
95 On the other hand, `cxJsonIsInteger()` only returns true for integral numbers.
96
97 The function `cxJsonIsBool()` returns true if `cxJsonIsLiteral()` returns true, but `cxJsonIsNull()` does not.
98
99 > Since a literal can be `true`, `false`, or `null`, note carefully that `!cxJsonIsTrue(v)`
100 > is in general _not_ equivalent to `cxJsonIsFalse(v)`.
101 >
102 > Additionally, UCX does implement the Javascript concept of a "falsy" value, meaning that
103 > `cxJsonIsFalse()` _only_ returns true, if the value is a literal `false`.
104 >{style="note"}
105
106 The `cxJsonAsXYZ()` family of functions return the value with its corresponding C type.
107
108 The functions `cxJsonAsInteger()` and `cxJsonAsDouble()` can be used for any number value.
109 For example, if `cxJsonAsInteger()` is used on a non-integral number, a double-to-int conversion is performed.
110
111 The function `cxJsonArraySize()` returns the number of items in an array value,
112 which can be accessed via index with `cxJsonArrGet()` or via an iterator created with `cxJsonArrIter()`.
113
114 The function `cxJsonObjGet()` returns the member in a JSON object associated with the specified `name`.
115
116 > Both `cxJsonArrGet()` and `cxJsonObjGet()` are safe regarding access to non-existing values.
117 >
118 > When `cxJsonArrGet()` is used with an out-of-bounds index, or `cxJsonObjGet()` is used with a non-existent name,
119 > they return a JSON value, that returns `false` for any `cxJsonIsXYZ()` function.
120
121 > If you don't have full control over the JSON data, you should always check the datatype of a value first, before accessing it.
122 >{style="note"}
128 123
129 ## Deallocate Memory 124 ## Deallocate Memory
130 125
131 ```C 126 ```C
132 #include <cx/json.h> 127 #include <cx/json.h>

Mercurial Repository: ucx

mercurial