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.32 by root, Thu Apr 12 07:25:29 2007 UTC vs.
Revision 1.41 by root, Mon Jun 11 03:45:26 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.24';
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
… …
159as per RFC4627. The resulting encoded JSON text can be treated as a native 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, 160unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
161or any other superset of ASCII. 161or any other superset of ASCII.
162 162
163If 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
164characters unless required by the JSON syntax. This results in a faster 164characters unless required by the JSON syntax or other flags. This results
165and 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.
166 170
167 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 171 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
168 => ["\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)
169 196
170=item $json = $json->utf8 ([$enable]) 197=item $json = $json->utf8 ([$enable])
171 198
172If 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
173the 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
… …
347 374
348JSON numbers and strings become simple Perl scalars. JSON arrays become 375JSON numbers and strings become simple Perl scalars. JSON arrays become
349Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 376Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
350C<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>.
351 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
352=back 393=back
353 394
354 395
355=head1 MAPPING 396=head1 MAPPING
356 397
… …
360(what you put in comes out as something equivalent). 401(what you put in comes out as something equivalent).
361 402
362For the more enlightened: note that in the following descriptions, 403For the more enlightened: note that in the following descriptions,
363lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 404lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
364refers to the abstract Perl language itself. 405refers to the abstract Perl language itself.
406
365 407
366=head2 JSON -> PERL 408=head2 JSON -> PERL
367 409
368=over 4 410=over 4
369 411
… …
400=item null 442=item null
401 443
402A JSON null atom becomes C<undef> in Perl. 444A JSON null atom becomes C<undef> in Perl.
403 445
404=back 446=back
447
405 448
406=head2 PERL -> JSON 449=head2 PERL -> JSON
407 450
408The mapping from Perl to JSON is slightly more difficult, as Perl is a 451The mapping from Perl to JSON is slightly more difficult, as Perl is a
409truly typeless language, so we can only guess which JSON type is meant by 452truly typeless language, so we can only guess which JSON type is meant by
… …
564 607
565Does not check input for validity. 608Does not check input for validity.
566 609
567=back 610=back
568 611
612
613=head2 JSON and YAML
614
615You often hear that JSON is a subset (or a close subset) of YAML. This is,
616however, a mass hysteria and very far from the truth. In general, there is
617no way to configure JSON::XS to output a data structure as valid YAML.
618
619If you really must use JSON::XS to generate YAML, you should use this
620algorithm (subject to change in future versions):
621
622 my $to_yaml = JSON::XS->new->utf8->space_after (1);
623 my $yaml = $to_yaml->encode ($ref) . "\n";
624
625This will usually generate JSON texts that also parse as valid
626YAML. Please note that YAML has hardcoded limits on (simple) object key
627lengths that JSON doesn't have, so you should make sure that your hash
628keys are noticably shorter than the 1024 characters YAML allows.
629
630There might be other incompatibilities that I am not aware of. In general
631you should not try to generate YAML with a JSON generator or vice versa,
632or try to parse JSON with a YAML parser or vice versa: chances are high
633that you will run into severe interoperability problems.
634
635
569=head2 SPEED 636=head2 SPEED
570 637
571It seems that JSON::XS is surprisingly fast, as shown in the following 638It seems that JSON::XS is surprisingly fast, as shown in the following
572tables. They have been generated with the help of the C<eg/bench> program 639tables. They have been generated with the help of the C<eg/bench> program
573in the JSON::XS distribution, to make it easy to compare on your own 640in the JSON::XS distribution, to make it easy to compare on your own
574system. 641system.
575 642
576First comes a comparison between various modules using a very short JSON 643First comes a comparison between various modules using a very short
577string: 644single-line JSON string:
578 645
579 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} 646 {"method": "handleMessage", "params": ["user1", "we were just talking"], \
647 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}
580 648
581It shows the number of encodes/decodes per second (JSON::XS uses the 649It shows the number of encodes/decodes per second (JSON::XS uses
582functional interface, while JSON::XS/2 uses the OO interface with 650the functional interface, while JSON::XS/2 uses the OO interface
583pretty-printing and hashkey sorting enabled). Higher is better: 651with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
652shrink). Higher is better:
584 653
585 module | encode | decode | 654 module | encode | decode |
586 -----------|------------|------------| 655 -----------|------------|------------|
587 JSON | 11488.516 | 7823.035 | 656 JSON | 7645.468 | 4208.613 |
588 JSON::DWIW | 94708.054 | 129094.260 | 657 JSON::DWIW | 40721.398 | 77101.176 |
589 JSON::PC | 63884.157 | 128528.212 | 658 JSON::PC | 65948.176 | 78251.940 |
590 JSON::Syck | 34898.677 | 42096.911 | 659 JSON::Syck | 22844.793 | 26479.192 |
591 JSON::XS | 654027.064 | 396423.669 | 660 JSON::XS | 388361.481 | 199728.762 |
592 JSON::XS/2 | 371564.190 | 371725.613 | 661 JSON::XS/2 | 218453.333 | 192399.266 |
662 JSON::XS/3 | 338250.323 | 192399.266 |
663 Storable | 15779.925 | 14169.946 |
593 -----------+------------+------------+ 664 -----------+------------+------------+
594 665
595That is, JSON::XS is more than six times faster than JSON::DWIW on 666That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
596encoding, more than three times faster on decoding, and about thirty times 667about three times faster on decoding, and over fourty times faster
597faster than JSON, even with pretty-printing and key sorting. 668than JSON, even with pretty-printing and key sorting. It also compares
669favourably to Storable for small amounts of data.
598 670
599Using a longer test string (roughly 18KB, generated from Yahoo! Locals 671Using a longer test string (roughly 18KB, generated from Yahoo! Locals
600search API (http://nanoref.com/yahooapis/mgPdGg): 672search API (http://nanoref.com/yahooapis/mgPdGg):
601 673
602 module | encode | decode | 674 module | encode | decode |
603 -----------|------------|------------| 675 -----------|------------|------------|
604 JSON | 273.023 | 44.674 | 676 JSON | 254.685 | 37.665 |
605 JSON::DWIW | 1089.383 | 1145.704 | 677 JSON::DWIW | 843.343 | 1049.731 |
606 JSON::PC | 3097.419 | 2393.921 | 678 JSON::PC | 3602.116 | 2307.352 |
607 JSON::Syck | 514.060 | 843.053 | 679 JSON::Syck | 505.107 | 787.899 |
608 JSON::XS | 6479.668 | 3636.364 | 680 JSON::XS | 5747.196 | 3690.220 |
609 JSON::XS/2 | 3774.221 | 3599.124 | 681 JSON::XS/2 | 3968.121 | 3676.634 |
682 JSON::XS/3 | 6105.246 | 3662.508 |
683 Storable | 4417.337 | 5285.161 |
610 -----------+------------+------------+ 684 -----------+------------+------------+
611 685
612Again, JSON::XS leads by far. 686Again, JSON::XS leads by far (except for Storable which non-surprisingly
687decodes faster).
613 688
614On large strings containing lots of high unicode characters, some modules 689On large strings containing lots of high unicode characters, some modules
615(such as JSON::PC) seem to decode faster than JSON::XS, but the result 690(such as JSON::PC) seem to decode faster than JSON::XS, but the result
616will be broken due to missing (or wrong) unicode handling. Others refuse 691will be broken due to missing (or wrong) unicode handling. Others refuse
617to decode or encode properly, so it was impossible to prepare a fair 692to decode or encode properly, so it was impossible to prepare a fair

Diff Legend

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