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.122 by root, Fri Jul 17 14:33:45 2009 UTC vs.
Revision 1.133 by root, Tue Aug 17 23:27:36 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.24'; 106our $VERSION = '2.3';
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
… …
1268 my $yaml = $to_yaml->encode ($ref) . "\n"; 1285 my $yaml = $to_yaml->encode ($ref) . "\n";
1269 1286
1270This will I<usually> generate JSON texts that also parse as valid 1287This will I<usually> generate JSON texts that also parse as valid
1271YAML. Please note that YAML has hardcoded limits on (simple) object key 1288YAML. Please note that YAML has hardcoded limits on (simple) object key
1272lengths that JSON doesn't have and also has different and incompatible 1289lengths that JSON doesn't have and also has different and incompatible
1273unicode handling, so you should make sure that your hash keys are 1290unicode character escape syntax, so you should make sure that your hash
1274noticeably shorter than the 1024 "stream characters" YAML allows and that 1291keys are noticeably shorter than the 1024 "stream characters" YAML allows
1275you do not have characters with codepoint values outside the Unicode BMP 1292and that you do not have characters with codepoint values outside the
1276(basic multilingual page). YAML also does not allow C<\/> sequences in 1293Unicode BMP (basic multilingual page). YAML also does not allow C<\/>
1277strings (which JSON::XS does not I<currently> generate, but other JSON 1294sequences in strings (which JSON::XS does not I<currently> generate, but
1278generators might). 1295other JSON generators might).
1279 1296
1280There might be other incompatibilities that I am not aware of (or the YAML 1297There might be other incompatibilities that I am not aware of (or the YAML
1281specification has been changed yet again - it does so quite often). In 1298specification has been changed yet again - it does so quite often). In
1282general you should not try to generate YAML with a JSON generator or vice 1299general you should not try to generate YAML with a JSON generator or vice
1283versa, or try to parse JSON with a YAML parser or vice versa: chances are 1300versa, or try to parse JSON with a YAML parser or vice versa: chances are
… …
1302that difficult or long) and finally make YAML compatible to it, and 1319that difficult or long) and finally make YAML compatible to it, and
1303educating users about the changes, instead of spreading lies about the 1320educating users about the changes, instead of spreading lies about the
1304real compatibility for many I<years> and trying to silence people who 1321real compatibility for many I<years> and trying to silence people who
1305point out that it isn't true. 1322point out that it isn't true.
1306 1323
1324Addendum/2009: the YAML 1.2 spec is still incomaptible with JSON, even
1325though the incompatibilities have been documented (and are known to
1326Brian) for many years and the spec makes explicit claims that YAML is a
1327superset of JSON. It would be so easy to fix, but apparently, bullying and
1328corrupting userdata is so much easier.
1329
1307=back 1330=back
1308 1331
1309 1332
1310=head2 SPEED 1333=head2 SPEED
1311 1334
… …
1318a very short single-line JSON string (also available at 1341a very short single-line JSON string (also available at
1319L<http://dist.schmorp.de/misc/json/short.json>). 1342L<http://dist.schmorp.de/misc/json/short.json>).
1320 1343
1321 {"method": "handleMessage", "params": ["user1", 1344 {"method": "handleMessage", "params": ["user1",
1322 "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,
1323 true, false]} 1346 1, 0]}
1324 1347
1325It shows the number of encodes/decodes per second (JSON::XS uses 1348It shows the number of encodes/decodes per second (JSON::XS uses
1326the functional interface, while JSON::XS/2 uses the OO interface 1349the functional interface, while JSON::XS/2 uses the OO interface
1327with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1350with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1328shrink). Higher is better: 1351shrink. JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ
1352uses the from_json method). Higher is better:
1329 1353
1330 module | encode | decode | 1354 module | encode | decode |
1331 -----------|------------|------------| 1355 --------------|------------|------------|
1332 JSON 1.x | 4990.842 | 4088.813 | 1356 JSON::DWIW/DS | 86302.551 | 102300.098 |
1333 JSON::DWIW | 51653.990 | 71575.154 | 1357 JSON::DWIW/FJ | 86302.551 | 75983.768 |
1334 JSON::PC | 65948.176 | 74631.744 | 1358 JSON::PP | 15827.562 | 6638.658 |
1335 JSON::PP | 8931.652 | 3817.168 | 1359 JSON::Syck | 63358.066 | 47662.545 |
1336 JSON::Syck | 24877.248 | 27776.848 | 1360 JSON::XS | 511500.488 | 511500.488 |
1337 JSON::XS | 388361.481 | 227951.304 | 1361 JSON::XS/2 | 291271.111 | 388361.481 |
1338 JSON::XS/2 | 227951.304 | 218453.333 | 1362 JSON::XS/3 | 361577.931 | 361577.931 |
1339 JSON::XS/3 | 338250.323 | 218453.333 | 1363 Storable | 66788.280 | 265462.278 |
1340 Storable | 16500.016 | 135300.129 |
1341 -----------+------------+------------+ 1364 --------------+------------+------------+
1342 1365
1343That 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,
1344about three times faster on decoding, and over forty times faster 1367about five times faster on decoding, and over thirty to seventy times
1345than JSON, even with pretty-printing and key sorting. It also compares 1368faster than JSON's pure perl implementation. It also compares favourably
1346favourably to Storable for small amounts of data. 1369to Storable for small amounts of data.
1347 1370
1348Using a longer test string (roughly 18KB, generated from Yahoo! Locals 1371Using a longer test string (roughly 18KB, generated from Yahoo! Locals
1349search API (L<http://dist.schmorp.de/misc/json/long.json>). 1372search API (L<http://dist.schmorp.de/misc/json/long.json>).
1350 1373
1351 module | encode | decode | 1374 module | encode | decode |
1352 -----------|------------|------------| 1375 --------------|------------|------------|
1353 JSON 1.x | 55.260 | 34.971 | 1376 JSON::DWIW/DS | 1647.927 | 2673.916 |
1354 JSON::DWIW | 825.228 | 1082.513 | 1377 JSON::DWIW/FJ | 1630.249 | 2596.128 |
1355 JSON::PC | 3571.444 | 2394.829 |
1356 JSON::PP | 210.987 | 32.574 | 1378 JSON::PP | 400.640 | 62.311 |
1357 JSON::Syck | 552.551 | 787.544 | 1379 JSON::Syck | 1481.040 | 1524.869 |
1358 JSON::XS | 5780.463 | 4854.519 | 1380 JSON::XS | 20661.596 | 9541.183 |
1359 JSON::XS/2 | 3869.998 | 4798.975 | 1381 JSON::XS/2 | 10683.403 | 9416.938 |
1360 JSON::XS/3 | 5862.880 | 4798.975 | 1382 JSON::XS/3 | 20661.596 | 9400.054 |
1361 Storable | 4445.002 | 5235.027 | 1383 Storable | 19765.806 | 10000.725 |
1362 -----------+------------+------------+ 1384 --------------+------------+------------+
1363 1385
1364Again, JSON::XS leads by far (except for Storable which non-surprisingly 1386Again, JSON::XS leads by far (except for Storable which non-surprisingly
1365decodes faster). 1387decodes a bit faster).
1366 1388
1367On large strings containing lots of high Unicode characters, some modules 1389On large strings containing lots of high Unicode characters, some modules
1368(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
1369will be broken due to missing (or wrong) Unicode handling. Others refuse 1391will be broken due to missing (or wrong) Unicode handling. Others refuse
1370to 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
… …
1406information 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
1407will not end up in front of untrusted eyes. 1429will not end up in front of untrusted eyes.
1408 1430
1409If you are using JSON::XS to return packets to consumption 1431If you are using JSON::XS to return packets to consumption
1410by JavaScript scripts in a browser you should have a look at 1432by JavaScript scripts in a browser you should have a look at
1411L<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
1412you are vulnerable to some common attack vectors (which really are browser 1434see whether you are vulnerable to some common attack vectors (which really
1413design 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
1414browser developers care only for features, not about getting security 1436it, as major browser developers care only for features, not about getting
1415right). 1437security right).
1416 1438
1417 1439
1418=head1 THREADS 1440=head1 THREADS
1419 1441
1420This 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