--- JSON-XS/XS.pm	2007/03/23 17:40:29	1.10
+++ JSON-XS/XS.pm	2007/03/23 18:37:30	1.13
@@ -6,6 +6,17 @@
 
  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
@@ -149,12 +160,16 @@
 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]})
    =>
    {
@@ -186,6 +201,10 @@
 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
@@ -198,6 +217,10 @@
 
 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
@@ -226,6 +249,12 @@
 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
@@ -381,6 +410,10 @@
 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
@@ -476,10 +509,11 @@
 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).
+First comes a comparison between various modules using a very short JSON
+string (83 bytes), 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). Higher is
+better:
 
    module     |     encode |     decode |
    -----------|------------|------------|
@@ -494,7 +528,7 @@
 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 |
@@ -510,8 +544,18 @@
 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:
+On large strings containing lots of unicode characters, some modules
+(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