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.31 by root, Wed Apr 11 12:23:02 2007 UTC vs.
Revision 1.38 by root, Wed Jun 6 18:16:52 2007 UTC

… …
86package JSON::XS; 86package JSON::XS;
87 87
88use strict; 88use strict;
89 89
90BEGIN { 90BEGIN {
91 our $VERSION = '1.12'; 91 our $VERSION = '1.23';
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
… …
345 374
346JSON numbers and strings become simple Perl scalars. JSON arrays become 375JSON numbers and strings become simple Perl scalars. JSON arrays become
347Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 376Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
348C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. 377C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
349 378
379=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
380
381This works like the C<decode> method, but instead of raising an exception
382when there is trailing garbage after the first JSON object, it will
383silently stop parsing there and return the number of characters consumed
384so far.
385
386This is useful if your JSON texts are not delimited by an outer protocol
387(which is not the brightest thing to do in the first place) and you need
388to know where the JSON text ends.
389
390 JSON::XS->new->decode_prefix ("[1] the tail")
391 => ([], 3)
392
350=back 393=back
351 394
352 395
353=head1 MAPPING 396=head1 MAPPING
354 397
… …
569It seems that JSON::XS is surprisingly fast, as shown in the following 612It seems that JSON::XS is surprisingly fast, as shown in the following
570tables. They have been generated with the help of the C<eg/bench> program 613tables. They have been generated with the help of the C<eg/bench> program
571in the JSON::XS distribution, to make it easy to compare on your own 614in the JSON::XS distribution, to make it easy to compare on your own
572system. 615system.
573 616
574First comes a comparison between various modules using a very short JSON 617First comes a comparison between various modules using a very short
575string: 618single-line JSON string:
576 619
577 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} 620 {"method": "handleMessage", "params": ["user1", "we were just talking"], \
621 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}
578 622
579It shows the number of encodes/decodes per second (JSON::XS uses the 623It shows the number of encodes/decodes per second (JSON::XS uses the
580functional interface, while JSON::XS/2 uses the OO interface with 624functional interface, while JSON::XS/2 uses the OO interface with
581pretty-printing and hashkey sorting enabled). Higher is better: 625pretty-printing and hashkey sorting enabled). Higher is better:
582 626
583 module | encode | decode | 627 module | encode | decode |
584 -----------|------------|------------| 628 -----------|------------|------------|
585 JSON | 11488.516 | 7823.035 | 629 JSON | 7645.468 | 4208.613 |
586 JSON::DWIW | 94708.054 | 129094.260 | 630 JSON::DWIW | 68534.379 | 79437.576 |
587 JSON::PC | 63884.157 | 128528.212 | 631 JSON::PC | 65948.176 | 78251.940 |
588 JSON::Syck | 34898.677 | 42096.911 | 632 JSON::Syck | 23379.621 | 28416.694 |
589 JSON::XS | 654027.064 | 396423.669 | 633 JSON::XS | 388361.481 | 199728.762 |
590 JSON::XS/2 | 371564.190 | 371725.613 | 634 JSON::XS/2 | 218453.333 | 192399.266 |
635 JSON::XS/3 | 338250.323 | 192399.266 |
636 Storable | 15732.573 | 28571.553 |
591 -----------+------------+------------+ 637 -----------+------------+------------+
592 638
593That is, JSON::XS is more than six times faster than JSON::DWIW on 639That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
594encoding, more than three times faster on decoding, and about thirty times 640about three times faster on decoding, and over fourty times faster
595faster than JSON, even with pretty-printing and key sorting. 641than JSON, even with pretty-printing and key sorting. It also compares
642favourably to Storable for small amounts of data.
596 643
597Using a longer test string (roughly 18KB, generated from Yahoo! Locals 644Using a longer test string (roughly 18KB, generated from Yahoo! Locals
598search API (http://nanoref.com/yahooapis/mgPdGg): 645search API (http://nanoref.com/yahooapis/mgPdGg):
599 646
600 module | encode | decode | 647 module | encode | decode |
601 -----------|------------|------------| 648 -----------|------------|------------|
602 JSON | 273.023 | 44.674 | 649 JSON | 254.685 | 37.665 |
603 JSON::DWIW | 1089.383 | 1145.704 | 650 JSON::DWIW | 1014.244 | 1087.678 |
604 JSON::PC | 3097.419 | 2393.921 | 651 JSON::PC | 3602.116 | 2307.352 |
605 JSON::Syck | 514.060 | 843.053 | 652 JSON::Syck | 558.035 | 776.263 |
606 JSON::XS | 6479.668 | 3636.364 | 653 JSON::XS | 5747.196 | 3543.684 |
607 JSON::XS/2 | 3774.221 | 3599.124 | 654 JSON::XS/2 | 3968.121 | 3589.170 |
655 JSON::XS/3 | 6105.246 | 3561.134 |
656 Storable | 4456.337 | 5320.020 |
608 -----------+------------+------------+ 657 -----------+------------+------------+
609 658
610Again, JSON::XS leads by far. 659Again, JSON::XS leads by far.
611 660
612On large strings containing lots of high unicode characters, some modules 661On large strings containing lots of high unicode characters, some modules

Diff Legend

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