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.33 by root, Wed May 9 16:10:37 2007 UTC vs.
Revision 1.40 by root, Mon Jun 11 03:42:57 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
… …
374 374
375JSON numbers and strings become simple Perl scalars. JSON arrays become 375JSON numbers and strings become simple Perl scalars. JSON arrays become
376Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 376Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
377C<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>.
378 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
379=back 393=back
380 394
381 395
382=head1 MAPPING 396=head1 MAPPING
383 397
… …
387(what you put in comes out as something equivalent). 401(what you put in comes out as something equivalent).
388 402
389For the more enlightened: note that in the following descriptions, 403For the more enlightened: note that in the following descriptions,
390lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 404lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
391refers to the abstract Perl language itself. 405refers to the abstract Perl language itself.
406
392 407
393=head2 JSON -> PERL 408=head2 JSON -> PERL
394 409
395=over 4 410=over 4
396 411
… …
427=item null 442=item null
428 443
429A JSON null atom becomes C<undef> in Perl. 444A JSON null atom becomes C<undef> in Perl.
430 445
431=back 446=back
447
432 448
433=head2 PERL -> JSON 449=head2 PERL -> JSON
434 450
435The 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
436truly 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
… …
591 607
592Does not check input for validity. 608Does not check input for validity.
593 609
594=back 610=back
595 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 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 object key lengths
627that JSON doesn't have, so you should make sure that your hash keys are
628noticably shorter than 1024 characters.
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.
633
634
596=head2 SPEED 635=head2 SPEED
597 636
598It seems that JSON::XS is surprisingly fast, as shown in the following 637It seems that JSON::XS is surprisingly fast, as shown in the following
599tables. They have been generated with the help of the C<eg/bench> program 638tables. They have been generated with the help of the C<eg/bench> program
600in the JSON::XS distribution, to make it easy to compare on your own 639in the JSON::XS distribution, to make it easy to compare on your own
601system. 640system.
602 641
603First comes a comparison between various modules using a very short JSON 642First comes a comparison between various modules using a very short
604string: 643single-line JSON string:
605 644
606 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} 645 {"method": "handleMessage", "params": ["user1", "we were just talking"], \
646 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}
607 647
608It shows the number of encodes/decodes per second (JSON::XS uses the 648It shows the number of encodes/decodes per second (JSON::XS uses
609functional interface, while JSON::XS/2 uses the OO interface with 649the functional interface, while JSON::XS/2 uses the OO interface
610pretty-printing and hashkey sorting enabled). Higher is better: 650with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
651shrink). Higher is better:
611 652
612 module | encode | decode | 653 module | encode | decode |
613 -----------|------------|------------| 654 -----------|------------|------------|
614 JSON | 11488.516 | 7823.035 | 655 JSON | 7645.468 | 4208.613 |
615 JSON::DWIW | 94708.054 | 129094.260 | 656 JSON::DWIW | 40721.398 | 77101.176 |
616 JSON::PC | 63884.157 | 128528.212 | 657 JSON::PC | 65948.176 | 78251.940 |
617 JSON::Syck | 34898.677 | 42096.911 | 658 JSON::Syck | 22844.793 | 26479.192 |
618 JSON::XS | 654027.064 | 396423.669 | 659 JSON::XS | 388361.481 | 199728.762 |
619 JSON::XS/2 | 371564.190 | 371725.613 | 660 JSON::XS/2 | 218453.333 | 192399.266 |
661 JSON::XS/3 | 338250.323 | 192399.266 |
662 Storable | 15779.925 | 14169.946 |
620 -----------+------------+------------+ 663 -----------+------------+------------+
621 664
622That is, JSON::XS is more than six times faster than JSON::DWIW on 665That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
623encoding, more than three times faster on decoding, and about thirty times 666about three times faster on decoding, and over fourty times faster
624faster than JSON, even with pretty-printing and key sorting. 667than JSON, even with pretty-printing and key sorting. It also compares
668favourably to Storable for small amounts of data.
625 669
626Using a longer test string (roughly 18KB, generated from Yahoo! Locals 670Using a longer test string (roughly 18KB, generated from Yahoo! Locals
627search API (http://nanoref.com/yahooapis/mgPdGg): 671search API (http://nanoref.com/yahooapis/mgPdGg):
628 672
629 module | encode | decode | 673 module | encode | decode |
630 -----------|------------|------------| 674 -----------|------------|------------|
631 JSON | 273.023 | 44.674 | 675 JSON | 254.685 | 37.665 |
632 JSON::DWIW | 1089.383 | 1145.704 | 676 JSON::DWIW | 843.343 | 1049.731 |
633 JSON::PC | 3097.419 | 2393.921 | 677 JSON::PC | 3602.116 | 2307.352 |
634 JSON::Syck | 514.060 | 843.053 | 678 JSON::Syck | 505.107 | 787.899 |
635 JSON::XS | 6479.668 | 3636.364 | 679 JSON::XS | 5747.196 | 3690.220 |
636 JSON::XS/2 | 3774.221 | 3599.124 | 680 JSON::XS/2 | 3968.121 | 3676.634 |
681 JSON::XS/3 | 6105.246 | 3662.508 |
682 Storable | 4417.337 | 5285.161 |
637 -----------+------------+------------+ 683 -----------+------------+------------+
638 684
639Again, JSON::XS leads by far. 685Again, JSON::XS leads by far (except for Storable which non-surprisingly
686decodes faster).
640 687
641On large strings containing lots of high unicode characters, some modules 688On large strings containing lots of high unicode characters, some modules
642(such as JSON::PC) seem to decode faster than JSON::XS, but the result 689(such as JSON::PC) seem to decode faster than JSON::XS, but the result
643will be broken due to missing (or wrong) unicode handling. Others refuse 690will be broken due to missing (or wrong) unicode handling. Others refuse
644to decode or encode properly, so it was impossible to prepare a fair 691to decode or encode properly, so it was impossible to prepare a fair

Diff Legend

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