--- JSON-XS/README 2010/01/19 00:31:13 1.33 +++ JSON-XS/README 2011/07/27 15:53:40 1.36 @@ -58,10 +58,11 @@ * round-trip integrity When you serialise a perl data structure using only data types - supported by JSON, the deserialised data structure is identical on - the Perl level. (e.g. the string "2.0" doesn't suddenly become "2" - just because it looks like a number). There minor *are* exceptions - to this, read the MAPPING section below to learn about those. + supported by JSON and Perl, the deserialised data structure is + identical on the Perl level. (e.g. the string "2.0" doesn't suddenly + become "2" just because it looks like a number). There *are* minor + exceptions to this, read the MAPPING section below to learn about + those. * strict checking of JSON correctness @@ -637,7 +638,7 @@ JSON::XS will only attempt to parse the JSON text once it is sure it has enough text to get a decisive result, using a very simple but truly incremental parser. This means that it sometimes won't stop as early as - the full parser, for example, it doesn't detect parenthese mismatches. + the full parser, for example, it doesn't detect mismatched parentheses. The only thing it guarantees is that it starts decoding as soon as a syntactically valid JSON text has been seen. This means you need to set resource limits (e.g. "max_size") to ensure the parser will stop parsing @@ -672,6 +673,11 @@ the scalar context case. Note that in this case, any previously-parsed JSON texts will be lost. + Example: Parse some JSON arrays/objects in a given string and return + them. + + my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]"); + $lvalue_string = $json->incr_text This method returns the currently stored JSON fragment as an lvalue, that is, you can manipulate it. This *only* works when a preceding @@ -896,6 +902,11 @@ ability, but the JSON number will still be re-encoded as a JSON number). + Note that precision is not accuracy - binary floating point values + cannot represent most decimal fractions exactly, and when converting + from and to floating point, JSON::XS only guarantees precision up to + but not including the leats significant bit. + true, false These JSON atoms become "JSON::XS::true" and "JSON::XS::false", respectively. They are overloaded to act almost exactly like the @@ -981,6 +992,13 @@ Tell me if you need this capability (but don't forget to explain why it's needed :). + Note that numerical precision has the same meaning as under Perl (so + binary to decimal conversion follows the same rules as in Perl, + which can differ to other languages). Also, your perl interpreter + might expose extensions to the floating point numbers of your + platform, such as infinities or NaN's - these cannot be represented + in JSON, and it is an error to pass those in. + ENCODING/CODESET FLAG NOTES The interested reader might have seen a number of flags that signify encodings or codesets - "utf8", "latin1" and "ascii". There seems to be @@ -1127,7 +1145,7 @@ Another problem is that some javascript implementations reserve some property names for their own purposes (which probably makes them non-ECMAscript-compliant). For example, Iceweasel reserves the - "__proto__" property name for it's own purposes. + "__proto__" property name for its own purposes. If that is a problem, you could parse try to filter the resulting JSON output for these property strings, e.g.: @@ -1185,11 +1203,12 @@ spreading lies about the real compatibility for many *years* and trying to silence people who point out that it isn't true. - Addendum/2009: the YAML 1.2 spec is still incomaptible with JSON, + Addendum/2009: the YAML 1.2 spec is still incompatible with JSON, even though the incompatibilities have been documented (and are known to Brian) for many years and the spec makes explicit claims that YAML is a superset of JSON. It would be so easy to fix, but - apparently, bullying and corrupting userdata is so much easier. + apparently, bullying people and corrupting userdata is so much + easier. SPEED It seems that JSON::XS is surprisingly fast, as shown in the following @@ -1203,49 +1222,48 @@ {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7, - true, false]} + 1, 0]} It shows the number of encodes/decodes per second (JSON::XS uses the functional interface, while JSON::XS/2 uses the OO interface with - pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). - Higher is better: - - module | encode | decode | - -----------|------------|------------| - JSON 1.x | 4990.842 | 4088.813 | - JSON::DWIW | 51653.990 | 71575.154 | - JSON::PC | 65948.176 | 74631.744 | - JSON::PP | 8931.652 | 3817.168 | - JSON::Syck | 24877.248 | 27776.848 | - JSON::XS | 388361.481 | 227951.304 | - JSON::XS/2 | 227951.304 | 218453.333 | - JSON::XS/3 | 338250.323 | 218453.333 | - Storable | 16500.016 | 135300.129 | - -----------+------------+------------+ - - That is, JSON::XS is about five times faster than JSON::DWIW on - encoding, about three times faster on decoding, and over forty times - faster than JSON, even with pretty-printing and key sorting. It also + pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink. + JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ uses + the from_json method). Higher is better: + + module | encode | decode | + --------------|------------|------------| + JSON::DWIW/DS | 86302.551 | 102300.098 | + JSON::DWIW/FJ | 86302.551 | 75983.768 | + JSON::PP | 15827.562 | 6638.658 | + JSON::Syck | 63358.066 | 47662.545 | + JSON::XS | 511500.488 | 511500.488 | + JSON::XS/2 | 291271.111 | 388361.481 | + JSON::XS/3 | 361577.931 | 361577.931 | + Storable | 66788.280 | 265462.278 | + --------------+------------+------------+ + + That is, JSON::XS is almost six times faster than JSON::DWIW on + encoding, about five times faster on decoding, and over thirty to + seventy times faster than JSON's pure perl implementation. It also compares favourably to Storable for small amounts of data. Using a longer test string (roughly 18KB, generated from Yahoo! Locals search API (). - module | encode | decode | - -----------|------------|------------| - JSON 1.x | 55.260 | 34.971 | - JSON::DWIW | 825.228 | 1082.513 | - JSON::PC | 3571.444 | 2394.829 | - JSON::PP | 210.987 | 32.574 | - JSON::Syck | 552.551 | 787.544 | - JSON::XS | 5780.463 | 4854.519 | - JSON::XS/2 | 3869.998 | 4798.975 | - JSON::XS/3 | 5862.880 | 4798.975 | - Storable | 4445.002 | 5235.027 | - -----------+------------+------------+ + module | encode | decode | + --------------|------------|------------| + JSON::DWIW/DS | 1647.927 | 2673.916 | + JSON::DWIW/FJ | 1630.249 | 2596.128 | + JSON::PP | 400.640 | 62.311 | + JSON::Syck | 1481.040 | 1524.869 | + JSON::XS | 20661.596 | 9541.183 | + JSON::XS/2 | 10683.403 | 9416.938 | + JSON::XS/3 | 20661.596 | 9400.054 | + Storable | 19765.806 | 10000.725 | + --------------+------------+------------+ Again, JSON::XS leads by far (except for Storable which non-surprisingly - decodes faster). + decodes a bit faster). On large strings containing lots of high Unicode characters, some modules (such as JSON::PC) seem to decode faster than JSON::XS, but the