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.25 by root, Thu Mar 29 02:45:49 2007 UTC vs.
Revision 1.33 by root, Wed May 9 16:10:37 2007 UTC

… …
86package JSON::XS; 86package JSON::XS;
87 87
88use strict; 88use strict;
89 89
90BEGIN { 90BEGIN {
91 our $VERSION = '1.0'; 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 or other flags. This results
163and more compact format. 165in a faster and more compact format.
166
167The main use for this flag is to produce JSON texts that can be
168transmitted over a 7-bit channel, as the encoded JSON texts will not
169contain any 8 bit characters.
164 170
165 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 171 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
166 => ["\ud801\udc01"] 172 => ["\ud801\udc01"]
173
174=item $json = $json->latin1 ([$enable])
175
176If C<$enable> is true (or missing), then the C<encode> method will encode
177the resulting JSON text as latin1 (or iso-8859-1), escaping any characters
178outside the code range C<0..255>. The resulting string can be treated as a
179latin1-encoded JSON text or a native unicode string. The C<decode> method
180will not be affected in any way by this flag, as C<decode> by default
181expects unicode, which is a strict superset of latin1.
182
183If C<$enable> is false, then the C<encode> method will not escape Unicode
184characters unless required by the JSON syntax or other flags.
185
186The main use for this flag is efficiently encoding binary data as JSON
187text, as most octets will not be escaped, resulting in a smaller encoded
188size. The disadvantage is that the resulting JSON text is encoded
189in latin1 (and must correctly be treated as such when storing and
190transfering), a rare encoding for JSON. It is therefore most useful when
191you want to store data structures known to contain binary data efficiently
192in files or databases, not when talking to other JSON encoders/decoders.
193
194 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
195 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
167 196
168=item $json = $json->utf8 ([$enable]) 197=item $json = $json->utf8 ([$enable])
169 198
170If C<$enable> is true (or missing), then the C<encode> method will encode 199If C<$enable> is true (or missing), then the C<encode> method will encode
171the JSON result into UTF-8, as required by many protocols, while the 200the JSON result into UTF-8, as required by many protocols, while the
… …
309strings that look like integers or floats into integers or floats 338strings that look like integers or floats into integers or floats
310internally (there is no difference on the Perl level), saving space. 339internally (there is no difference on the Perl level), saving space.
311 340
312=item $json = $json->max_depth ([$maximum_nesting_depth]) 341=item $json = $json->max_depth ([$maximum_nesting_depth])
313 342
314Sets the maximum nesting level (default C<4096>) accepted while encoding 343Sets the maximum nesting level (default C<512>) accepted while encoding
315or decoding. If the JSON text or Perl data structure has an equal or 344or decoding. If the JSON text or Perl data structure has an equal or
316higher nesting level then this limit, then the encoder and decoder will 345higher nesting level then this limit, then the encoder and decoder will
317stop and croak at that point. 346stop and croak at that point.
318 347
319Nesting level is defined by number of hash- or arrayrefs that the encoder 348Nesting level is defined by number of hash- or arrayrefs that the encoder
… …
473 $x *= 1; # same thing, the choise is yours. 502 $x *= 1; # same thing, the choise is yours.
474 503
475You can not currently output JSON booleans or force the type in other, 504You can not currently output JSON booleans or force the type in other,
476less obscure, ways. Tell me if you need this capability. 505less obscure, ways. Tell me if you need this capability.
477 506
478=item circular data structures
479
480Those will be encoded until memory or stackspace runs out.
481
482=back 507=back
483 508
484 509
485=head1 COMPARISON 510=head1 COMPARISON
486 511
… …
636usually a good indication of the size of the resources required to decode 661usually a good indication of the size of the resources required to decode
637it into a Perl structure. 662it into a Perl structure.
638 663
639Third, JSON::XS recurses using the C stack when decoding objects and 664Third, JSON::XS recurses using the C stack when decoding objects and
640arrays. The C stack is a limited resource: for instance, on my amd64 665arrays. The C stack is a limited resource: for instance, on my amd64
641machine with 8MB of stack size I can decode around 180k nested arrays 666machine with 8MB of stack size I can decode around 180k nested arrays but
642but only 14k nested JSON objects. If that is exceeded, the program 667only 14k nested JSON objects (due to perl itself recursing deeply on croak
643crashes. Thats why the default nesting limit is set to 4096. If your 668to free the temporary). If that is exceeded, the program crashes. to be
669conservative, the default nesting limit is set to 512. If your process
644process has a smaller stack, you should adjust this setting accordingly 670has a smaller stack, you should adjust this setting accordingly with the
645with the C<max_depth> method. 671C<max_depth> method.
646 672
647And last but least, something else could bomb you that I forgot to think 673And last but least, something else could bomb you that I forgot to think
648of. In that case, you get to keep the pieces. I am alway sopen for hints, 674of. In that case, you get to keep the pieces. I am always open for hints,
649though... 675though...
650 676
651 677
652=head1 BUGS 678=head1 BUGS
653 679

Diff Legend

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