ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.23 by root, Sun Mar 25 21:19:13 2007 UTC vs.
Revision 1.32 by root, Thu Apr 12 07:25:29 2007 UTC

… …
86package JSON::XS; 86package JSON::XS;
87 87
88use strict; 88use strict;
89 89
90BEGIN { 90BEGIN {
91 our $VERSION = '0.8'; 91 our $VERSION = '1.12';
92 our @ISA = qw(Exporter); 92 our @ISA = qw(Exporter);
93 93
94 our @EXPORT = qw(to_json from_json objToJson jsonToObj); 94 our @EXPORT = qw(to_json from_json objToJson jsonToObj);
95 require Exporter; 95 require Exporter;
96 96
… …
154 154
155If C<$enable> is true (or missing), then the C<encode> method will not 155If C<$enable> is true (or missing), then the C<encode> method will not
156generate characters outside the code range C<0..127> (which is ASCII). Any 156generate characters outside the code range C<0..127> (which is ASCII). Any
157unicode characters outside that range will be escaped using either a 157unicode characters outside that range will be escaped using either a
158single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, 158single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
159as per RFC4627. 159as per RFC4627. The resulting encoded JSON text can be treated as a native
160unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
161or any other superset of ASCII.
160 162
161If C<$enable> is false, then the C<encode> method will not escape Unicode 163If C<$enable> is false, then the C<encode> method will not escape Unicode
162characters unless required by the JSON syntax. This results in a faster 164characters unless required by the JSON syntax. This results in a faster
163and more compact format. 165and more compact format.
164 166
… …
284 => "Hello, World!" 286 => "Hello, World!"
285 287
286=item $json = $json->shrink ([$enable]) 288=item $json = $json->shrink ([$enable])
287 289
288Perl usually over-allocates memory a bit when allocating space for 290Perl usually over-allocates memory a bit when allocating space for
289strings. This flag optionally resizes strings generated by either 291strings. This flag optionally resizes strings generated by either
290C<encode> or C<decode> to their minimum size possible. This can save 292C<encode> or C<decode> to their minimum size possible. This can save
291memory when your JSON texts are either very very long or you have many 293memory when your JSON texts are either very very long or you have many
292short strings. It will also try to downgrade any strings to octet-form 294short strings. It will also try to downgrade any strings to octet-form
293if possible: perl stores strings internally either in an encoding called 295if possible: perl stores strings internally either in an encoding called
294UTF-X or in octet-form. The latter cannot store everything but uses less 296UTF-X or in octet-form. The latter cannot store everything but uses less
295space in general. 297space in general (and some buggy Perl or C code might even rely on that
298internal representation being used).
296 299
300The actual definition of what shrink does might change in future versions,
301but it will always try to save space at the expense of time.
302
297If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit, 303If C<$enable> is true (or missing), the string returned by C<encode> will
298while all strings generated by C<decode> will also be shrunk-to-fit. 304be shrunk-to-fit, while all strings generated by C<decode> will also be
305shrunk-to-fit.
299 306
300If C<$enable> is false, then the normal perl allocation algorithms are used. 307If C<$enable> is false, then the normal perl allocation algorithms are used.
301If you work with your data, then this is likely to be faster. 308If you work with your data, then this is likely to be faster.
302 309
303In the future, this setting might control other things, such as converting 310In the future, this setting might control other things, such as converting
304strings that look like integers or floats into integers or floats 311strings that look like integers or floats into integers or floats
305internally (there is no difference on the Perl level), saving space. 312internally (there is no difference on the Perl level), saving space.
306 313
307=item $json = $json->max_depth ([$maximum_nesting_depth]) 314=item $json = $json->max_depth ([$maximum_nesting_depth])
308 315
309Sets the maximum nesting level (default C<8192>) accepted while encoding 316Sets the maximum nesting level (default C<512>) accepted while encoding
310or decoding. If the JSON text or Perl data structure has an equal or 317or decoding. If the JSON text or Perl data structure has an equal or
311higher nesting level then this limit, then the encoder and decoder will 318higher nesting level then this limit, then the encoder and decoder will
312stop and croak at that point. 319stop and croak at that point.
313 320
314Nesting level is defined by number of hash- or arrayrefs that the encoder 321Nesting level is defined by number of hash- or arrayrefs that the encoder
… …
405=over 4 412=over 4
406 413
407=item hash references 414=item hash references
408 415
409Perl hash references become JSON objects. As there is no inherent ordering 416Perl hash references become JSON objects. As there is no inherent ordering
410in hash keys, they will usually be encoded in a pseudo-random order that 417in hash keys (or JSON objects), they will usually be encoded in a
411can change between runs of the same program but stays generally the same 418pseudo-random order that can change between runs of the same program but
412within a single run of a program. JSON::XS can optionally sort the hash 419stays generally the same within a single run of a program. JSON::XS can
413keys (determined by the I<canonical> flag), so the same datastructure 420optionally sort the hash keys (determined by the I<canonical> flag), so
414will serialise to the same JSON text (given same settings and version of 421the same datastructure will serialise to the same JSON text (given same
415JSON::XS), but this incurs a runtime overhead. 422settings and version of JSON::XS), but this incurs a runtime overhead
423and is only rarely useful, e.g. when you want to compare some JSON text
424against another for equality.
416 425
417=item array references 426=item array references
418 427
419Perl array references become JSON arrays. 428Perl array references become JSON arrays.
429
430=item other references
431
432Other unblessed references are generally not allowed and will cause an
433exception to be thrown, except for references to the integers C<0> and
434C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
435also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
436
437 to_json [\0,JSON::XS::true] # yields [false,true]
420 438
421=item blessed objects 439=item blessed objects
422 440
423Blessed objects are not allowed. JSON::XS currently tries to encode their 441Blessed objects are not allowed. JSON::XS currently tries to encode their
424underlying representation (hash- or arrayref), but this behaviour might 442underlying representation (hash- or arrayref), but this behaviour might
… …
456 $x += 0; # numify it, ensuring it will be dumped as a number 474 $x += 0; # numify it, ensuring it will be dumped as a number
457 $x *= 1; # same thing, the choise is yours. 475 $x *= 1; # same thing, the choise is yours.
458 476
459You can not currently output JSON booleans or force the type in other, 477You can not currently output JSON booleans or force the type in other,
460less obscure, ways. Tell me if you need this capability. 478less obscure, ways. Tell me if you need this capability.
461
462=item circular data structures
463
464Those will be encoded until memory or stackspace runs out.
465 479
466=back 480=back
467 481
468 482
469=head1 COMPARISON 483=head1 COMPARISON
… …
620usually a good indication of the size of the resources required to decode 634usually a good indication of the size of the resources required to decode
621it into a Perl structure. 635it into a Perl structure.
622 636
623Third, JSON::XS recurses using the C stack when decoding objects and 637Third, JSON::XS recurses using the C stack when decoding objects and
624arrays. The C stack is a limited resource: for instance, on my amd64 638arrays. The C stack is a limited resource: for instance, on my amd64
625machine with 8MB of stack size I can decode around 180k nested arrays 639machine with 8MB of stack size I can decode around 180k nested arrays but
626but only 14k nested JSON objects. If that is exceeded, the program 640only 14k nested JSON objects (due to perl itself recursing deeply on croak
641to free the temporary). If that is exceeded, the program crashes. to be
627crashes. Thats why the default nesting limit is set to 8192. If your 642conservative, the default nesting limit is set to 512. If your process
628process has a smaller stack, you should adjust this setting accordingly 643has a smaller stack, you should adjust this setting accordingly with the
629with the C<max_depth> method. 644C<max_depth> method.
630 645
631And last but least, something else could bomb you that I forgot to think 646And last but least, something else could bomb you that I forgot to think
632of. In that case, you get to keep the pieces. I am alway sopen for hints, 647of. In that case, you get to keep the pieces. I am always open for hints,
633though... 648though...
634 649
635 650
636=head1 BUGS 651=head1 BUGS
637 652
… …
640still relatively early in its development. If you keep reporting bugs they 655still relatively early in its development. If you keep reporting bugs they
641will be fixed swiftly, though. 656will be fixed swiftly, though.
642 657
643=cut 658=cut
644 659
660sub true() { \1 }
661sub false() { \0 }
662
6451; 6631;
646 664
647=head1 AUTHOR 665=head1 AUTHOR
648 666
649 Marc Lehmann <schmorp@schmorp.de> 667 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines