--- JSON-XS/XS.pm	2007/03/22 23:24:18	1.6
+++ JSON-XS/XS.pm	2007/03/23 15:10:55	1.7
@@ -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,24 @@
 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