… | |
… | |
4 | |
4 | |
5 | =head1 SYNOPSIS |
5 | =head1 SYNOPSIS |
6 | |
6 | |
7 | use JSON::XS; |
7 | use JSON::XS; |
8 | |
8 | |
9 | # exported functions, croak on error |
9 | # exported functions, they croak on error |
|
|
10 | # and expect/generate UTF-8 |
10 | |
11 | |
11 | $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; |
12 | $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; |
12 | $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; |
13 | $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; |
13 | |
14 | |
|
|
15 | # objToJson and jsonToObj aliases to to_json and from_json |
|
|
16 | # are exported for compatibility to the JSON module, |
|
|
17 | # but should not be used in new code. |
|
|
18 | |
14 | # oo-interface |
19 | # OO-interface |
15 | |
20 | |
16 | $coder = JSON::XS->new->ascii->pretty->allow_nonref; |
21 | $coder = JSON::XS->new->ascii->pretty->allow_nonref; |
17 | $pretty_printed_unencoded = $coder->encode ($perl_scalar); |
22 | $pretty_printed_unencoded = $coder->encode ($perl_scalar); |
18 | $perl_scalar = $coder->decode ($unicode_json_text); |
23 | $perl_scalar = $coder->decode ($unicode_json_text); |
19 | |
24 | |
… | |
… | |
36 | |
41 | |
37 | =head2 FEATURES |
42 | =head2 FEATURES |
38 | |
43 | |
39 | =over 4 |
44 | =over 4 |
40 | |
45 | |
41 | =item * correct handling of unicode issues |
46 | =item * correct unicode handling |
42 | |
47 | |
43 | This module knows how to handle Unicode, and even documents how and when |
48 | This module knows how to handle Unicode, and even documents how and when |
44 | it does so. |
49 | it does so. |
45 | |
50 | |
46 | =item * round-trip integrity |
51 | =item * round-trip integrity |
47 | |
52 | |
48 | When you serialise a perl data structure using only datatypes supported |
53 | When you serialise a perl data structure using only datatypes supported |
49 | by JSON, the deserialised data structure is identical on the Perl level. |
54 | by JSON, the deserialised data structure is identical on the Perl level. |
50 | (e.g. the string "2.0" doesn't suddenly become "2"). |
55 | (e.g. the string "2.0" doesn't suddenly become "2" just because it looks |
|
|
56 | like a number). |
51 | |
57 | |
52 | =item * strict checking of JSON correctness |
58 | =item * strict checking of JSON correctness |
53 | |
59 | |
54 | There is no guessing, no generating of illegal JSON texts by default, |
60 | There is no guessing, no generating of illegal JSON texts by default, |
55 | and only JSON is accepted as input by default (the latter is a security |
61 | and only JSON is accepted as input by default (the latter is a security |
… | |
… | |
66 | interface. |
72 | interface. |
67 | |
73 | |
68 | =item * reasonably versatile output formats |
74 | =item * reasonably versatile output formats |
69 | |
75 | |
70 | You can choose between the most compact guarenteed single-line format |
76 | You can choose between the most compact guarenteed single-line format |
71 | possible (nice for simple line-based protocols), a pure-ascii format (for |
77 | possible (nice for simple line-based protocols), a pure-ascii format |
72 | when your transport is not 8-bit clean), or a pretty-printed format (for |
78 | (for when your transport is not 8-bit clean, still supports the whole |
73 | when you want to read that stuff). Or you can combine those features in |
79 | unicode range), or a pretty-printed format (for when you want to read that |
74 | whatever way you like. |
80 | stuff). Or you can combine those features in whatever way you like. |
75 | |
81 | |
76 | =back |
82 | =back |
77 | |
83 | |
78 | =cut |
84 | =cut |
79 | |
85 | |
80 | package JSON::XS; |
86 | package JSON::XS; |
81 | |
87 | |
|
|
88 | use strict; |
|
|
89 | |
82 | BEGIN { |
90 | BEGIN { |
83 | $VERSION = '0.31'; |
91 | our $VERSION = '0.8'; |
84 | @ISA = qw(Exporter); |
92 | our @ISA = qw(Exporter); |
85 | |
93 | |
86 | @EXPORT = qw(to_json from_json); |
94 | our @EXPORT = qw(to_json from_json objToJson jsonToObj); |
87 | require Exporter; |
95 | require Exporter; |
88 | |
96 | |
89 | require XSLoader; |
97 | require XSLoader; |
90 | XSLoader::load JSON::XS::, $VERSION; |
98 | XSLoader::load JSON::XS::, $VERSION; |
91 | } |
99 | } |
… | |
… | |
527 | tables. They have been generated with the help of the C<eg/bench> program |
535 | tables. They have been generated with the help of the C<eg/bench> program |
528 | in the JSON::XS distribution, to make it easy to compare on your own |
536 | in the JSON::XS distribution, to make it easy to compare on your own |
529 | system. |
537 | system. |
530 | |
538 | |
531 | First comes a comparison between various modules using a very short JSON |
539 | First comes a comparison between various modules using a very short JSON |
532 | string (83 bytes), showing the number of encodes/decodes per second |
540 | string: |
533 | (JSON::XS is the functional interface, while JSON::XS/2 is the OO |
541 | |
|
|
542 | {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} |
|
|
543 | |
|
|
544 | It shows the number of encodes/decodes per second (JSON::XS uses the |
|
|
545 | functional interface, while JSON::XS/2 uses the OO interface with |
534 | interface with pretty-printing and hashkey sorting enabled). Higher is |
546 | pretty-printing and hashkey sorting enabled). Higher is better: |
535 | better: |
|
|
536 | |
547 | |
537 | module | encode | decode | |
548 | module | encode | decode | |
538 | -----------|------------|------------| |
549 | -----------|------------|------------| |
539 | JSON | 14006 | 6820 | |
550 | JSON | 11488.516 | 7823.035 | |
540 | JSON::DWIW | 200937 | 120386 | |
551 | JSON::DWIW | 94708.054 | 129094.260 | |
541 | JSON::PC | 85065 | 129366 | |
552 | JSON::PC | 63884.157 | 128528.212 | |
542 | JSON::Syck | 59898 | 44232 | |
553 | JSON::Syck | 34898.677 | 42096.911 | |
543 | JSON::XS | 1171478 | 342435 | |
554 | JSON::XS | 654027.064 | 396423.669 | |
544 | JSON::XS/2 | 730760 | 328714 | |
555 | JSON::XS/2 | 371564.190 | 371725.613 | |
545 | -----------+------------+------------+ |
556 | -----------+------------+------------+ |
546 | |
557 | |
547 | That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80 |
558 | That is, JSON::XS is more than six times faster than JSON::DWIW on |
|
|
559 | encoding, more than three times faster on decoding, and about thirty times |
548 | times faster than JSON, even with pretty-printing and key sorting. |
560 | faster than JSON, even with pretty-printing and key sorting. |
549 | |
561 | |
550 | Using a longer test string (roughly 18KB, generated from Yahoo! Locals |
562 | Using a longer test string (roughly 18KB, generated from Yahoo! Locals |
551 | search API (http://nanoref.com/yahooapis/mgPdGg): |
563 | search API (http://nanoref.com/yahooapis/mgPdGg): |
552 | |
564 | |
553 | module | encode | decode | |
565 | module | encode | decode | |
554 | -----------|------------|------------| |
566 | -----------|------------|------------| |
555 | JSON | 673 | 38 | |
567 | JSON | 273.023 | 44.674 | |
556 | JSON::DWIW | 5271 | 770 | |
568 | JSON::DWIW | 1089.383 | 1145.704 | |
557 | JSON::PC | 9901 | 2491 | |
569 | JSON::PC | 3097.419 | 2393.921 | |
558 | JSON::Syck | 2360 | 786 | |
570 | JSON::Syck | 514.060 | 843.053 | |
559 | JSON::XS | 37398 | 3202 | |
571 | JSON::XS | 6479.668 | 3636.364 | |
560 | JSON::XS/2 | 13765 | 3153 | |
572 | JSON::XS/2 | 3774.221 | 3599.124 | |
561 | -----------+------------+------------+ |
573 | -----------+------------+------------+ |
562 | |
574 | |
563 | Again, JSON::XS leads by far in the encoding case, while still beating |
575 | Again, JSON::XS leads by far. |
564 | every other module in the decoding case. |
|
|
565 | |
576 | |
566 | On large strings containing lots of unicode characters, some modules |
577 | On large strings containing lots of high unicode characters, some modules |
567 | (such as JSON::PC) decode faster than JSON::XS, but the result will be |
578 | (such as JSON::PC) seem to decode faster than JSON::XS, but the result |
568 | broken due to missing unicode handling. Others refuse to decode or encode |
579 | will be broken due to missing (or wrong) unicode handling. Others refuse |
569 | properly, so it was impossible to prepare a fair comparison table for that |
580 | to decode or encode properly, so it was impossible to prepare a fair |
570 | case. |
581 | comparison table for that case. |
571 | |
582 | |
572 | =head1 RESOURCE LIMITS |
583 | =head1 RESOURCE LIMITS |
573 | |
584 | |
574 | JSON::XS does not impose any limits on the size of JSON texts or Perl |
585 | JSON::XS does not impose any limits on the size of JSON texts or Perl |
575 | values they represent - if your machine can handle it, JSON::XS will |
586 | values they represent - if your machine can handle it, JSON::XS will |