Mercurial > hg > ucx / file comparison

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

docs/Writerside/topics/json.h.md

changeset 1257
946cadf95ea4
parent 1190
a7b913d5d589
child 1258
a12e102ff67f
equal deleted inserted replaced
1256:b9a940779877 1257:946cadf95ea4
2 2
3 <warning> 3 <warning>
4 New Feature - will be documented soon! 4 New Feature - will be documented soon!
5 </warning> 5 </warning>
6 6
7 ## Parser
8
9 ```C
10 #include <cx/json.h>
11
12 void cxJsonInit(CxJson *json, const CxAllocator *allocator);
13
14 void cxJsonReset(CxJson *json);
15
16 int cxJsonFilln(CxJson *json, const char *buf, size_t len);
17
18 int cxJsonFill(CxJson *json, AnyStr str);
19
20 CxJsonStatus cxJsonNext(CxJson *json, CxJsonValue **value);
21
22 void cxJsonDestroy(CxJson *json);
23 ```
24
25 <warning>
26 TODO: document
27 </warning>
28
29 ### List of Status Codes
30
7 <!-- 31 <!--
8 ## Undocumented Symbols (TODO) 32 /**
9 ### cxJsonArrAddCxStrings 33 * Everything is fine.
10 ### cxJsonArrAddIntegers 34 */
11 ### cxJsonArrAddLiterals 35 CX_JSON_NO_ERROR,
12 ### cxJsonArrAddNumbers 36 /**
13 ### cxJsonArrAddStrings 37 * The input buffer does not contain more data.
14 ### cxJsonArrAddValues 38 */
15 ### cxJsonArrGet 39 CX_JSON_NO_DATA,
16 ### cxJsonArrIter 40 /**
17 ### cxJsonCreateArr 41 * The input ends unexpectedly.
18 ### cxJsonCreateCxString 42 *
19 ### cxJsonCreateInteger 43 * Refill the buffer with cxJsonFill() to complete the json data.
20 ### cxJsonCreateLiteral 44 */
21 ### cxJsonCreateNumber 45 CX_JSON_INCOMPLETE_DATA,
22 ### cxJsonCreateObj 46 /**
23 ### cxJsonCreateString 47 * Not used as a status and never returned by any function.
24 ### cxJsonDestroy 48 *
25 ### cxJsonFilln 49 * You can use this enumerator to check for all "good" status results
26 ### cxJsonInit 50 * by checking if the status is less than @c CX_JSON_OK.
27 ### cxJsonNext 51 *
28 ### cx_json_obj_get_cxstr 52 * A "good" status means, that you can refill data and continue parsing.
29 ### cxJsonObjIter 53 */
30 ### cxJsonObjPut 54 CX_JSON_OK,
31 ### cxJsonObjPutArr 55 /**
32 ### cxJsonObjPutCxString 56 * The input buffer has never been filled.
33 ### cxJsonObjPutInteger 57 */
34 ### cxJsonObjPutLiteral 58 CX_JSON_NULL_DATA,
35 ### cxJsonObjPutNumber 59 /**
36 ### cxJsonObjPutObj 60 * Allocating memory for the internal buffer failed.
37 ### cxJsonObjPutString 61 */
38 ### cxJsonValueFree 62 CX_JSON_BUFFER_ALLOC_FAILED,
39 ### cxJsonWrite 63 /**
40 ### cxJsonWriterCompact 64 * Allocating memory for a json value failed.
41 ### cx_json_write_rec 65 */
42 ### cxJsonWriterPretty 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
43 --> 75 -->
76
77 ## Access Values
78
79 ```C
80 #include <cx/json.h>
81
82 bool cxJsonIsObject(const CxJsonValue *value);
83
84 bool cxJsonIsArray(const CxJsonValue *value);
85
86 bool cxJsonIsString(const CxJsonValue *value);
87
88 bool cxJsonIsNumber(const CxJsonValue *value);
89
90 bool cxJsonIsInteger(const CxJsonValue *value);
91
92 bool cxJsonIsLiteral(const CxJsonValue *value);
93
94 bool cxJsonIsBool(const CxJsonValue *value);
95
96 bool cxJsonIsTrue(const CxJsonValue *value);
97
98 bool cxJsonIsFalse(const CxJsonValue *value);
99
100 bool cxJsonIsNull(const CxJsonValue *value);
101
102 char *cxJsonAsString(const CxJsonValue *value);
103
104 cxstring cxJsonAsCxString(const CxJsonValue *value);
105
106 cxmutstr cxJsonAsCxMutStr(const CxJsonValue *value);
107
108 double cxJsonAsDouble(const CxJsonValue *value);
109
110 int64_t cxJsonAsInteger(const CxJsonValue *value);
111
112 bool cxJsonAsBool(const CxJsonValue *value);
113
114 size_t cxJsonArrSize(const CxJsonValue *value);
115
116 CxJsonValue *cxJsonArrGet(const CxJsonValue *value, size_t index);
117
118 CxJsonValue *cxJsonObjGet(const CxJsonValue *value, AnyStr name);
119
120 CxIterator cxJsonArrIter(const CxJsonValue *value);
121
122 CxIterator cxJsonObjIter(const CxJsonValue *value);
123 ```
124
125 <warning>
126 TODO: document
127 </warning>
128
129 ## Deallocate Memory
130
131 ```C
132 #include <cx/json.h>
133
134 void cxJsonValueFree(CxJsonValue *value);
135 ```
136
137 Once a JSON value is not needed anymore, the memory can be deallocated with `cxJsonValueFree()`.
138 Nested values are also recursively deallocated.
139
140 > Make sure that you are not accidentally deallocating values that are still part of an object or array.
141 > When deallocating the enclosing object/array, this will lead to a double-free.
142 >{style="warning"}
143
144 ## Create Objects
145
146 ```C
147 #include <cx/json.h>
148
149 CxJsonValue* cxJsonCreateObj(const CxAllocator* allocator);
150
151 CxJsonValue* cxJsonCreateArr(const CxAllocator* allocator);
152
153 CxJsonValue* cxJsonCreateNumber(
154 const CxAllocator* allocator, double num);
155
156 CxJsonValue* cxJsonCreateInteger(
157 const CxAllocator* allocator, int64_t num);
158
159 CxJsonValue* cxJsonCreateString(const CxAllocator* allocator,
160 const char *str);
161
162 CxJsonValue* cxJsonCreateCxString(
163 const CxAllocator* allocator, cxstring str);
164
165 CxJsonValue* cxJsonCreateLiteral(
166 const CxAllocator* allocator, CxJsonLiteral lit);
167
168 int cxJsonArrAddNumbers(CxJsonValue* arr,
169 const double* num, size_t count);
170
171 int cxJsonArrAddIntegers(CxJsonValue* arr,
172 const int64_t* num, size_t count);
173
174 int cxJsonArrAddStrings(CxJsonValue* arr,
175 const char* const* str, size_t count);
176
177 int cxJsonArrAddCxStrings(CxJsonValue* arr,
178 const cxstring* str, size_t count);
179
180 int cxJsonArrAddLiterals(CxJsonValue* arr,
181 const CxJsonLiteral* lit, size_t count);
182
183 int cxJsonArrAddValues(CxJsonValue* arr,
184 CxJsonValue* const* val, size_t count);
185
186 int cxJsonObjPut(CxJsonValue* obj, cxstring name, CxJsonValue* child);
187
188 CxJsonValue* cxJsonObjPutObj(CxJsonValue* obj, cxstring name);
189
190 CxJsonValue* cxJsonObjPutArr(CxJsonValue* obj, cxstring name);
191
192 CxJsonValue* cxJsonObjPutNumber(CxJsonValue* obj,
193 cxstring name, double num);
194
195 CxJsonValue* cxJsonObjPutInteger(CxJsonValue* obj,
196 cxstring name, int64_t num);
197
198 CxJsonValue* cxJsonObjPutString(CxJsonValue* obj,
199 cxstring name, const char* str);
200
201 CxJsonValue* cxJsonObjPutCxString(CxJsonValue* obj,
202 cxstring name, cxstring str);
203
204 CxJsonValue* cxJsonObjPutLiteral(CxJsonValue* obj,
205 cxstring name, CxJsonLiteral lit);
206 ```
207
208 <warning>
209 TODO: document
210 </warning>
211
212 ## Writer
213
214 ```C
215 #include <cx/json.h>
216
217 typedef struct cx_json_writer_s {
218 bool pretty;
219 bool sort_members;
220 uint8_t frac_max_digits;
221 bool indent_space;
222 uint8_t indent;
223 bool escape_slash;
224 } CxJsonWriter;
225
226 CxJsonWriter cxJsonWriterCompact(void);
227
228 CxJsonWriter cxJsonWriterPretty(bool use_spaces);
229
230 int cxJsonWrite(void* target, const CxJsonValue* value,
231 cx_write_func wfunc, const CxJsonWriter* settings);
232 ```
233
234 <warning>
235 TODO: document
236 </warning>
237
44 <seealso> 238 <seealso>
45 <category ref="apidoc"> 239 <category ref="apidoc">
46 <a href="https://ucx.sourceforge.io/api/json_8h.html">json.h</a> 240 <a href="https://ucx.sourceforge.io/api/json_8h.html">json.h</a>
47 </category> 241 </category>
48 </seealso> 242 </seealso>

Mercurial Repository: ucx

mercurial