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.125 by root, Sat Oct 10 01:48:50 2009 UTC vs.
Revision 1.132 by root, Wed Mar 17 01:45:43 2010 UTC

… …
64so, and even documents what "correct" means. 64so, and even documents what "correct" means.
65 65
66=item * round-trip integrity 66=item * round-trip integrity
67 67
68When you serialise a perl data structure using only data types supported 68When you serialise a perl data structure using only data types supported
69by JSON, the deserialised data structure is identical on the Perl level. 69by JSON and Perl, the deserialised data structure is identical on the Perl
70(e.g. the string "2.0" doesn't suddenly become "2" just because it looks 70level. (e.g. the string "2.0" doesn't suddenly become "2" just because
71like a number). There minor I<are> exceptions to this, read the MAPPING 71it looks like a number). There I<are> minor exceptions to this, read the
72section below to learn about those. 72MAPPING section below to learn about those.
73 73
74=item * strict checking of JSON correctness 74=item * strict checking of JSON correctness
75 75
76There is no guessing, no generating of illegal JSON texts by default, 76There is no guessing, no generating of illegal JSON texts by default,
77and only JSON is accepted as input by default (the latter is a security 77and only JSON is accepted as input by default (the latter is a security
… …
101 101
102package JSON::XS; 102package JSON::XS;
103 103
104use common::sense; 104use common::sense;
105 105
106our $VERSION = '2.26'; 106our $VERSION = '2.29';
107our @ISA = qw(Exporter); 107our @ISA = qw(Exporter);
108 108
109our @EXPORT = qw(encode_json decode_json to_json from_json); 109our @EXPORT = qw(encode_json decode_json to_json from_json);
110 110
111sub to_json($) { 111sub to_json($) {
… …
751objects or arrays, instead they must be concatenated back-to-back. If 751objects or arrays, instead they must be concatenated back-to-back. If
752an error occurs, an exception will be raised as in the scalar context 752an error occurs, an exception will be raised as in the scalar context
753case. Note that in this case, any previously-parsed JSON texts will be 753case. Note that in this case, any previously-parsed JSON texts will be
754lost. 754lost.
755 755
756Example: Parse some JSON arrays/objects in a given string and return
757them.
758
759 my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
760
756=item $lvalue_string = $json->incr_text 761=item $lvalue_string = $json->incr_text
757 762
758This method returns the currently stored JSON fragment as an lvalue, that 763This method returns the currently stored JSON fragment as an lvalue, that
759is, you can manipulate it. This I<only> works when a preceding call to 764is, you can manipulate it. This I<only> works when a preceding call to
760C<incr_parse> in I<scalar context> successfully returned an object. Under 765C<incr_parse> in I<scalar context> successfully returned an object. Under
… …
989Numbers containing a fractional or exponential part will always be 994Numbers containing a fractional or exponential part will always be
990represented as numeric (floating point) values, possibly at a loss of 995represented as numeric (floating point) values, possibly at a loss of
991precision (in which case you might lose perfect roundtripping ability, but 996precision (in which case you might lose perfect roundtripping ability, but
992the JSON number will still be re-encoded as a JSON number). 997the JSON number will still be re-encoded as a JSON number).
993 998
999Note that precision is not accuracy - binary floating point values cannot
1000represent most decimal fractions exactly, and when converting from and to
1001floating point, JSON::XS only guarantees precision up to but not including
1002the leats significant bit.
1003
994=item true, false 1004=item true, false
995 1005
996These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 1006These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
997respectively. They are overloaded to act almost exactly like the numbers 1007respectively. They are overloaded to act almost exactly like the numbers
998C<1> and C<0>. You can check whether a scalar is a JSON boolean by using 1008C<1> and C<0>. You can check whether a scalar is a JSON boolean by using
… …
1085 1095
1086You can not currently force the type in other, less obscure, ways. Tell me 1096You can not currently force the type in other, less obscure, ways. Tell me
1087if you need this capability (but don't forget to explain why it's needed 1097if you need this capability (but don't forget to explain why it's needed
1088:). 1098:).
1089 1099
1100Note that numerical precision has the same meaning as under Perl (so
1101binary to decimal conversion follows the same rules as in Perl, which
1102can differ to other languages). Also, your perl interpreter might expose
1103extensions to the floating point numbers of your platform, such as
1104infinities or NaN's - these cannot be represented in JSON, and it is an
1105error to pass those in.
1106
1090=back 1107=back
1091 1108
1092 1109
1093=head1 ENCODING/CODESET FLAG NOTES 1110=head1 ENCODING/CODESET FLAG NOTES
1094 1111
… …
1324a very short single-line JSON string (also available at 1341a very short single-line JSON string (also available at
1325L<http://dist.schmorp.de/misc/json/short.json>). 1342L<http://dist.schmorp.de/misc/json/short.json>).
1326 1343
1327 {"method": "handleMessage", "params": ["user1", 1344 {"method": "handleMessage", "params": ["user1",
1328 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7, 1345 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1329 true, false]} 1346 1, 0]}
1330 1347
1331It shows the number of encodes/decodes per second (JSON::XS uses 1348It shows the number of encodes/decodes per second (JSON::XS uses
1332the functional interface, while JSON::XS/2 uses the OO interface 1349the functional interface, while JSON::XS/2 uses the OO interface
1333with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1350with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1334shrink). Higher is better: 1351shrink. JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ
1352uses the from_json method). Higher is better:
1335 1353
1336 module | encode | decode | 1354 module | encode | decode |
1337 -----------|------------|------------| 1355 --------------|------------|------------|
1338 JSON 1.x | 4990.842 | 4088.813 | 1356 JSON::DWIW/DS | 86302.551 | 102300.098 |
1339 JSON::DWIW | 51653.990 | 71575.154 | 1357 JSON::DWIW/FJ | 86302.551 | 75983.768 |
1340 JSON::PC | 65948.176 | 74631.744 | 1358 JSON::PP | 15827.562 | 6638.658 |
1341 JSON::PP | 8931.652 | 3817.168 | 1359 JSON::Syck | 63358.066 | 47662.545 |
1342 JSON::Syck | 24877.248 | 27776.848 | 1360 JSON::XS | 511500.488 | 511500.488 |
1343 JSON::XS | 388361.481 | 227951.304 | 1361 JSON::XS/2 | 291271.111 | 388361.481 |
1344 JSON::XS/2 | 227951.304 | 218453.333 | 1362 JSON::XS/3 | 361577.931 | 361577.931 |
1345 JSON::XS/3 | 338250.323 | 218453.333 | 1363 Storable | 66788.280 | 265462.278 |
1346 Storable | 16500.016 | 135300.129 |
1347 -----------+------------+------------+ 1364 --------------+------------+------------+
1348 1365
1349That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 1366That is, JSON::XS is almost six times faster than JSON::DWIW on encoding,
1350about three times faster on decoding, and over forty times faster 1367about five times faster on decoding, and over thirty to seventy times
1351than JSON, even with pretty-printing and key sorting. It also compares 1368faster than JSON's pure perl implementation. It also compares favourably
1352favourably to Storable for small amounts of data. 1369to Storable for small amounts of data.
1353 1370
1354Using a longer test string (roughly 18KB, generated from Yahoo! Locals 1371Using a longer test string (roughly 18KB, generated from Yahoo! Locals
1355search API (L<http://dist.schmorp.de/misc/json/long.json>). 1372search API (L<http://dist.schmorp.de/misc/json/long.json>).
1356 1373
1357 module | encode | decode | 1374 module | encode | decode |
1358 -----------|------------|------------| 1375 --------------|------------|------------|
1359 JSON 1.x | 55.260 | 34.971 | 1376 JSON::DWIW/DS | 1647.927 | 2673.916 |
1360 JSON::DWIW | 825.228 | 1082.513 | 1377 JSON::DWIW/FJ | 1630.249 | 2596.128 |
1361 JSON::PC | 3571.444 | 2394.829 |
1362 JSON::PP | 210.987 | 32.574 | 1378 JSON::PP | 400.640 | 62.311 |
1363 JSON::Syck | 552.551 | 787.544 | 1379 JSON::Syck | 1481.040 | 1524.869 |
1364 JSON::XS | 5780.463 | 4854.519 | 1380 JSON::XS | 20661.596 | 9541.183 |
1365 JSON::XS/2 | 3869.998 | 4798.975 | 1381 JSON::XS/2 | 10683.403 | 9416.938 |
1366 JSON::XS/3 | 5862.880 | 4798.975 | 1382 JSON::XS/3 | 20661.596 | 9400.054 |
1367 Storable | 4445.002 | 5235.027 | 1383 Storable | 19765.806 | 10000.725 |
1368 -----------+------------+------------+ 1384 --------------+------------+------------+
1369 1385
1370Again, JSON::XS leads by far (except for Storable which non-surprisingly 1386Again, JSON::XS leads by far (except for Storable which non-surprisingly
1371decodes faster). 1387decodes a bit faster).
1372 1388
1373On large strings containing lots of high Unicode characters, some modules 1389On large strings containing lots of high Unicode characters, some modules
1374(such as JSON::PC) seem to decode faster than JSON::XS, but the result 1390(such as JSON::PC) seem to decode faster than JSON::XS, but the result
1375will be broken due to missing (or wrong) Unicode handling. Others refuse 1391will be broken due to missing (or wrong) Unicode handling. Others refuse
1376to decode or encode properly, so it was impossible to prepare a fair 1392to decode or encode properly, so it was impossible to prepare a fair
… …
1412information you might want to make sure that exceptions thrown by JSON::XS 1428information you might want to make sure that exceptions thrown by JSON::XS
1413will not end up in front of untrusted eyes. 1429will not end up in front of untrusted eyes.
1414 1430
1415If you are using JSON::XS to return packets to consumption 1431If you are using JSON::XS to return packets to consumption
1416by JavaScript scripts in a browser you should have a look at 1432by JavaScript scripts in a browser you should have a look at
1417L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether 1433L<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/> to
1418you are vulnerable to some common attack vectors (which really are browser 1434see whether you are vulnerable to some common attack vectors (which really
1419design bugs, but it is still you who will have to deal with it, as major 1435are browser design bugs, but it is still you who will have to deal with
1420browser developers care only for features, not about getting security 1436it, as major browser developers care only for features, not about getting
1421right). 1437security right).
1422 1438
1423 1439
1424=head1 THREADS 1440=head1 THREADS
1425 1441
1426This module is I<not> guaranteed to be thread safe and there are no 1442This module is I<not> guaranteed to be thread safe and there are no

Diff Legend

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