Debian Codegraph @

manual.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6 <meta name="generator" content="AsciiDoc 8.4.5" />
7 <title>Lua CJSON 2.1.0 Manual</title>
8 <style type="text/css">
9 /* Debug borders */
10 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
11 /*
12 border: 1px solid red;
13 */
14 }
15
16 body {
17 margin: 1em 5% 1em 5%;
18 }
19
20 a {
21 color: blue;
22 text-decoration: underline;
23 }
24 a:visited {
25 color: fuchsia;
26 }
27
28 em {
29 font-style: italic;
30 color: navy;
31 }
32
33 strong {
34 font-weight: bold;
35 color: #083194;
36 }
37
38 tt {
39 color: navy;
40 }
41
42 h1, h2, h3, h4, h5, h6 {
43 color: #527bbd;
44 font-family: sans-serif;
45 margin-top: 1.2em;
46 margin-bottom: 0.5em;
47 line-height: 1.3;
48 }
49
50 h1, h2, h3 {
51 border-bottom: 2px solid silver;
52 }
53 h2 {
54 padding-top: 0.5em;
55 }
56 h3 {
57 float: left;
58 }
59 h3 + * {
60 clear: left;
61 }
62
63 div.sectionbody {
64 font-family: serif;
65 margin-left: 0;
66 }
67
68 hr {
69 border: 1px solid silver;
70 }
71
72 p {
73 margin-top: 0.5em;
74 margin-bottom: 0.5em;
75 }
76
77 ul, ol, li > p {
78 margin-top: 0;
79 }
80
81 pre {
82 padding: 0;
83 margin: 0;
84 }
85
86 span#author {
87 color: #527bbd;
88 font-family: sans-serif;
89 font-weight: bold;
90 font-size: 1.1em;
91 }
92 span#email {
93 }
94 span#revnumber, span#revdate, span#revremark {
95 font-family: sans-serif;
96 }
97
98 div#footer {
99 font-family: sans-serif;
100 font-size: small;
101 border-top: 2px solid silver;
102 padding-top: 0.5em;
103 margin-top: 4.0em;
104 }
105 div#footer-text {
106 float: left;
107 padding-bottom: 0.5em;
108 }
109 div#footer-badges {
110 float: right;
111 padding-bottom: 0.5em;
112 }
113
114 div#preamble {
115 margin-top: 1.5em;
116 margin-bottom: 1.5em;
117 }
118 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120 div.admonitionblock {
121 margin-top: 1.5em;
122 margin-bottom: 1.5em;
123 }
124 div.admonitionblock {
125 margin-top: 2.5em;
126 margin-bottom: 2.5em;
127 }
128
129 div.content { /* Block element content. */
130 padding: 0;
131 }
132
133 /* Block element titles. */
134 div.title, caption.title {
135 color: #527bbd;
136 font-family: sans-serif;
137 font-weight: bold;
138 text-align: left;
139 margin-top: 1.0em;
140 margin-bottom: 0.5em;
141 }
142 div.title + * {
143 margin-top: 0;
144 }
145
146 td div.title:first-child {
147 margin-top: 0.0em;
148 }
149 div.content div.title:first-child {
150 margin-top: 0.0em;
151 }
152 div.content + div.title {
153 margin-top: 0.0em;
154 }
155
156 div.sidebarblock > div.content {
157 background: #ffffee;
158 border: 1px solid silver;
159 padding: 0.5em;
160 }
161
162 div.listingblock > div.content {
163 border: 1px solid silver;
164 background: #f4f4f4;
165 padding: 0.5em;
166 }
167
168 div.quoteblock {
169 padding-left: 2.0em;
170 margin-right: 10%;
171 }
172 div.quoteblock > div.attribution {
173 padding-top: 0.5em;
174 text-align: right;
175 }
176
177 div.verseblock {
178 padding-left: 2.0em;
179 margin-right: 10%;
180 }
181 div.verseblock > div.content {
182 white-space: pre;
183 }
184 div.verseblock > div.attribution {
185 padding-top: 0.75em;
186 text-align: left;
187 }
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
189 div.verseblock + div.attribution {
190 text-align: left;
191 }
192
193 div.admonitionblock .icon {
194 vertical-align: top;
195 font-size: 1.1em;
196 font-weight: bold;
197 text-decoration: underline;
198 color: #527bbd;
199 padding-right: 0.5em;
200 }
201 div.admonitionblock td.content {
202 padding-left: 0.5em;
203 border-left: 2px solid silver;
204 }
205
206 div.exampleblock > div.content {
207 border-left: 2px solid silver;
208 padding: 0.5em;
209 }
210
211 div.imageblock div.content { padding-left: 0; }
212 span.image img { border-style: none; }
213 a.image:visited { color: white; }
214
215 dl {
216 margin-top: 0.8em;
217 margin-bottom: 0.8em;
218 }
219 dt {
220 margin-top: 0.5em;
221 margin-bottom: 0;
222 font-style: normal;
223 color: navy;
224 }
225 dd > *:first-child {
226 margin-top: 0.1em;
227 }
228
229 ul, ol {
230 list-style-position: outside;
231 }
232 ol.arabic {
233 list-style-type: decimal;
234 }
235 ol.loweralpha {
236 list-style-type: lower-alpha;
237 }
238 ol.upperalpha {
239 list-style-type: upper-alpha;
240 }
241 ol.lowerroman {
242 list-style-type: lower-roman;
243 }
244 ol.upperroman {
245 list-style-type: upper-roman;
246 }
247
248 div.compact ul, div.compact ol,
249 div.compact p, div.compact p,
250 div.compact div, div.compact div {
251 margin-top: 0.1em;
252 margin-bottom: 0.1em;
253 }
254
255 div.tableblock > table {
256 border: 3px solid #527bbd;
257 }
258 thead {
259 font-family: sans-serif;
260 font-weight: bold;
261 }
262 tfoot {
263 font-weight: bold;
264 }
265 td > div.verse {
266 white-space: pre;
267 }
268 p.table {
269 margin-top: 0;
270 }
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
272 div.tableblock > table[frame="void"] {
273 border-style: none;
274 }
275 div.tableblock > table[frame="hsides"] {
276 border-left-style: none;
277 border-right-style: none;
278 }
279 div.tableblock > table[frame="vsides"] {
280 border-top-style: none;
281 border-bottom-style: none;
282 }
283
284
285 div.hdlist {
286 margin-top: 0.8em;
287 margin-bottom: 0.8em;
288 }
289 div.hdlist tr {
290 padding-bottom: 15px;
291 }
292 dt.hdlist1.strong, td.hdlist1.strong {
293 font-weight: bold;
294 }
295 td.hdlist1 {
296 vertical-align: top;
297 font-style: normal;
298 padding-right: 0.8em;
299 color: navy;
300 }
301 td.hdlist2 {
302 vertical-align: top;
303 }
304 div.hdlist.compact tr {
305 margin: 0;
306 padding-bottom: 0;
307 }
308
309 .comment {
310 background: yellow;
311 }
312
313 @media print {
314 div#footer-badges { display: none; }
315 }
316
317 div#toctitle {
318 color: #527bbd;
319 font-family: sans-serif;
320 font-size: 1.1em;
321 font-weight: bold;
322 margin-top: 1.0em;
323 margin-bottom: 0.1em;
324 }
325
326 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
327 margin-top: 0;
328 margin-bottom: 0;
329 }
330 div.toclevel2 {
331 margin-left: 2em;
332 font-size: 0.9em;
333 }
334 div.toclevel3 {
335 margin-left: 4em;
336 font-size: 0.9em;
337 }
338 div.toclevel4 {
339 margin-left: 6em;
340 font-size: 0.9em;
341 }
342 /* Workarounds for IE6's broken and incomplete CSS2. */
343
344 div.sidebar-content {
345 background: #ffffee;
346 border: 1px solid silver;
347 padding: 0.5em;
348 }
349 div.sidebar-title, div.image-title {
350 color: #527bbd;
351 font-family: sans-serif;
352 font-weight: bold;
353 margin-top: 0.0em;
354 margin-bottom: 0.5em;
355 }
356
357 div.listingblock div.content {
358 border: 1px solid silver;
359 background: #f4f4f4;
360 padding: 0.5em;
361 }
362
363 div.quoteblock-attribution {
364 padding-top: 0.5em;
365 text-align: right;
366 }
367
368 div.verseblock-content {
369 white-space: pre;
370 }
371 div.verseblock-attribution {
372 padding-top: 0.75em;
373 text-align: left;
374 }
375
376 div.exampleblock-content {
377 border-left: 2px solid silver;
378 padding-left: 0.5em;
379 }
380
381 /* IE6 sets dynamically generated links as visited. */
382 div#toc a:visited { color: blue; }
383 </style>
384 <script type="text/javascript">
385 /*<![CDATA[*/
386 window.onload = function(){generateToc(2)}
387 /* Author: Mihai Bazon, September 2002
388 * http://students.infoiasi.ro/~mishoo
389 *
390 * Table Of Content generator
391 * Version: 0.4
392 *
393 * Feel free to use this script under the terms of the GNU General Public
394 * License, as long as you do not remove or alter this notice.
395 */
396
397 /* modified by Troy D. Hanson, September 2006. License: GPL */
398 /* modified by Stuart Rackham, October 2006. License: GPL */
399
400 function getText(el) {
401 var text = "";
402 for (var i = el.firstChild; i != null; i = i.nextSibling) {
403 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
404 text += i.data;
405 else if (i.firstChild != null)
406 text += getText(i);
407 }
408 return text;
409 }
410
411 function TocEntry(el, text, toclevel) {
412 this.element = el;
413 this.text = text;
414 this.toclevel = toclevel;
415 }
416
417 function tocEntries(el, toclevels) {
418 var result = new Array;
419 var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
420 // Function that scans the DOM tree for header elements (the DOM2
421 // nodeIterator API would be a better technique but not supported by all
422 // browsers).
423 var iterate = function (el) {
424 for (var i = el.firstChild; i != null; i = i.nextSibling) {
425 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
426 var mo = re.exec(i.tagName)
427 if (mo)
428 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
429 iterate(i);
430 }
431 }
432 }
433 iterate(el);
434 return result;
435 }
436
437 // This function does the work. toclevels = 1..4.
438 function generateToc(toclevels) {
439 var toc = document.getElementById("toc");
440 var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
441 for (var i = 0; i < entries.length; ++i) {
442 var entry = entries[i];
443 if (entry.element.id == "")
444 entry.element.id = "toc" + i;
445 var a = document.createElement("a");
446 a.href = "#" + entry.element.id;
447 a.appendChild(document.createTextNode(entry.text));
448 var div = document.createElement("div");
449 div.appendChild(a);
450 div.className = "toclevel" + entry.toclevel;
451 toc.appendChild(div);
452 }
453 if (entries.length == 0)
454 document.getElementById("header").removeChild(toc);
455 }
456 /*]]>*/
457 </script>
458 </head>
459 <body>
460 <div id="header">
461 <h1>Lua CJSON 2.1.0 Manual</h1>
462 <span id="author">Mark Pulford</span><br />
463 <span id="email"><tt>&lt;<a href="mailto:[email protected]">[email protected]</a>&gt;</tt></span><br />
464 <span id="revdate">1st March 2012</span>
465 <div id="toc">
466 <div id="toctitle">Table of Contents</div>
467 <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
468 </div>
469 </div>
470 <h2 id="_overview">1. Overview</h2>
471 <div class="sectionbody">
472 <div class="paragraph"><p>The Lua CJSON module provides JSON support for Lua.</p></div>
473 <div class="dlist"><dl>
474 <dt class="hdlist1">
475 <strong>Features</strong>
476 </dt>
477 <dd>
478 <div class="ulist"><ul>
479 <li>
480 <p>
481 Fast, standards compliant encoding/parsing routines
482 </p>
483 </li>
484 <li>
485 <p>
486 Full support for JSON with UTF-8, including decoding surrogate pairs
487 </p>
488 </li>
489 <li>
490 <p>
491 Optional run-time support for common exceptions to the JSON
492 specification (infinity, NaN,..)
493 </p>
494 </li>
495 <li>
496 <p>
497 No dependencies on other libraries
498 </p>
499 </li>
500 </ul></div>
501 </dd>
502 <dt class="hdlist1">
503 <strong>Caveats</strong>
504 </dt>
505 <dd>
506 <div class="ulist"><ul>
507 <li>
508 <p>
509 UTF-16 and UTF-32 are not supported
510 </p>
511 </li>
512 </ul></div>
513 </dd>
514 </dl></div>
515 <div class="paragraph"><p>Lua CJSON is covered by the MIT license. Review the file <tt>LICENSE</tt> for
516 details.</p></div>
517 <div class="paragraph"><p>The latest version of this software is available from the
518 <a href="http://www.kyne.com.au/%7Emark/software/lua-cjson.php">Lua CJSON website</a>.</p></div>
519 <div class="paragraph"><p>Feel free to email me if you have any patches, suggestions, or comments.</p></div>
520 </div>
521 <h2 id="_installation">2. Installation</h2>
522 <div class="sectionbody">
523 <div class="paragraph"><p>Lua CJSON requires either <a href="http://www.lua.org">Lua</a> 5.1, Lua 5.2, or
524 <a href="http://www.luajit.org">LuaJIT</a> to build.</p></div>
525 <div class="paragraph"><p>The build method can be selected from 4 options:</p></div>
526 <div class="dlist"><dl>
527 <dt class="hdlist1">
528 Make
529 </dt>
530 <dd>
531 <p>
532 Unix (including Linux, BSD, Mac OSX &amp; Solaris), Windows
533 </p>
534 </dd>
535 <dt class="hdlist1">
536 CMake
537 </dt>
538 <dd>
539 <p>
540 Unix, Windows
541 </p>
542 </dd>
543 <dt class="hdlist1">
544 RPM
545 </dt>
546 <dd>
547 <p>
548 Linux
549 </p>
550 </dd>
551 <dt class="hdlist1">
552 LuaRocks
553 </dt>
554 <dd>
555 <p>
556 Unix, Windows
557 </p>
558 </dd>
559 </dl></div>
560 <h3 id="_make">2.1. Make</h3><div style="clear:left"></div>
561 <div class="paragraph"><p>The included <tt>Makefile</tt> has generic settings.</p></div>
562 <div class="paragraph"><p>First, review and update the included makefile to suit your platform (if
563 required).</p></div>
564 <div class="paragraph"><p>Next, build and install the module:</p></div>
565 <div class="exampleblock">
566 <div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4
567 by Lorenzo Bettini
568 http://www.lorenzobettini.it
569 http://www.gnu.org/software/src-highlite -->
570 <pre><tt>make install</tt></pre></div></div>
571 <div class="paragraph"><p>Or install manually into your Lua module directory:</p></div>
572 <div class="exampleblock">
573 <div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4
574 by Lorenzo Bettini
575 http://www.lorenzobettini.it
576 http://www.gnu.org/software/src-highlite -->
577 <pre><tt>make
578 cp cjson<span style="color: #990000">.</span>so <span style="color: #009900">$LUA_MODULE_DIRECTORY</span></tt></pre></div></div>
579 <h3 id="_cmake">2.2. CMake</h3><div style="clear:left"></div>
580 <div class="paragraph"><p><a href="http://www.cmake.org">CMake</a> can generate build configuration for many
581 different platforms (including Unix and Windows).</p></div>
582 <div class="paragraph"><p>First, generate the makefile for your platform using CMake. If CMake is
583 unable to find Lua, manually set the <tt>LUA_DIR</tt> environment variable to
584 the base prefix of your Lua 5.1 installation.</p></div>
585 <div class="paragraph"><p>While <tt>cmake</tt> is used in the example below, <tt>ccmake</tt> or <tt>cmake-gui</tt> may
586 be used to present an interface for changing the default build options.</p></div>
587 <div class="exampleblock">
588 <div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4
589 by Lorenzo Bettini
590 http://www.lorenzobettini.it
591 http://www.gnu.org/software/src-highlite -->
592 <pre><tt>mkdir build
593 cd build
594 <span style="font-style: italic"><span style="color: #9A1900"># Optional: export LUA_DIR=$LUA51_PREFIX</span></span>
595 cmake <span style="color: #990000">..</span></tt></pre></div></div>
596 <div class="paragraph"><p>Next, build and install the module:</p></div>
597 <div class="exampleblock">
598 <div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4
599 by Lorenzo Bettini
600 http://www.lorenzobettini.it
601 http://www.gnu.org/software/src-highlite -->
602 <pre><tt>make install
603 <span style="font-style: italic"><span style="color: #9A1900"># Or:</span></span>
604 make
605 cp cjson<span style="color: #990000">.</span>so <span style="color: #009900">$LUA_MODULE_DIRECTORY</span></tt></pre></div></div>
606 <div class="paragraph"><p>Review the
607 <a href="http://www.cmake.org/cmake/help/documentation.html">CMake documentation</a>
608 for further details.</p></div>
609 <h3 id="_rpm">2.3. RPM</h3><div style="clear:left"></div>
610 <div class="paragraph"><p>Linux distributions using <a href="http://rpm.org">RPM</a> can create a package via
611 the included RPM spec file. Ensure the <tt>rpm-build</tt> package (or similar)
612 has been installed.</p></div>
613 <div class="paragraph"><p>Build and install the module via RPM:</p></div>
614 <div class="exampleblock">
615 <div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4
616 by Lorenzo Bettini
617 http://www.lorenzobettini.it
618 http://www.gnu.org/software/src-highlite -->
619 <pre><tt>rpmbuild -tb lua-cjson-<span style="color: #993399">2.1</span><span style="color: #990000">.</span><span style="color: #993399">0</span><span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz
620 rpm -Uvh <span style="color: #009900">$LUA_CJSON_RPM</span></tt></pre></div></div>
621 <h3 id="_luarocks">2.4. LuaRocks</h3><div style="clear:left"></div>
622 <div class="paragraph"><p><a href="http://luarocks.org">LuaRocks</a> can be used to install and manage Lua
623 modules on a wide range of platforms (including Windows).</p></div>
624 <div class="paragraph"><p>First, extract the Lua CJSON source package.</p></div>
625 <div class="paragraph"><p>Next, install the module:</p></div>
626 <div class="exampleblock">
627 <div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4
628 by Lorenzo Bettini
629 http://www.lorenzobettini.it
630 http://www.gnu.org/software/src-highlite -->
631 <pre><tt>cd lua-cjson-<span style="color: #993399">2.1</span><span style="color: #990000">.</span><span style="color: #993399">0</span>
632 luarocks make</tt></pre></div></div>
633 <div class="admonitionblock">
634 <table><tr>
635 <td class="icon">
636 <div class="title">Note</div>
637 </td>
638 <td class="content">LuaRocks does not support platform specific configuration for Solaris.
639 On Solaris, you may need to manually uncomment <tt>USE_INTERNAL_ISINF</tt> in
640 the rockspec before building this module.</td>
641 </tr></table>
642 </div>
643 <div class="paragraph"><p>Review the <a href="http://luarocks.org/en/Documentation">LuaRocks documentation</a>
644 for further details.</p></div>
645 <h3 id="build_options">2.5. Build Options (#define)</h3><div style="clear:left"></div>
646 <div class="paragraph"><p>Lua CJSON offers several <tt>#define</tt> build options to address portability
647 issues, and enable non-default features. Some build methods may
648 automatically set platform specific options if required. Other features
649 should be enabled manually.</p></div>
650 <div class="dlist"><dl>
651 <dt class="hdlist1">
652 USE_INTERNAL_ISINF
653 </dt>
654 <dd>
655 <p>
656 Workaround for Solaris platforms missing <tt>isinf</tt>.
657 </p>
658 </dd>
659 <dt class="hdlist1">
660 DISABLE_INVALID_NUMBERS
661 </dt>
662 <dd>
663 <p>
664 Recommended on platforms where <tt>strtod</tt> /
665 <tt>sprintf</tt> are not POSIX compliant (eg, Windows MinGW). Prevents
666 <tt>cjson.encode_invalid_numbers</tt> and <tt>cjson.decode_invalid_numbers</tt> from
667 being enabled. However, <tt>cjson.encode_invalid_numbers</tt> may still be
668 set to <tt>"null"</tt>. When using the Lua CJSON built-in floating point
669 conversion this option is unnecessary and is ignored.
670 </p>
671 </dd>
672 </dl></div>
673 <h4 id="_built_in_floating_point_conversion">2.5.1. Built-in floating point conversion</h4>
674 <div class="paragraph"><p>Lua CJSON may be built with David Gay&#8217;s
675 <a href="http://www.netlib.org/fp/">floating point conversion routines</a>. This can
676 increase overall performance by up to 50% on some platforms when
677 converting a large amount of numeric data. However, this option reduces
678 portability and is disabled by default.</p></div>
679 <div class="dlist"><dl>
680 <dt class="hdlist1">
681 USE_INTERNAL_FPCONV
682 </dt>
683 <dd>
684 <p>
685 Enable internal number conversion routines.
686 </p>
687 </dd>
688 <dt class="hdlist1">
689 IEEE_BIG_ENDIAN
690 </dt>
691 <dd>
692 <p>
693 Must be set on big endian architectures.
694 </p>
695 </dd>
696 <dt class="hdlist1">
697 MULTIPLE_THREADS
698 </dt>
699 <dd>
700 <p>
701 Must be set if Lua CJSON may be used in a
702 multi-threaded application. Requires the <em>pthreads</em> library.
703 </p>
704 </dd>
705 </dl></div>
706 </div>
707 <h2 id="_api_functions">3. API (Functions)</h2>
708 <div class="sectionbody">
709 <h3 id="_synopsis">3.1. Synopsis</h3><div style="clear:left"></div>
710 <div class="listingblock">
711 <div class="content"><!-- Generator: GNU source-highlight 3.1.4
712 by Lorenzo Bettini
713 http://www.lorenzobettini.it
714 http://www.gnu.org/software/src-highlite -->
715 <pre><tt><span style="font-style: italic"><span style="color: #9A1900">-- Module instantiation</span></span>
716 <span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cjson <span style="color: #990000">=</span> require <span style="color: #FF0000">"cjson"</span>
717 <span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cjson2 <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">new</span></span><span style="color: #990000">()</span>
718 <span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cjson_safe <span style="color: #990000">=</span> require <span style="color: #FF0000">"cjson.safe"</span>
719
720 <span style="font-style: italic"><span style="color: #9A1900">-- Translate Lua value to/from JSON</span></span>
721 text <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode</span></span><span style="color: #990000">(</span>value<span style="color: #990000">)</span>
722 value <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode</span></span><span style="color: #990000">(</span>text<span style="color: #990000">)</span>
723
724 <span style="font-style: italic"><span style="color: #9A1900">-- Get and/or set Lua CJSON configuration</span></span>
725 setting <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode_invalid_numbers</span></span><span style="color: #990000">([</span>setting<span style="color: #990000">])</span>
726 setting <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_invalid_numbers</span></span><span style="color: #990000">([</span>setting<span style="color: #990000">])</span>
727 keep <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_keep_buffer</span></span><span style="color: #990000">([</span>keep<span style="color: #990000">])</span>
728 depth <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_max_depth</span></span><span style="color: #990000">([</span>depth<span style="color: #990000">])</span>
729 depth <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode_max_depth</span></span><span style="color: #990000">([</span>depth<span style="color: #990000">])</span>
730 convert<span style="color: #990000">,</span> ratio<span style="color: #990000">,</span> safe <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_sparse_array</span></span><span style="color: #990000">([</span>convert<span style="color: #990000">[,</span> ratio<span style="color: #990000">[,</span> safe<span style="color: #990000">]]])</span></tt></pre></div></div>
731 <h3 id="_module_instantiation">3.2. Module Instantiation</h3><div style="clear:left"></div>
732 <div class="listingblock">
733 <div class="content"><!-- Generator: GNU source-highlight 3.1.4
734 by Lorenzo Bettini
735 http://www.lorenzobettini.it
736 http://www.gnu.org/software/src-highlite -->
737 <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cjson <span style="color: #990000">=</span> require <span style="color: #FF0000">"cjson"</span>
738 <span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cjson2 <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">new</span></span><span style="color: #990000">()</span>
739 <span style="font-weight: bold"><span style="color: #0000FF">local</span></span> cjson_safe <span style="color: #990000">=</span> require <span style="color: #FF0000">"cjson.safe"</span></tt></pre></div></div>
740 <div class="paragraph"><p>Import Lua CJSON via the Lua <tt>require</tt> function. Lua CJSON does not
741 register a global module table.</p></div>
742 <div class="paragraph"><p>The <tt>cjson</tt> module will throw an error during JSON conversion if any
743 invalid data is encountered. Refer to <a href="#cjson_encode"><tt>cjson.encode</tt></a>
744 and <a href="#cjson_decode"><tt>cjson.decode</tt></a> for details.</p></div>
745 <div class="paragraph"><p>The <tt>cjson.safe</tt> module behaves identically to the <tt>cjson</tt> module,
746 except when errors are encountered during JSON conversion. On error, the
747 <tt>cjson_safe.encode</tt> and <tt>cjson_safe.decode</tt> functions will return
748 <tt>nil</tt> followed by the error message.</p></div>
749 <div class="paragraph"><p><tt>cjson.new</tt> can be used to instantiate an independent copy of the Lua
750 CJSON module. The new module has a separate persistent encoding buffer,
751 and default settings.</p></div>
752 <div class="paragraph"><p>Lua CJSON can support Lua implementations using multiple preemptive
753 threads within a single Lua state provided the persistent encoding
754 buffer is not shared. This can be achieved by one of the following
755 methods:</p></div>
756 <div class="ulist"><ul>
757 <li>
758 <p>
759 Disabling the persistent encoding buffer with
760 <a href="#encode_keep_buffer"><tt>cjson.encode_keep_buffer</tt></a>
761 </p>
762 </li>
763 <li>
764 <p>
765 Ensuring each thread calls <a href="#encode"><tt>cjson.encode</tt></a> separately (ie,
766 treat <tt>cjson.encode</tt> as non-reentrant).
767 </p>
768 </li>
769 <li>
770 <p>
771 Using a separate <tt>cjson</tt> module table per preemptive thread
772 (<tt>cjson.new</tt>)
773 </p>
774 </li>
775 </ul></div>
776 <div class="admonitionblock">
777 <table><tr>
778 <td class="icon">
779 <div class="title">Note</div>
780 </td>
781 <td class="content">Lua CJSON uses <tt>strtod</tt> and <tt>snprintf</tt> to perform numeric conversion as
782 they are usually well supported, fast and bug free. However, these
783 functions require a workaround for JSON encoding/parsing under locales
784 using a comma decimal separator. Lua CJSON detects the current locale
785 during instantiation to determine and automatically implement the
786 workaround if required. Lua CJSON should be reinitialised via
787 <tt>cjson.new</tt> if the locale of the current process changes. Using a
788 different locale per thread is not supported.</td>
789 </tr></table>
790 </div>
791 <h3 id="_decode">3.3. decode</h3><div style="clear:left"></div>
792 <div class="listingblock">
793 <div class="content"><!-- Generator: GNU source-highlight 3.1.4
794 by Lorenzo Bettini
795 http://www.lorenzobettini.it
796 http://www.gnu.org/software/src-highlite -->
797 <pre><tt>value <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode</span></span><span style="color: #990000">(</span>json_text<span style="color: #990000">)</span></tt></pre></div></div>
798 <div class="paragraph"><p><tt>cjson.decode</tt> will deserialise any UTF-8 JSON string into a Lua value
799 or table.</p></div>
800 <div class="paragraph"><p>UTF-16 and UTF-32 JSON strings are not supported.</p></div>
801 <div class="paragraph"><p><tt>cjson.decode</tt> requires that any NULL (ASCII 0) and double quote (ASCII
802 34) characters are escaped within strings. All escape codes will be
803 decoded and other bytes will be passed transparently. UTF-8 characters
804 are not validated during decoding and should be checked elsewhere if
805 required.</p></div>
806 <div class="paragraph"><p>JSON <tt>null</tt> will be converted to a NULL <tt>lightuserdata</tt> value. This can
807 be compared with <tt>cjson.null</tt> for convenience.</p></div>
808 <div class="paragraph"><p>By default, numbers incompatible with the JSON specification (infinity,
809 NaN, hexadecimal) can be decoded. This default can be changed with
810 <a href="#decode_invalid_numbers"><tt>cjson.decode_invalid_numbers</tt></a>.</p></div>
811 <div class="exampleblock">
812 <div class="title">Example: Decoding</div>
813 <div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4
814 by Lorenzo Bettini
815 http://www.lorenzobettini.it
816 http://www.gnu.org/software/src-highlite -->
817 <pre><tt>json_text <span style="color: #990000">=</span> <span style="color: #FF0000">'[ true, { "foo": "bar" } ]'</span>
818 value <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode</span></span><span style="color: #990000">(</span>json_text<span style="color: #990000">)</span>
819 <span style="font-style: italic"><span style="color: #9A1900">-- Returns: { true, { foo = "bar" } }</span></span></tt></pre></div></div>
820 <div class="admonitionblock">
821 <table><tr>
822 <td class="icon">
823 <div class="title">Caution</div>
824 </td>
825 <td class="content">Care must be taken after decoding JSON objects with numeric keys. Each
826 numeric key will be stored as a Lua <tt>string</tt>. Any subsequent code
827 assuming type <tt>number</tt> may break.</td>
828 </tr></table>
829 </div>
830 <h3 id="decode_invalid_numbers">3.4. decode_invalid_numbers</h3><div style="clear:left"></div>
831 <div class="listingblock">
832 <div class="content"><!-- Generator: GNU source-highlight 3.1.4
833 by Lorenzo Bettini
834 http://www.lorenzobettini.it
835 http://www.gnu.org/software/src-highlite -->
836 <pre><tt>setting <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode_invalid_numbers</span></span><span style="color: #990000">([</span>setting<span style="color: #990000">])</span>
837 <span style="font-style: italic"><span style="color: #9A1900">-- "setting" must be a boolean. Default: true.</span></span></tt></pre></div></div>
838 <div class="paragraph"><p>Lua CJSON may generate an error when trying to decode numbers not
839 supported by the JSON specification. <em>Invalid numbers</em> are defined as:</p></div>
840 <div class="ulist"><ul>
841 <li>
842 <p>
843 infinity
844 </p>
845 </li>
846 <li>
847 <p>
848 not-a-number (NaN)
849 </p>
850 </li>
851 <li>
852 <p>
853 hexadecimal
854 </p>
855 </li>
856 </ul></div>
857 <div class="paragraph"><p>Available settings:</p></div>
858 <div class="dlist"><dl>
859 <dt class="hdlist1">
860 <tt>true</tt>
861 </dt>
862 <dd>
863 <p>
864 Accept and decode <em>invalid numbers</em>. This is the default
865 setting.
866 </p>
867 </dd>
868 <dt class="hdlist1">
869 <tt>false</tt>
870 </dt>
871 <dd>
872 <p>
873 Throw an error when <em>invalid numbers</em> are encountered.
874 </p>
875 </dd>
876 </dl></div>
877 <div class="paragraph"><p>The current setting is always returned, and is only updated when an
878 argument is provided.</p></div>
879 <h3 id="decode_max_depth">3.5. decode_max_depth</h3><div style="clear:left"></div>
880 <div class="listingblock">
881 <div class="content"><!-- Generator: GNU source-highlight 3.1.4
882 by Lorenzo Bettini
883 http://www.lorenzobettini.it
884 http://www.gnu.org/software/src-highlite -->
885 <pre><tt>depth <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">decode_max_depth</span></span><span style="color: #990000">([</span>depth<span style="color: #990000">])</span>
886 <span style="font-style: italic"><span style="color: #9A1900">-- "depth" must be a positive integer. Default: 1000.</span></span></tt></pre></div></div>
887 <div class="paragraph"><p>Lua CJSON will generate an error when parsing deeply nested JSON once
888 the maximum array/object depth has been exceeded. This check prevents
889 unnecessarily complicated JSON from slowing down the application, or
890 crashing the application due to lack of process stack space.</p></div>
891 <div class="paragraph"><p>An error may be generated before the depth limit is hit if Lua is unable
892 to allocate more objects on the Lua stack.</p></div>
893 <div class="paragraph"><p>By default, Lua CJSON will reject JSON with arrays and/or objects nested
894 more than 1000 levels deep.</p></div>
895 <div class="paragraph"><p>The current setting is always returned, and is only updated when an
896 argument is provided.</p></div>
897 <h3 id="encode">3.6. encode</h3><div style="clear:left"></div>
898 <div class="listingblock">
899 <div class="content"><!-- Generator: GNU source-highlight 3.1.4
900 by Lorenzo Bettini
901 http://www.lorenzobettini.it
902 http://www.gnu.org/software/src-highlite -->
903 <pre><tt>json_text <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode</span></span><span style="color: #990000">(</span>value<span style="color: #990000">)</span></tt></pre></div></div>
904 <div class="paragraph"><p><tt>cjson.encode</tt> will serialise a Lua value into a string containing the
905 JSON representation.</p></div>
906 <div class="paragraph"><p><tt>cjson.encode</tt> supports the following types:</p></div>
907 <div class="ulist"><ul>
908 <li>
909 <p>
910 <tt>boolean</tt>
911 </p>
912 </li>
913 <li>
914 <p>
915 <tt>lightuserdata</tt> (NULL value only)
916 </p>
917 </li>
918 <li>
919 <p>
920 <tt>nil</tt>
921 </p>
922 </li>
923 <li>
924 <p>
925 <tt>number</tt>
926 </p>
927 </li>
928 <li>
929 <p>
930 <tt>string</tt>
931 </p>
932 </li>
933 <li>
934 <p>
935 <tt>table</tt>
936 </p>
937 </li>
938 </ul></div>
939 <div class="paragraph"><p>The remaining Lua types will generate an error:</p></div>
940 <div class="ulist"><ul>
941 <li>
942 <p>
943 <tt>function</tt>
944 </p>
945 </li>
946 <li>
947 <p>
948 <tt>lightuserdata</tt> (non-NULL values)
949 </p>
950 </li>
951 <li>
952 <p>
953 <tt>thread</tt>
954 </p>
955 </li>
956 <li>
957 <p>
958 <tt>userdata</tt>
959 </p>
960 </li>
961 </ul></div>
962 <div class="paragraph"><p>By default, numbers are encoded with 14 significant digits. Refer to
963 <a href="#encode_number_precision"><tt>cjson.encode_number_precision</tt></a> for details.</p></div>
964 <div class="paragraph"><p>Lua CJSON will escape the following characters within each UTF-8 string:</p></div>
965 <div class="ulist"><ul>
966 <li>
967 <p>
968 Control characters (ASCII 0 - 31)
969 </p>
970 </li>
971 <li>
972 <p>
973 Double quote (ASCII 34)
974 </p>
975 </li>
976 <li>
977 <p>
978 Forward slash (ASCII 47)
979 </p>
980 </li>
981 <li>
982 <p>
983 Blackslash (ASCII 92)
984 </p>
985 </li>
986 <li>
987 <p>
988 Delete (ASCII 127)
989 </p>
990 </li>
991 </ul></div>
992 <div class="paragraph"><p>All other bytes are passed transparently.</p></div>
993 <div class="admonitionblock">
994 <table><tr>
995 <td class="icon">
996 <div class="title">Caution</div>
997 </td>
998 <td class="content">
999 <div class="paragraph"><p>Lua CJSON will successfully encode/decode binary strings, but this is
1000 technically not supported by JSON and may not be compatible with other
1001 JSON libraries. To ensure the output is valid JSON, applications should
1002 ensure all Lua strings passed to <tt>cjson.encode</tt> are UTF-8.</p></div>
1003 <div class="paragraph"><p>Base64 is commonly used to encode binary data as the most efficient
1004 encoding under UTF-8 can only reduce the encoded size by a further
1005 &#126;8%. Lua Base64 routines can be found in the
1006 <a href="http://w3.impa.br/%7Ediego/software/luasocket/">LuaSocket</a> and
1007 <a href="http://www.tecgraf.puc-rio.br/%7Elhf/ftp/lua/#lbase64">lbase64</a> packages.</p></div>
1008 </td>
1009 </tr></table>
1010 </div>
1011 <div class="paragraph"><p>Lua CJSON uses a heuristic to determine whether to encode a Lua table as
1012 a JSON array or an object. A Lua table with only positive integer keys
1013 of type <tt>number</tt> will be encoded as a JSON array. All other tables will
1014 be encoded as a JSON object.</p></div>
1015 <div class="paragraph"><p>Lua CJSON does not use metamethods when serialising tables.</p></div>
1016 <div class="ulist"><ul>
1017 <li>
1018 <p>
1019 <tt>rawget</tt> is used to iterate over Lua arrays
1020 </p>
1021 </li>
1022 <li>
1023 <p>
1024 <tt>next</tt> is used to iterate over Lua objects
1025 </p>
1026 </li>
1027 </ul></div>
1028 <div class="paragraph"><p>Lua arrays with missing entries (<em>sparse arrays</em>) may optionally be
1029 encoded in several different ways. Refer to
1030 <a href="#encode_sparse_array"><tt>cjson.encode_sparse_array</tt></a> for details.</p></div>
1031 <div class="paragraph"><p>JSON object keys are always strings. Hence <tt>cjson.encode</tt> only supports
1032 table keys which are type <tt>number</tt> or <tt>string</tt>. All other types will
1033 generate an error.</p></div>
1034 <div class="admonitionblock">
1035 <table><tr>
1036 <td class="icon">
1037 <div class="title">Note</div>
1038 </td>
1039 <td class="content">Standards compliant JSON must be encapsulated in either an object (<tt>{}</tt>)
1040 or an array (<tt>[]</tt>). If strictly standards compliant JSON is desired, a
1041 table must be passed to <tt>cjson.encode</tt>.</td>
1042 </tr></table>
1043 </div>
1044 <div class="paragraph"><p>By default, encoding the following Lua values will generate errors:</p></div>
1045 <div class="ulist"><ul>
1046 <li>
1047 <p>
1048 Numbers incompatible with the JSON specification (infinity, NaN)
1049 </p>
1050 </li>
1051 <li>
1052 <p>
1053 Tables nested more than 1000 levels deep
1054 </p>
1055 </li>
1056 <li>
1057 <p>
1058 Excessively sparse Lua arrays
1059 </p>
1060 </li>
1061 </ul></div>
1062 <div class="paragraph"><p>These defaults can be changed with:</p></div>
1063 <div class="ulist"><ul>
1064 <li>
1065 <p>
1066 <a href="#encode_invalid_numbers"><tt>cjson.encode_invalid_numbers</tt></a>
1067 </p>
1068 </li>
1069 <li>
1070 <p>
1071 <a href="#encode_max_depth"><tt>cjson.encode_max_depth</tt></a>
1072 </p>
1073 </li>
1074 <li>
1075 <p>
1076 <a href="#encode_sparse_array"><tt>cjson.encode_sparse_array</tt></a>
1077 </p>
1078 </li>
1079 </ul></div>
1080 <div class="exampleblock">
1081 <div class="title">Example: Encoding</div>
1082 <div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4
1083 by Lorenzo Bettini
1084 http://www.lorenzobettini.it
1085 http://www.gnu.org/software/src-highlite -->
1086 <pre><tt>value <span style="color: #990000">=</span> <span style="color: #FF0000">{</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span><span style="color: #990000">,</span> <span style="color: #FF0000">{</span> foo <span style="color: #990000">=</span> <span style="color: #FF0000">"bar"</span> <span style="color: #FF0000">}</span> <span style="color: #FF0000">}</span>
1087 json_text <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode</span></span><span style="color: #990000">(</span>value<span style="color: #990000">)</span>
1088 <span style="font-style: italic"><span style="color: #9A1900">-- Returns: '[true,{"foo":"bar"}]'</span></span></tt></pre></div></div>
1089 <h3 id="encode_invalid_numbers">3.7. encode_invalid_numbers</h3><div style="clear:left"></div>
1090 <div class="listingblock">
1091 <div class="content"><!-- Generator: GNU source-highlight 3.1.4
1092 by Lorenzo Bettini
1093 http://www.lorenzobettini.it
1094 http://www.gnu.org/software/src-highlite -->
1095 <pre><tt>setting <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_invalid_numbers</span></span><span style="color: #990000">([</span>setting<span style="color: #990000">])</span>
1096 <span style="font-style: italic"><span style="color: #9A1900">-- "setting" must a boolean or "null". Default: false.</span></span></tt></pre></div></div>
1097 <div class="paragraph"><p>Lua CJSON may generate an error when encoding floating point numbers not
1098 supported by the JSON specification (<em>invalid numbers</em>):</p></div>
1099 <div class="ulist"><ul>
1100 <li>
1101 <p>
1102 infinity
1103 </p>
1104 </li>
1105 <li>
1106 <p>
1107 not-a-number (NaN)
1108 </p>
1109 </li>
1110 </ul></div>
1111 <div class="paragraph"><p>Available settings:</p></div>
1112 <div class="dlist"><dl>
1113 <dt class="hdlist1">
1114 <tt>true</tt>
1115 </dt>
1116 <dd>
1117 <p>
1118 Allow <em>invalid numbers</em> to be encoded. This will generate
1119 non-standard JSON, but this output is supported by some libraries.
1120 </p>
1121 </dd>
1122 <dt class="hdlist1">
1123 <tt>"null"</tt>
1124 </dt>
1125 <dd>
1126 <p>
1127 Encode <em>invalid numbers</em> as a JSON <tt>null</tt> value. This allows
1128 infinity and NaN to be encoded into valid JSON.
1129 </p>
1130 </dd>
1131 <dt class="hdlist1">
1132 <tt>false</tt>
1133 </dt>
1134 <dd>
1135 <p>
1136 Throw an error when attempting to encode <em>invalid numbers</em>.
1137 This is the default setting.
1138 </p>
1139 </dd>
1140 </dl></div>
1141 <div class="paragraph"><p>The current setting is always returned, and is only updated when an
1142 argument is provided.</p></div>
1143 <h3 id="encode_keep_buffer">3.8. encode_keep_buffer</h3><div style="clear:left"></div>
1144 <div class="listingblock">
1145 <div class="content"><!-- Generator: GNU source-highlight 3.1.4
1146 by Lorenzo Bettini
1147 http://www.lorenzobettini.it
1148 http://www.gnu.org/software/src-highlite -->
1149 <pre><tt>keep <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_keep_buffer</span></span><span style="color: #990000">([</span>keep<span style="color: #990000">])</span>
1150 <span style="font-style: italic"><span style="color: #9A1900">-- "keep" must be a boolean. Default: true.</span></span></tt></pre></div></div>
1151 <div class="paragraph"><p>Lua CJSON can reuse the JSON encoding buffer to improve performance.</p></div>
1152 <div class="paragraph"><p>Available settings:</p></div>
1153 <div class="dlist"><dl>
1154 <dt class="hdlist1">
1155 <tt>true</tt>
1156 </dt>
1157 <dd>
1158 <p>
1159 The buffer will grow to the largest size required and is not
1160 freed until the Lua CJSON module is garbage collected. This is the
1161 default setting.
1162 </p>
1163 </dd>
1164 <dt class="hdlist1">
1165 <tt>false</tt>
1166 </dt>
1167 <dd>
1168 <p>
1169 Free the encode buffer after each call to <tt>cjson.encode</tt>.
1170 </p>
1171 </dd>
1172 </dl></div>
1173 <div class="paragraph"><p>The current setting is always returned, and is only updated when an
1174 argument is provided.</p></div>
1175 <h3 id="encode_max_depth">3.9. encode_max_depth</h3><div style="clear:left"></div>
1176 <div class="listingblock">
1177 <div class="content"><!-- Generator: GNU source-highlight 3.1.4
1178 by Lorenzo Bettini
1179 http://www.lorenzobettini.it
1180 http://www.gnu.org/software/src-highlite -->
1181 <pre><tt>depth <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_max_depth</span></span><span style="color: #990000">([</span>depth<span style="color: #990000">])</span>
1182 <span style="font-style: italic"><span style="color: #9A1900">-- "depth" must be a positive integer. Default: 1000.</span></span></tt></pre></div></div>
1183 <div class="paragraph"><p>Once the maximum table depth has been exceeded Lua CJSON will generate
1184 an error. This prevents a deeply nested or recursive data structure from
1185 crashing the application.</p></div>
1186 <div class="paragraph"><p>By default, Lua CJSON will generate an error when trying to encode data
1187 structures with more than 1000 nested tables.</p></div>
1188 <div class="paragraph"><p>The current setting is always returned, and is only updated when an
1189 argument is provided.</p></div>
1190 <div class="exampleblock">
1191 <div class="title">Example: Recursive Lua table</div>
1192 <div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4
1193 by Lorenzo Bettini
1194 http://www.lorenzobettini.it
1195 http://www.gnu.org/software/src-highlite -->
1196 <pre><tt>a <span style="color: #990000">=</span> <span style="color: #FF0000">{}</span><span style="color: #990000">;</span> a<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> a</tt></pre></div></div>
1197 <h3 id="encode_number_precision">3.10. encode_number_precision</h3><div style="clear:left"></div>
1198 <div class="listingblock">
1199 <div class="content"><!-- Generator: GNU source-highlight 3.1.4
1200 by Lorenzo Bettini
1201 http://www.lorenzobettini.it
1202 http://www.gnu.org/software/src-highlite -->
1203 <pre><tt>precision <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_number_precision</span></span><span style="color: #990000">([</span>precision<span style="color: #990000">])</span>
1204 <span style="font-style: italic"><span style="color: #9A1900">-- "precision" must be an integer between 1 and 14. Default: 14.</span></span></tt></pre></div></div>
1205 <div class="paragraph"><p>The amount of significant digits returned by Lua CJSON when encoding
1206 numbers can be changed to balance accuracy versus performance. For data
1207 structures containing many numbers, setting
1208 <tt>cjson.encode_number_precision</tt> to a smaller integer, for example <tt>3</tt>,
1209 can improve encoding performance by up to 50%.</p></div>
1210 <div class="paragraph"><p>By default, Lua CJSON will output 14 significant digits when converting
1211 a number to text.</p></div>
1212 <div class="paragraph"><p>The current setting is always returned, and is only updated when an
1213 argument is provided.</p></div>
1214 <h3 id="encode_sparse_array">3.11. encode_sparse_array</h3><div style="clear:left"></div>
1215 <div class="listingblock">
1216 <div class="content"><!-- Generator: GNU source-highlight 3.1.4
1217 by Lorenzo Bettini
1218 http://www.lorenzobettini.it
1219 http://www.gnu.org/software/src-highlite -->
1220 <pre><tt>convert<span style="color: #990000">,</span> ratio<span style="color: #990000">,</span> safe <span style="color: #990000">=</span> cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_sparse_array</span></span><span style="color: #990000">([</span>convert<span style="color: #990000">[,</span> ratio<span style="color: #990000">[,</span> safe<span style="color: #990000">]]])</span>
1221 <span style="font-style: italic"><span style="color: #9A1900">-- "convert" must be a boolean. Default: false.</span></span>
1222 <span style="font-style: italic"><span style="color: #9A1900">-- "ratio" must be a positive integer. Default: 2.</span></span>
1223 <span style="font-style: italic"><span style="color: #9A1900">-- "safe" must be a positive integer. Default: 10.</span></span></tt></pre></div></div>
1224 <div class="paragraph"><p>Lua CJSON classifies a Lua table into one of three kinds when encoding a
1225 JSON array. This is determined by the number of values missing from the
1226 Lua array as follows:</p></div>
1227 <div class="dlist"><dl>
1228 <dt class="hdlist1">
1229 Normal
1230 </dt>
1231 <dd>
1232 <p>
1233 All values are available.
1234 </p>
1235 </dd>
1236 <dt class="hdlist1">
1237 Sparse
1238 </dt>
1239 <dd>
1240 <p>
1241 At least 1 value is missing.
1242 </p>
1243 </dd>
1244 <dt class="hdlist1">
1245 Excessively sparse
1246 </dt>
1247 <dd>
1248 <p>
1249 The number of values missing exceeds the configured
1250 ratio.
1251 </p>
1252 </dd>
1253 </dl></div>
1254 <div class="paragraph"><p>Lua CJSON encodes sparse Lua arrays as JSON arrays using JSON <tt>null</tt> for
1255 the missing entries.</p></div>
1256 <div class="paragraph"><p>An array is excessively sparse when all the following conditions are
1257 met:</p></div>
1258 <div class="ulist"><ul>
1259 <li>
1260 <p>
1261 <tt>ratio</tt> &gt; <tt>0</tt>
1262 </p>
1263 </li>
1264 <li>
1265 <p>
1266 <em>maximum_index</em> &gt; <tt>safe</tt>
1267 </p>
1268 </li>
1269 <li>
1270 <p>
1271 <em>maximum_index</em> &gt; <em>item_count</em> * <tt>ratio</tt>
1272 </p>
1273 </li>
1274 </ul></div>
1275 <div class="paragraph"><p>Lua CJSON will never consider an array to be <em>excessively sparse</em> when
1276 <tt>ratio</tt> = <tt>0</tt>. The <tt>safe</tt> limit ensures that small Lua arrays are always
1277 encoded as sparse arrays.</p></div>
1278 <div class="paragraph"><p>By default, attempting to encode an <em>excessively sparse</em> array will
1279 generate an error. If <tt>convert</tt> is set to <tt>true</tt>, <em>excessively sparse</em>
1280 arrays will be converted to a JSON object.</p></div>
1281 <div class="paragraph"><p>The current settings are always returned. A particular setting is only
1282 changed when the argument is provided (non-<tt>nil</tt>).</p></div>
1283 <div class="exampleblock">
1284 <div class="title">Example: Encoding a sparse array</div>
1285 <div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4
1286 by Lorenzo Bettini
1287 http://www.lorenzobettini.it
1288 http://www.gnu.org/software/src-highlite -->
1289 <pre><tt>cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode</span></span><span style="color: #990000">(</span><span style="color: #FF0000">{</span> <span style="color: #990000">[</span><span style="color: #993399">3</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"data"</span> <span style="color: #FF0000">}</span><span style="color: #990000">)</span>
1290 <span style="font-style: italic"><span style="color: #9A1900">-- Returns: '[null,null,"data"]'</span></span></tt></pre></div></div>
1291 <div class="exampleblock">
1292 <div class="title">Example: Enabling conversion to a JSON object</div>
1293 <div class="exampleblock-content"><!-- Generator: GNU source-highlight 3.1.4
1294 by Lorenzo Bettini
1295 http://www.lorenzobettini.it
1296 http://www.gnu.org/software/src-highlite -->
1297 <pre><tt>cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode_sparse_array</span></span><span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">true</span></span><span style="color: #990000">)</span>
1298 cjson<span style="color: #990000">.</span><span style="font-weight: bold"><span style="color: #000000">encode</span></span><span style="color: #990000">(</span><span style="color: #FF0000">{</span> <span style="color: #990000">[</span><span style="color: #993399">1000</span><span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"excessively sparse"</span> <span style="color: #FF0000">}</span><span style="color: #990000">)</span>
1299 <span style="font-style: italic"><span style="color: #9A1900">-- Returns: '{"1000":"excessively sparse"}'</span></span></tt></pre></div></div>
1300 </div>
1301 <h2 id="_api_variables">4. API (Variables)</h2>
1302 <div class="sectionbody">
1303 <h3 id="_name">4.1. _NAME</h3><div style="clear:left"></div>
1304 <div class="paragraph"><p>The name of the Lua CJSON module (<tt>"cjson"</tt>).</p></div>
1305 <h3 id="_version">4.2. _VERSION</h3><div style="clear:left"></div>
1306 <div class="paragraph"><p>The version number of the Lua CJSON module (<tt>"2.1.0"</tt>).</p></div>
1307 <h3 id="_null">4.3. null</h3><div style="clear:left"></div>
1308 <div class="paragraph"><p>Lua CJSON decodes JSON <tt>null</tt> as a Lua <tt>lightuserdata</tt> NULL pointer.
1309 <tt>cjson.null</tt> is provided for comparison.</p></div>
1310 </div>
1311 <h2 id="_references">5. References</h2>
1312 <div class="sectionbody">
1313 <div class="ulist"><ul>
1314 <li>
1315 <p>
1316 <a href="http://tools.ietf.org/html/rfc4627">RFC 4627</a>
1317 </p>
1318 </li>
1319 <li>
1320 <p>
1321 <a href="http://www.json.org/">JSON website</a>
1322 </p>
1323 </li>
1324 </ul></div>
1325 </div>
1326 <div id="footer">
1327 <div id="footer-text">
1328 Last updated 2012-03-01 22:52:58 CST
1329 </div>
1330 </div>
1331 </body>
1332 </html>