--- JSON-XS/XS.pm	2007/05/23 22:07:43	1.36
+++ JSON-XS/XS.pm	2007/06/11 02:58:10	1.39
@@ -88,7 +88,7 @@
 use strict;
 
 BEGIN {
-   our $VERSION = '1.22';
+   our $VERSION = '1.23';
    our @ISA = qw(Exporter);
 
    our @EXPORT = qw(to_json from_json objToJson jsonToObj);
@@ -404,6 +404,7 @@
 lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
 refers to the abstract Perl language itself.
 
+
 =head2 JSON -> PERL
 
 =over 4
@@ -444,6 +445,7 @@
 
 =back
 
+
 =head2 PERL -> JSON
 
 The mapping from Perl to JSON is slightly more difficult, as Perl is a
@@ -607,6 +609,29 @@
 
 =back
 
+
+=head2 JSON and YAML
+
+You often hear that JSON is a subset (or a close subset) of YAML. This is,
+however, a mass hysteria and very far from the truth. In general, there is
+no way to configure JSON::XS to output a data structure as valid YAML.
+
+If you really must use JSON::XS to generate YAML, you should this
+algorithm (subject to change in future versions):
+
+   my $to_yaml = JSON::XS->new->utf8->space_after (1);
+   my $yaml = $to_yaml->encode ($ref) . "\n";
+
+This will usually generate JSON texts that also parse as valid
+YAML. Please note that YAML has hardcoded limits on object key lengths
+that JSON doesn't have, so you should make sure that your hash keys are
+noticably shorter than 1024 characters.
+
+There might be other incompatibilities that I am not aware of. In general
+you should not try to generate YAML with a JSON generator or vice versa,
+or try to parse JSON with a YAML parser or vice versa.
+
+
 =head2 SPEED
 
 It seems that JSON::XS is surprisingly fast, as shown in the following
@@ -614,40 +639,47 @@
 in the JSON::XS distribution, to make it easy to compare on your own
 system.
 
-First comes a comparison between various modules using a very short JSON
-string:
+First comes a comparison between various modules using a very short
+single-line JSON string:
 
-   {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
+   {"method": "handleMessage", "params": ["user1", "we were just talking"], \
+   "id": null, "array":[1,11,234,-5,1e5,1e7, true,  false]}
 
-It shows the number of encodes/decodes per second (JSON::XS uses the
-functional interface, while JSON::XS/2 uses the OO interface with
-pretty-printing and hashkey sorting enabled). Higher is better:
+It shows the number of encodes/decodes per second (JSON::XS uses
+the functional interface, while JSON::XS/2 uses the OO interface
+with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
+shrink). Higher is better:
 
    module     |     encode |     decode |
    -----------|------------|------------|
-   JSON       |  11488.516 |   7823.035 |
-   JSON::DWIW |  94708.054 | 129094.260 |
-   JSON::PC   |  63884.157 | 128528.212 |
-   JSON::Syck |  34898.677 |  42096.911 |
-   JSON::XS   | 654027.064 | 396423.669 |
-   JSON::XS/2 | 371564.190 | 371725.613 |
+   JSON       |   7645.468 |   4208.613 |
+   JSON::DWIW |  68534.379 |  79437.576 |
+   JSON::PC   |  65948.176 |  78251.940 |
+   JSON::Syck |  23379.621 |  28416.694 |
+   JSON::XS   | 388361.481 | 199728.762 |
+   JSON::XS/2 | 218453.333 | 192399.266 |
+   JSON::XS/3 | 338250.323 | 192399.266 |
+   Storable   |  15732.573 |  28571.553 |
    -----------+------------+------------+
 
-That is, JSON::XS is more than six times faster than JSON::DWIW on
-encoding, more than three times faster on decoding, and about thirty times
-faster than JSON, even with pretty-printing and key sorting.
+That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
+about three times faster on decoding, and over fourty times faster
+than JSON, even with pretty-printing and key sorting. It also compares
+favourably to Storable for small amounts of data.
 
 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
 search API (http://nanoref.com/yahooapis/mgPdGg):
 
    module     |     encode |     decode |
    -----------|------------|------------|
-   JSON       |    273.023 |     44.674 |
-   JSON::DWIW |   1089.383 |   1145.704 |
-   JSON::PC   |   3097.419 |   2393.921 |
-   JSON::Syck |    514.060 |    843.053 |
-   JSON::XS   |   6479.668 |   3636.364 |
-   JSON::XS/2 |   3774.221 |   3599.124 |
+   JSON       |    254.685 |     37.665 |
+   JSON::DWIW |   1014.244 |   1087.678 |
+   JSON::PC   |   3602.116 |   2307.352 |
+   JSON::Syck |    558.035 |    776.263 |
+   JSON::XS   |   5747.196 |   3543.684 |
+   JSON::XS/2 |   3968.121 |   3589.170 |
+   JSON::XS/3 |   6105.246 |   3561.134 |
+   Storable   |   4456.337 |   5320.020 |
    -----------+------------+------------+
 
 Again, JSON::XS leads by far.