--- JSON-XS/XS.pm	2010/01/19 01:02:19	1.129
+++ JSON-XS/XS.pm	2013/05/23 09:31:32	1.139
@@ -66,10 +66,10 @@
 =item * round-trip integrity
 
 When you serialise a perl data structure using only data types supported
-by JSON, the deserialised data structure is identical on the Perl level.
-(e.g. the string "2.0" doesn't suddenly become "2" just because it looks
-like a number). There minor I<are> exceptions to this, read the MAPPING
-section below to learn about those.
+by JSON and Perl, the deserialised data structure is identical on the Perl
+level. (e.g. the string "2.0" doesn't suddenly become "2" just because
+it looks like a number). There I<are> minor exceptions to this, read the
+MAPPING section below to learn about those.
 
 =item * strict checking of JSON correctness
 
@@ -103,7 +103,7 @@
 
 use common::sense;
 
-our $VERSION = '2.28';
+our $VERSION = 2.34;
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_json decode_json to_json from_json);
@@ -434,7 +434,8 @@
 
 If C<$enable> is false, then the C<encode> method will output key-value
 pairs in the order Perl stores them (which will likely change between runs
-of the same script).
+of the same script, and can change even within the same run from 5.18
+onwards).
 
 This option is useful if you want the same data structure to be encoded as
 the same JSON text (given the same overall settings). If it is disabled,
@@ -715,8 +716,8 @@
 JSON::XS will only attempt to parse the JSON text once it is sure it
 has enough text to get a decisive result, using a very simple but
 truly incremental parser. This means that it sometimes won't stop as
-early as the full parser, for example, it doesn't detect parenthese
-mismatches. The only thing it guarantees is that it starts decoding as
+early as the full parser, for example, it doesn't detect mismatched
+parentheses. The only thing it guarantees is that it starts decoding as
 soon as a syntactically valid JSON text has been seen. This means you need
 to set resource limits (e.g. C<max_size>) to ensure the parser will stop
 parsing in the presence if syntax errors.
@@ -753,6 +754,11 @@
 case. Note that in this case, any previously-parsed JSON texts will be
 lost.
 
+Example: Parse some JSON arrays/objects in a given string and return
+them.
+
+   my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
+
 =item $lvalue_string = $json->incr_text
 
 This method returns the currently stored JSON fragment as an lvalue, that
@@ -991,6 +997,11 @@
 precision (in which case you might lose perfect roundtripping ability, but
 the JSON number will still be re-encoded as a JSON number).
 
+Note that precision is not accuracy - binary floating point values cannot
+represent most decimal fractions exactly, and when converting from and to
+floating point, JSON::XS only guarantees precision up to but not including
+the leats significant bit.
+
 =item true, false
 
 These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
@@ -1087,6 +1098,13 @@
 if you need this capability (but don't forget to explain why it's needed
 :).
 
+Note that numerical precision has the same meaning as under Perl (so
+binary to decimal conversion follows the same rules as in Perl, which
+can differ to other languages). Also, your perl interpreter might expose
+extensions to the floating point numbers of your platform, such as
+infinities or NaN's - these cannot be represented in JSON, and it is an
+error to pass those in.
+
 =back
 
 
@@ -1240,7 +1258,7 @@
 Another problem is that some javascript implementations reserve
 some property names for their own purposes (which probably makes
 them non-ECMAscript-compliant). For example, Iceweasel reserves the
-C<__proto__> property name for it's own purposes.
+C<__proto__> property name for its own purposes.
 
 If that is a problem, you could parse try to filter the resulting JSON
 output for these property strings, e.g.:
@@ -1304,10 +1322,10 @@
 real compatibility for many I<years> and trying to silence people who
 point out that it isn't true.
 
-Addendum/2009: the YAML 1.2 spec is still incomaptible with JSON, even
-though the incompatibilities have been documented (and are known to
-Brian) for many years and the spec makes explicit claims that YAML is a
-superset of JSON. It would be so easy to fix, but apparently, bullying and
+Addendum/2009: the YAML 1.2 spec is still incompatible with JSON, even
+though the incompatibilities have been documented (and are known to Brian)
+for many years and the spec makes explicit claims that YAML is a superset
+of JSON. It would be so easy to fix, but apparently, bullying people and
 corrupting userdata is so much easier.
 
 =back
@@ -1430,6 +1448,24 @@
 (It might actually work, but you have been warned).
 
 
+=head1 THE PERILS OF SETLOCALE
+
+Sometimes people avoid the Perl locale support and directly call the
+system's setlocale function with C<LC_ALL>.
+
+This breaks both perl and modules such as JSON::XS, as stringification of
+numbers no longer works correcly (e.g. C<$x = 0.1; print "$x"+1> might
+print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on
+perl to stringify numbers).
+
+The solution is simple: don't call C<setlocale>, or use it for only those
+categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>.
+
+If you need C<LC_NUMERIC>, you should enable it only around the code that
+actually needs it (avoiding stringification of numbers), and restore it
+afterwards.
+
+
 =head1 BUGS
 
 While the goal of this module is to be correct, that unfortunately does