diff options
author | Mark Pulford <mark@kyne.com.au> | 2011-12-13 22:35:49 +1030 |
---|---|---|
committer | Mark Pulford <mark@kyne.com.au> | 2011-12-13 22:35:49 +1030 |
commit | 2be899558e59230c9fc866f6e004f6b6a17272a4 (patch) | |
tree | f24a480711fbea9a0e40d60fa1990db07879f161 | |
parent | 5970e0a93f691bdb7134f6cc2598e6d5aca63c1b (diff) | |
download | lua-cjson-2be899558e59230c9fc866f6e004f6b6a17272a4.tar.gz lua-cjson-2be899558e59230c9fc866f6e004f6b6a17272a4.tar.bz2 lua-cjson-2be899558e59230c9fc866f6e004f6b6a17272a4.zip |
Order API functions in manual alphabetically
-rw-r--r-- | manual.txt | 162 |
1 files changed, 81 insertions, 81 deletions
@@ -123,6 +123,40 @@ keep = cjson.encode_keep_buffer([keep]) | |||
123 | ------------ | 123 | ------------ |
124 | 124 | ||
125 | 125 | ||
126 | cjson.decode | ||
127 | ~~~~~~~~~~~~ | ||
128 | |||
129 | [source,lua] | ||
130 | ------------ | ||
131 | value = cjson.decode(json_text) | ||
132 | ------------ | ||
133 | |||
134 | +cjson.decode+ will deserialise any UTF-8 JSON string into a Lua value | ||
135 | or table. It may return any of the types that +cjson.encode+ supports. | ||
136 | |||
137 | UTF-16 and UTF-32 JSON strings are not supported. | ||
138 | |||
139 | +cjson.decode+ requires that any NULL (ASCII 0) and double quote | ||
140 | (ASCII 34) characters are escaped within strings. All escape codes | ||
141 | will be decoded and other characters will be passed transparently. | ||
142 | UTF-8 characters are not validated during decoding and should be | ||
143 | checked elsewhere if required. | ||
144 | |||
145 | JSON +null+ will be converted to a NULL +lightuserdata+ value. This | ||
146 | can be compared with +cjson.null+ for convenience. | ||
147 | |||
148 | By default, _invalid_ numbers (NaN, Infinity, Hexidecimal) will be | ||
149 | decoded. This default can be changed with | ||
150 | +cjson.refuse_invalid_numbers+. | ||
151 | |||
152 | .Example: decoding | ||
153 | [source,lua] | ||
154 | ------------ | ||
155 | data_json = '[ true, { "foo": "bar" } ]' | ||
156 | data_obj = cjson.decode(data_json) | ||
157 | ------------ | ||
158 | |||
159 | |||
126 | cjson.encode | 160 | cjson.encode |
127 | ~~~~~~~~~~~~ | 161 | ~~~~~~~~~~~~ |
128 | 162 | ||
@@ -208,69 +242,40 @@ data_json = cjson.encode(data_obj) | |||
208 | ------------ | 242 | ------------ |
209 | 243 | ||
210 | 244 | ||
211 | cjson.decode | 245 | cjson.encode_max_depth |
212 | ~~~~~~~~~~~~ | 246 | ~~~~~~~~~~~~~~~~~~~~~~ |
213 | 247 | ||
214 | [source,lua] | 248 | [source,lua] |
215 | ------------ | 249 | ------------ |
216 | value = cjson.decode(json_text) | 250 | depth = cjson.encode_max_depth([depth]) |
251 | -- "depth" must be a positive integer (>0). | ||
217 | ------------ | 252 | ------------ |
218 | 253 | ||
219 | +cjson.decode+ will deserialise any UTF-8 JSON string into a Lua value | 254 | By default, Lua CJSON will reject data structure with more than 20 nested |
220 | or table. It may return any of the types that +cjson.encode+ supports. | 255 | tables. |
221 | |||
222 | UTF-16 and UTF-32 JSON strings are not supported. | ||
223 | |||
224 | +cjson.decode+ requires that any NULL (ASCII 0) and double quote | ||
225 | (ASCII 34) characters are escaped within strings. All escape codes | ||
226 | will be decoded and other characters will be passed transparently. | ||
227 | UTF-8 characters are not validated during decoding and should be | ||
228 | checked elsewhere if required. | ||
229 | |||
230 | JSON +null+ will be converted to a NULL +lightuserdata+ value. This | ||
231 | can be compared with +cjson.null+ for convenience. | ||
232 | 256 | ||
233 | By default, _invalid_ numbers (NaN, Infinity, Hexidecimal) will be | 257 | This check prevents a deeply nested or recursive data structure from |
234 | decoded. This default can be changed with | 258 | crashing the application. |
235 | +cjson.refuse_invalid_numbers+. | ||
236 | 259 | ||
237 | .Example: decoding | 260 | .Example |
238 | [source,lua] | 261 | [source,lua] |
239 | ------------ | 262 | a = {}; b = { a }; a[1] = b |
240 | data_json = '[ true, { "foo": "bar" } ]' | ||
241 | data_obj = cjson.decode(data_json) | ||
242 | ------------ | ||
243 | 263 | ||
244 | 264 | ||
245 | cjson.refuse_invalid_numbers | 265 | cjson.encode_number_precision |
246 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 266 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
247 | 267 | ||
248 | [source,lua] | 268 | [source,lua] |
249 | ------------ | 269 | ------------ |
250 | setting = cjson.refuse_invalid_numbers([setting]) | 270 | precision = cjson.encode_number_precision([precision]) |
251 | -- "setting" must be on of: | 271 | -- "precision" must be between 1 and 14 (inclusive) |
252 | -- false, "encode", "decode", "both", true | ||
253 | ------------ | 272 | ------------ |
254 | 273 | ||
255 | Lua CJSON considers numbers which are outside the JSON specification to be | 274 | By default, Lua CJSON will output 14 significant digits when |
256 | _invalid_: | 275 | converting a number to text. |
257 | |||
258 | - Infinity | ||
259 | - NaN | ||
260 | - Hexadecimal numbers | ||
261 | |||
262 | By default Lua CJSON will decode _invalid_ numbers, but will refuse to | ||
263 | encode them. | ||
264 | |||
265 | This setting can be configured separately for encoding and/or | ||
266 | decoding: | ||
267 | 276 | ||
268 | Enabled:: | 277 | Reducing number precision to _3_ can improve performance of number |
269 | an error will be generated if an _invalid_ number is found. | 278 | heavy JSON conversions by up to 50%. |
270 | Disabled (encoding):: | ||
271 | NaN and Infinity can be encoded. | ||
272 | Disabled (decoding):: | ||
273 | All numbers supported by +strtod+(3) will be parsed. | ||
274 | 279 | ||
275 | 280 | ||
276 | [[sparse_arrays]] | 281 | [[sparse_arrays]] |
@@ -324,56 +329,51 @@ encoded as a JSON object: | |||
324 | Setting +ratio+ to +0+ disables checking for excessively sparse arrays. | 329 | Setting +ratio+ to +0+ disables checking for excessively sparse arrays. |
325 | 330 | ||
326 | 331 | ||
327 | cjson.encode_max_depth | 332 | cjson.keep_encode_buffer |
328 | ~~~~~~~~~~~~~~~~~~~~~~ | 333 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
329 | 334 | ||
330 | [source,lua] | 335 | [source,lua] |
331 | ------------ | 336 | ------------ |
332 | depth = cjson.encode_max_depth([depth]) | 337 | keep = cjson.keep_encode_buffer([keep]) |
333 | -- "depth" must be a positive integer (>0). | 338 | -- "keep" must be a boolean |
334 | ------------ | 339 | ------------ |
335 | 340 | ||
336 | By default, Lua CJSON will reject data structure with more than 20 nested | 341 | By default, Lua CJSON will reuse the JSON encoding buffer to improve |
337 | tables. | 342 | performance. The buffer will grow to the largest size required and is |
338 | 343 | not freed until the Lua CJSON module is garbage collected. Setting this | |
339 | This check prevents a deeply nested or recursive data structure from | 344 | option to +false+ will cause the buffer to be freed after each call to |
340 | crashing the application. | 345 | +cjson.encode+. |
341 | |||
342 | .Example | ||
343 | [source,lua] | ||
344 | a = {}; b = { a }; a[1] = b | ||
345 | 346 | ||
346 | 347 | ||
347 | cjson.encode_number_precision | 348 | cjson.refuse_invalid_numbers |
348 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 349 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
349 | 350 | ||
350 | [source,lua] | 351 | [source,lua] |
351 | ------------ | 352 | ------------ |
352 | precision = cjson.encode_number_precision([precision]) | 353 | setting = cjson.refuse_invalid_numbers([setting]) |
353 | -- "precision" must be between 1 and 14 (inclusive) | 354 | -- "setting" must be on of: |
355 | -- false, "encode", "decode", "both", true | ||
354 | ------------ | 356 | ------------ |
355 | 357 | ||
356 | By default, Lua CJSON will output 14 significant digits when | 358 | Lua CJSON considers numbers which are outside the JSON specification to be |
357 | converting a number to text. | 359 | _invalid_: |
358 | |||
359 | Reducing number precision to _3_ can improve performance of number | ||
360 | heavy JSON conversions by up to 50%. | ||
361 | 360 | ||
361 | - Infinity | ||
362 | - NaN | ||
363 | - Hexadecimal numbers | ||
362 | 364 | ||
363 | cjson.keep_encode_buffer | 365 | By default Lua CJSON will decode _invalid_ numbers, but will refuse to |
364 | ~~~~~~~~~~~~~~~~~~~~~~~~ | 366 | encode them. |
365 | 367 | ||
366 | [source,lua] | 368 | This setting can be configured separately for encoding and/or |
367 | ------------ | 369 | decoding: |
368 | keep = cjson.keep_encode_buffer([keep]) | ||
369 | -- "keep" must be a boolean | ||
370 | ------------ | ||
371 | 370 | ||
372 | By default, Lua CJSON will reuse the JSON encoding buffer to improve | 371 | Enabled:: |
373 | performance. The buffer will grow to the largest size required and is | 372 | an error will be generated if an _invalid_ number is found. |
374 | not freed until the Lua CJSON module is garbage collected. Setting this | 373 | Disabled (encoding):: |
375 | option to +false+ will cause the buffer to be freed after each call to | 374 | NaN and Infinity can be encoded. |
376 | +cjson.encode+. | 375 | Disabled (decoding):: |
376 | All numbers supported by +strtod+(3) will be parsed. | ||
377 | 377 | ||
378 | 378 | ||
379 | cjson.version | 379 | cjson.version |