--- JSON-XS/XS.pm 2007/03/22 18:10:29 1.3 +++ JSON-XS/XS.pm 2007/03/23 15:10:55 1.7 @@ -61,7 +61,7 @@ package JSON::XS; BEGIN { - $VERSION = '0.1'; + $VERSION = '0.2'; @ISA = qw(Exporter); @EXPORT = qw(to_json from_json); @@ -116,12 +116,13 @@ my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]}) => {"a": [1, 2]} -=item $json = $json->ascii ($enable) +=item $json = $json->ascii ([$enable]) -If C<$enable> is true, then the C method will not generate -characters outside the code range C<0..127>. Any unicode characters -outside that range will be escaped using either a single \uXXXX (BMP -characters) or a double \uHHHH\uLLLLL escape sequence, as per RFC4627. +If C<$enable> is true (or missing), then the C method will +not generate characters outside the code range C<0..127>. Any unicode +characters outside that range will be escaped using either a single +\uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, as per +RFC4627. If C<$enable> is false, then the C method will not escape Unicode characters unless necessary. @@ -129,20 +130,20 @@ JSON::XS->new->ascii (1)->encode (chr 0x10401) => \ud801\udc01 -=item $json = $json->utf8 ($enable) +=item $json = $json->utf8 ([$enable]) -If C<$enable> is true, then the C method will encode the JSON -string into UTF-8, as required by many protocols, while the C -method expects to be handled an UTF-8-encoded string. Please note that -UTF-8-encoded strings do not contain any characters outside the range -C<0..255>, they are thus useful for bytewise/binary I/O. +If C<$enable> is true (or missing), then the C method will encode +the JSON string into UTF-8, as required by many protocols, while the +C method expects to be handled an UTF-8-encoded string. Please +note that UTF-8-encoded strings do not contain any characters outside the +range C<0..255>, they are thus useful for bytewise/binary I/O. If C<$enable> is false, then the C method will return the JSON string as a (non-encoded) unicode string, while C expects thus a unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs to be done yourself, e.g. using the Encode module. -=item $json = $json->pretty ($enable) +=item $json = $json->pretty ([$enable]) This enables (or disables) all of the C, C and C (and in the future possibly more) flags in one call to @@ -157,9 +158,9 @@ ] } -=item $json = $json->indent ($enable) +=item $json = $json->indent ([$enable]) -If C<$enable> is true, then the C method will use a multiline +If C<$enable> is true (or missing), then the C method will use a multiline format as output, putting every array member or object/hash key-value pair into its own line, identing them properly. @@ -168,9 +169,9 @@ This setting has no effect when decoding JSON strings. -=item $json = $json->space_before ($enable) +=item $json = $json->space_before ([$enable]) -If C<$enable> is true, then the C method will add an extra +If C<$enable> is true (or missing), then the C method will add an extra optional space before the C<:> separating keys from values in JSON objects. If C<$enable> is false, then the C method will not add any extra @@ -179,9 +180,9 @@ This setting has no effect when decoding JSON strings. You will also most likely combine this setting with C. -=item $json = $json->space_after ($enable) +=item $json = $json->space_after ([$enable]) -If C<$enable> is true, then the C method will add an extra +If C<$enable> is true (or missing), then the C method will add an extra optional space after the C<:> separating keys from values in JSON objects and extra whitespace after the C<,> separating key-value pairs and array members. @@ -191,9 +192,9 @@ This setting has no effect when decoding JSON strings. -=item $json = $json->canonical ($enable) +=item $json = $json->canonical ([$enable]) -If C<$enable> is true, then the C method will output JSON objects +If C<$enable> is true (or missing), then the C method will output JSON objects by sorting their keys. This is adding a comparatively high overhead. If C<$enable> is false, then the C method will output key-value @@ -207,9 +208,9 @@ This setting has no effect when decoding JSON strings. -=item $json = $json->allow_nonref ($enable) +=item $json = $json->allow_nonref ([$enable]) -If C<$enable> is true, then the C method can convert a +If C<$enable> is true (or missing), then the C method can convert a non-reference into its corresponding string, number or null JSON value, which is an extension to RFC4627. Likewise, C will accept those JSON values instead of croaking. @@ -219,6 +220,24 @@ or array. Likewise, C will croak if given something that is not a JSON object or array. +=item $json = $json->shrink ([$enable]) + +Perl usually over-allocates memory a bit when allocating space for +strings. This flag optionally resizes strings generated by either +C or C to their minimum size possible. This can save +memory when your JSON strings are either very very long or you have many +short strings. + +If C<$enable> is true (or missing), the string returned by C will be shrunk-to-fit, +while all strings generated by C will also be shrunk-to-fit. + +If C<$enable> is false, then the normal perl allocation algorithms are used. +If you work with your data, then this is likely to be faster. + +In the future, this setting might control other things, such as converting +strings that look like integers or floats into integers or floats +internally (there is no difference on the Perl level), saving space. + =item $json_string = $json->encode ($perl_scalar) Converts the given Perl data structure (a simple scalar or a reference @@ -244,11 +263,12 @@ As already mentioned, this module was created because none of the existing JSON modules could be made to work correctly. First I will describe the problems (or pleasures) I encountered with various existing JSON modules, -followed by some benchmark values. +followed by some benchmark values. JSON::XS was designed not to suffer +from any of these problems or limitations. =over 4 -=item JSON +=item JSON 1.07 Slow (but very portable, as it is written in pure Perl). @@ -260,20 +280,16 @@ the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will decode into the number 2. -=item JSON::PC +=item JSON::PC 0.01 Very fast. -Very inflexible (no human-readable format supported, format pretty much -undocumented. I need at least a format for easy reading by humans and a -single-line compact format for use in a protocol, and preferably a way to -generate ASCII-only JSON strings). - Undocumented/buggy Unicode handling. No roundtripping. -Has problems handling many Perl values. +Has problems handling many Perl values (e.g. regex results and other magic +values will make it croak). Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}> which is not a valid JSON string. @@ -281,11 +297,14 @@ Unmaintained (maintainer unresponsive for many months, bugs are not getting fixed). -=item JSON::Syck +=item JSON::Syck 0.21 Very buggy (often crashes). -Very inflexible. +Very inflexible (no human-readable format supported, format pretty much +undocumented. I need at least a format for easy reading by humans and a +single-line compact format for use in a protocol, and preferably a way to +generate ASCII-only JSON strings). Completely broken (and confusingly documented) Unicode handling (unicode escapes are not working properly, you need to set ImplicitUnicode to @@ -307,7 +326,7 @@ good protocol will at least recover, that is extra unnecessary work and the transaction will still not succeed). -=item JSON::DWIW +=item JSON::DWIW 0.04 Very fast. Very natural. Very nice. @@ -318,12 +337,64 @@ No roundtripping. +Does not generate valid JSON (key strings are often unquoted, empty keys +result in nothing being output) + Does not check input for validity. =back =head2 SPEED +It seems that JSON::XS is surprisingly fast, as shown in the following +tables. They have been generated with the help of the C program +in the JSON::XS distribution, to make it easy to compare on your own +system. + +First is a comparison between various modules using a very simple JSON +string, showing the number of encodes/decodes per second (JSON::XS is +the functional interface, while JSON::XS/2 is the OO interface with +pretty-printing and hashkey sorting enabled). + + module | encode | decode | + -----------|------------|------------| + JSON | 14006 | 6820 | + JSON::DWIW | 200937 | 120386 | + JSON::PC | 85065 | 129366 | + JSON::Syck | 59898 | 44232 | + JSON::XS | 1171478 | 342435 | + JSON::XS/2 | 730760 | 328714 | + -----------+------------+------------+ + +That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80 +times faster than JSON, even with pretty-printing and key sorting. + +Using a longer test string (roughly 8KB, generated from Yahoo! Locals +search API (http://nanoref.com/yahooapis/mgPdGg): + + module | encode | decode | + -----------|------------|------------| + JSON | 673 | 38 | + JSON::DWIW | 5271 | 770 | + JSON::PC | 9901 | 2491 | + JSON::Syck | 2360 | 786 | + JSON::XS | 37398 | 3202 | + JSON::XS/2 | 13765 | 3153 | + -----------+------------+------------+ + +Again, JSON::XS leads by far in the encoding case, while still beating +every other module in the decoding case. + +Last example is an almost 8MB large hash with many large binary values +(PNG files), resulting in a lot of escaping: + +=head1 BUGS + +While the goal of this module is to be correct, that unfortunately does +not mean its bug-free, only that I think its design is bug-free. It is +still very young and not well-tested. If you keep reporting bugs they will +be fixed swiftly, though. + =cut 1;