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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.10 by root, Fri Mar 23 17:40:29 2007 UTC vs.
Revision 1.14 by root, Fri Mar 23 19:02:02 2007 UTC

 JSON::XS - JSON serialising/deserialising, done correctly and fast
 =head1 SYNOPSIS
  use JSON::XS;
+ # exported functions, croak on error
+ $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
+ $perl_hash_or_arrayref  = from_json $utf8_encoded_json_text;
+ # oo-interface
+ $coder = JSON::XS->new->ascii->pretty->allow_nonref;
+ $pretty_printed_unencoded = $coder->encode ($perl_scalar);
+ $perl_scalar = $coder->decode ($unicode_json_text);
 =head1 DESCRIPTION
 This module converts Perl data structures to JSON and vice versa. Its
 primary goal is to be I<correct> and its secondary goal is to be
 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.
+Example, output UTF-16-encoded JSON:
 =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.
+Example, pretty-print some simple structure:
    my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
    =>
    {
       "a" : [
 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>.
+Example, space_before enabled, space_after and indent disabled:
+   {"key" :"value"}
 =item $json = $json->space_after ([$enable])
 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
 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.
+Example, space_before and indent disabled, space_after enabled:
+   {"key": "value"}
 =item $json = $json->canonical ([$enable])
 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 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.
+Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
+resulting in an invalid JSON text:
+   JSON::XS->new->allow_nonref->encode ("Hello, World!")
+   => "Hello, World!"
 =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
 =over 4
 =item object
 A JSON object becomes a reference to a hash in Perl. No ordering of object
-keys is preserved.
+keys is preserved (JSON does not preserver object key ordering itself).
 =item array
 A JSON array becomes a reference to an array in Perl.
 =item hash references
 Perl hash references become JSON objects. As there is no inherent ordering
 in hash keys, they will usually be encoded in a pseudo-random order that
 can change between runs of the same program but stays generally the same
-within the single run of a program. JSON::XS can optionally sort the hash
+within a single run of a program. JSON::XS can optionally sort the hash
 keys (determined by the I<canonical> flag), so the same datastructure
 will serialise to the same JSON text (given same settings and version of
 JSON::XS), but this incurs a runtime overhead.
 =item array references
    $x += 0;     # numify it, ensuring it will be dumped as a number
    $x *= 1;     # same thing, the choise is yours.
 You can not currently output JSON booleans or force the type in other,
 less obscure, ways. Tell me if you need this capability.
+=item circular data structures
+Those will be encoded until memory or stackspace runs out.
 =back
 =head1 COMPARISON
 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
+First comes a comparison between various modules using a very short JSON
-string, showing the number of encodes/decodes per second (JSON::XS is
+string (83 bytes), showing the number of encodes/decodes per second
-the functional interface, while JSON::XS/2 is the OO interface with
+(JSON::XS is the functional interface, while JSON::XS/2 is the OO
-pretty-printing and hashkey sorting enabled).
+interface with pretty-printing and hashkey sorting enabled). Higher is
+better:
    module     |     encode |     decode |
    -----------|------------|------------|
    JSON       |      14006 |       6820 |
    JSON::DWIW |     200937 |     120386 |
    -----------+------------+------------+
 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
+Using a longer test string (roughly 18KB, generated from Yahoo! Locals
 search API (http://nanoref.com/yahooapis/mgPdGg):
    module     |     encode |     decode |
    -----------|------------|------------|
    JSON       |        673 |         38 |
    -----------+------------+------------+
 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
+On large strings containing lots of unicode characters, some modules
-(PNG files), resulting in a lot of escaping:
+(such as JSON::PC) decode faster than JSON::XS, but the result will be
+broken due to missing unicode handling. Others refuse to decode or encode
+properly, so it was impossible to prepare a fair comparison table for that
+case.
+=head1 RESOURCE LIMITS
+JSON::XS does not impose any limits on the size of JSON texts or Perl
+values they represent - if your machine can handle it, JSON::XS will
+encode or decode it. Future versions might optionally impose structure
+depth and memory use resource limits.
 =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

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.10 by root, Fri Mar 23 17:40:29 2007 UTC vs. Revision 1.14 by root, Fri Mar 23 19:02:02 2007 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.10 by root, Fri Mar 23 17:40:29 2007 UTC vs.
Revision 1.14 by root, Fri Mar 23 19:02:02 2007 UTC