--- JSON-XS/XS.pm	2007/03/22 21:13:58	1.4
+++ JSON-XS/XS.pm	2007/03/23 16:00:19	1.9
@@ -61,7 +61,7 @@
 package JSON::XS;
 
 BEGIN {
-   $VERSION = '0.1';
+   $VERSION = '0.3';
    @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<encode> 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<encode> 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<encode> 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<encode> method will encode the JSON
-string into UTF-8, as required by many protocols, while the C<decode>
-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<encode> method will encode
+the JSON string into UTF-8, as required by many protocols, while the
+C<decode> 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<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
@@ -157,9 +158,9 @@
       ]
    }
 
-=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.
 
@@ -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<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
@@ -179,9 +180,9 @@
 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.
@@ -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<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
@@ -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<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.
@@ -219,6 +220,27 @@
 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. It will also try to downgrade any strings to octet-form
+if possible: perl stores strings internally either in an encoding called
+UTF-X or in octet-form. The latter cannot store everything but uses less
+space in general.
+
+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
@@ -249,7 +271,7 @@
 
 =over 4
 
-=item JSON
+=item JSON 1.07
 
 Slow (but very portable, as it is written in pure Perl).
 
@@ -261,7 +283,7 @@
 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.
 
@@ -278,7 +300,7 @@
 Unmaintained (maintainer unresponsive for many months, bugs are not
 getting fixed).
 
-=item JSON::Syck
+=item JSON::Syck 0.21
 
 Very buggy (often crashes).
 
@@ -307,7 +329,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.