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