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.25 by root, Thu Mar 29 02:45:49 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.0';
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
… …
284 => "Hello, World!" 284 => "Hello, World!"
285 285
286=item $json = $json->shrink ([$enable]) 286=item $json = $json->shrink ([$enable])
287 287
288Perl usually over-allocates memory a bit when allocating space for 288Perl usually over-allocates memory a bit when allocating space for
289strings. This flag optionally resizes strings generated by either 289strings. This flag optionally resizes strings generated by either
290C<encode> or C<decode> to their minimum size possible. This can save 290C<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 291memory 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 292short strings. It will also try to downgrade any strings to octet-form
293if possible: perl stores strings internally either in an encoding called 293if possible: perl stores strings internally either in an encoding called
294UTF-X or in octet-form. The latter cannot store everything but uses less 294UTF-X or in octet-form. The latter cannot store everything but uses less
295space in general. 295space in general (and some buggy Perl or C code might even rely on that
296internal representation being used).
296 297
298The actual definition of what shrink does might change in future versions,
299but it will always try to save space at the expense of time.
300
297If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit, 301If 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. 302be shrunk-to-fit, while all strings generated by C<decode> will also be
303shrunk-to-fit.
299 304
300If C<$enable> is false, then the normal perl allocation algorithms are used. 305If 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. 306If you work with your data, then this is likely to be faster.
302 307
303In the future, this setting might control other things, such as converting 308In the future, this setting might control other things, such as converting
304strings that look like integers or floats into integers or floats 309strings that look like integers or floats into integers or floats
305internally (there is no difference on the Perl level), saving space. 310internally (there is no difference on the Perl level), saving space.
306 311
307=item $json = $json->max_depth ([$maximum_nesting_depth]) 312=item $json = $json->max_depth ([$maximum_nesting_depth])
308 313
309Sets the maximum nesting level (default C<8192>) accepted while encoding 314Sets the maximum nesting level (default C<4096>) accepted while encoding
310or decoding. If the JSON text or Perl data structure has an equal or 315or 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 316higher nesting level then this limit, then the encoder and decoder will
312stop and croak at that point. 317stop and croak at that point.
313 318
314Nesting level is defined by number of hash- or arrayrefs that the encoder 319Nesting level is defined by number of hash- or arrayrefs that the encoder
… …
405=over 4 410=over 4
406 411
407=item hash references 412=item hash references
408 413
409Perl hash references become JSON objects. As there is no inherent ordering 414Perl 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 415in 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 416pseudo-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 417stays generally the same within a single run of a program. JSON::XS can
413keys (determined by the I<canonical> flag), so the same datastructure 418optionally sort the hash keys (determined by the I<canonical> flag), so
414will serialise to the same JSON text (given same settings and version of 419the same datastructure will serialise to the same JSON text (given same
415JSON::XS), but this incurs a runtime overhead. 420settings and version of JSON::XS), but this incurs a runtime overhead
421and is only rarely useful, e.g. when you want to compare some JSON text
422against another for equality.
416 423
417=item array references 424=item array references
418 425
419Perl array references become JSON arrays. 426Perl array references become JSON arrays.
427
428=item other references
429
430Other unblessed references are generally not allowed and will cause an
431exception to be thrown, except for references to the integers C<0> and
432C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
433also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
434
435 to_json [\0,JSON::XS::true] # yields [false,true]
420 436
421=item blessed objects 437=item blessed objects
422 438
423Blessed objects are not allowed. JSON::XS currently tries to encode their 439Blessed objects are not allowed. JSON::XS currently tries to encode their
424underlying representation (hash- or arrayref), but this behaviour might 440underlying representation (hash- or arrayref), but this behaviour might
… …
622 638
623Third, JSON::XS recurses using the C stack when decoding objects and 639Third, JSON::XS recurses using the C stack when decoding objects and
624arrays. The C stack is a limited resource: for instance, on my amd64 640arrays. 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 641machine with 8MB of stack size I can decode around 180k nested arrays
626but only 14k nested JSON objects. If that is exceeded, the program 642but only 14k nested JSON objects. If that is exceeded, the program
627crashes. Thats why the default nesting limit is set to 8192. If your 643crashes. Thats why the default nesting limit is set to 4096. If your
628process has a smaller stack, you should adjust this setting accordingly 644process has a smaller stack, you should adjust this setting accordingly
629with the C<max_depth> method. 645with the C<max_depth> method.
630 646
631And last but least, something else could bomb you that I forgot to think 647And 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, 648of. In that case, you get to keep the pieces. I am alway sopen for hints,
… …
640still relatively early in its development. If you keep reporting bugs they 656still relatively early in its development. If you keep reporting bugs they
641will be fixed swiftly, though. 657will be fixed swiftly, though.
642 658
643=cut 659=cut
644 660
661sub true() { \1 }
662sub false() { \0 }
663
6451; 6641;
646 665
647=head1 AUTHOR 666=head1 AUTHOR
648 667
649 Marc Lehmann <schmorp@schmorp.de> 668 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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