--- JSON-XS/XS.pm	2007/03/22 18:10:29	1.3
+++ JSON-XS/XS.pm	2007/03/22 21:13:58	1.4
@@ -244,7 +244,8 @@
 As already mentioned, this module was created because none of the existing
 JSON modules could be made to work correctly. First I will describe the
 problems (or pleasures) I encountered with various existing JSON modules,
-followed by some benchmark values.
+followed by some benchmark values. JSON::XS was designed not to suffer
+from any of these problems or limitations.
 
 =over 4
 
@@ -264,16 +265,12 @@
 
 Very fast.
 
-Very inflexible (no human-readable format supported, format pretty much
-undocumented. I need at least a format for easy reading by humans and a
-single-line compact format for use in a protocol, and preferably a way to
-generate ASCII-only JSON strings).
-
 Undocumented/buggy Unicode handling.
 
 No roundtripping.
 
-Has problems handling many Perl values.
+Has problems handling many Perl values (e.g. regex results and other magic
+values will make it croak).
 
 Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
 which is not a valid JSON string.
@@ -285,7 +282,10 @@
 
 Very buggy (often crashes).
 
-Very inflexible.
+Very inflexible (no human-readable format supported, format pretty much
+undocumented. I need at least a format for easy reading by humans and a
+single-line compact format for use in a protocol, and preferably a way to
+generate ASCII-only JSON strings).
 
 Completely broken (and confusingly documented) Unicode handling (unicode
 escapes are not working properly, you need to set ImplicitUnicode to
@@ -318,12 +318,64 @@
 
 No roundtripping.
 
+Does not generate valid JSON (key strings are often unquoted, empty keys
+result in nothing being output)
+
 Does not check input for validity.
 
 =back
 
 =head2 SPEED
 
+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
+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).
+
+   module     |     encode |     decode |
+   -----------|------------|------------|
+   JSON       |      14006 |       6820 |
+   JSON::DWIW |     200937 |     120386 |
+   JSON::PC   |      85065 |     129366 |
+   JSON::Syck |      59898 |      44232 |
+   JSON::XS   |    1171478 |     342435 |
+   JSON::XS/2 |     730760 |     328714 |
+   -----------+------------+------------+
+
+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
+search API (http://nanoref.com/yahooapis/mgPdGg):
+
+   module     |     encode |     decode |
+   -----------|------------|------------|
+   JSON       |        673 |         38 |
+   JSON::DWIW |       5271 |        770 |
+   JSON::PC   |       9901 |       2491 |
+   JSON::Syck |       2360 |        786 |
+   JSON::XS   |      37398 |       3202 |
+   JSON::XS/2 |      13765 |       3153 |
+   -----------+------------+------------+
+
+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:
+
+=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
+still very young and not well-tested. If you keep reporting bugs they will
+be fixed swiftly, though.
+
 =cut
 
 1;