[ViewVC] Diff of: cvs/JSON-XS/XS.pm

Comparing JSON-XS/XS.pm (file contents):
Revision 1.3 by root, Thu Mar 22 18:10:29 2007 UTC vs.
Revision 1.7 by root, Fri Mar 23 15:10:55 2007 UTC

 =cut
 package JSON::XS;
 BEGIN {
-   $VERSION = '0.1';
+   $VERSION = '0.2';
    @ISA = qw(Exporter);
    @EXPORT = qw(to_json from_json);
    require Exporter;
 be chained:
    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<encode> method will not generate
+If C<$enable> is true (or missing), then the C<encode> method will
-characters outside the code range C<0..127>. Any unicode characters
+not generate characters outside the code range C<0..127>. Any unicode
-outside that range will be escaped using either a single \uXXXX (BMP
+characters outside that range will be escaped using either a single
-characters) or a double \uHHHH\uLLLLL escape sequence, as per RFC4627.
+\uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, as per
+RFC4627.
 If C<$enable> is false, then the C<encode> method will not escape Unicode
 characters unless necessary.
   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<encode> method will encode the JSON
+If C<$enable> is true (or missing), then the C<encode> method will encode
-string into UTF-8, as required by many protocols, while the C<decode>
+the JSON string into UTF-8, as required by many protocols, while the
-method expects to be handled an UTF-8-encoded string.  Please note that
+C<decode> method expects to be handled an UTF-8-encoded string.  Please
-UTF-8-encoded strings do not contain any characters outside the range
+note that UTF-8-encoded strings do not contain any characters outside the
-C<0..255>, they are thus useful for bytewise/binary I/O.
+range C<0..255>, they are thus useful for bytewise/binary I/O.
 If C<$enable> is false, then the C<encode> method will return the JSON
 string as a (non-encoded) unicode string, while C<decode> 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<indent>, C<space_before> and
 C<space_after> (and in the future possibly more) flags in one call to
 generate the most readable (or most compact) form possible.
          1,
          2
       ]
    }
-=item $json = $json->indent ($enable)
+=item $json = $json->indent ([$enable])
-If C<$enable> is true, then the C<encode> method will use a multiline
+If C<$enable> is true (or missing), then the C<encode> 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.
 If C<$enable> is false, no newlines or indenting will be produced, and the
 resulting JSON strings is guarenteed not to contain any C<newlines>.
 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<encode> method will add an extra
+If C<$enable> is true (or missing), then the C<encode> 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<encode> method will not add any extra
 space at those places.
 This setting has no effect when decoding JSON strings. You will also most
 likely combine this setting with C<space_after>.
-=item $json = $json->space_after ($enable)
+=item $json = $json->space_after ([$enable])
-If C<$enable> is true, then the C<encode> method will add an extra
+If C<$enable> is true (or missing), then the C<encode> 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.
 If C<$enable> is false, then the C<encode> method will not add any extra
 space at those places.
 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<encode> method will output JSON objects
+If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
 by sorting their keys. This is adding a comparatively high overhead.
 If C<$enable> is false, then the C<encode> method will output key-value
 pairs in the order Perl stores them (which will likely change between runs
 of the same script).
 the same hash migh be encoded differently even if contains the same data,
 as key-value pairs have no inherent ordering in Perl.
 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<encode> method can convert a
+If C<$enable> is true (or missing), then the C<encode> method can convert a
 non-reference into its corresponding string, number or null JSON value,
 which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
 values instead of croaking.
 If C<$enable> is false, then the C<encode> method will croak if it isn't
 passed an arrayref or hashref, as JSON strings must either be an object
 or array. Likewise, C<decode> 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<encode> or C<decode> 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<encode> will be shrunk-to-fit,
+while all strings generated by C<decode> 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
 to a hash or array) to its JSON representation. Simple scalars will be
 =head1 COMPARISON
 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).
 Undocumented/buggy Unicode handling (how JSON handles unicode values is
 undocumented. One can get far by feeding it unicode strings and doing
 No roundtripping (strings get clobbered if they look like numbers, e.g.
 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.
+Undocumented/buggy Unicode handling.
+No roundtripping.
+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.
+Unmaintained (maintainer unresponsive for many months, bugs are not
+getting fixed).
+=item JSON::Syck 0.21
+Very buggy (often crashes).
 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.
-Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
-which is not a valid JSON string.
-Unmaintained (maintainer unresponsive for many months, bugs are not
-getting fixed).
-=item JSON::Syck
-Very buggy (often crashes).
-Very inflexible.
 Completely broken (and confusingly documented) Unicode handling (unicode
 escapes are not working properly, you need to set ImplicitUnicode to
 I<different> values on en- and decoding to get symmetric behaviour).
 JSON. One bank might parse a given non-JSON request and deduct money,
 while the other might reject the transaction with a syntax error. While a
 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.
 Undocumented unicode handling (but the best of the pack. Unicode escapes
 still don't get parsed properly).
 Very inflexible.
 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<eg/bench> 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;

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.3 by root, Thu Mar 22 18:10:29 2007 UTC vs. Revision 1.7 by root, Fri Mar 23 15:10:55 2007 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.3 by root, Thu Mar 22 18:10:29 2007 UTC vs.
Revision 1.7 by root, Fri Mar 23 15:10:55 2007 UTC