--- JSON-XS/XS.pm	2010/01/19 01:02:19	1.129
+++ JSON-XS/XS.pm	2013/10/25 20:02:54	1.143
@@ -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
 
@@ -85,7 +85,7 @@
 =item * simple to use
 
 This module has both a simple functional interface as well as an object
-oriented interface interface.
+oriented interface.
 
 =item * reasonably versatile output formats
 
@@ -103,20 +103,10 @@
 
 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);
-
-sub to_json($) {
-   require Carp;
-   Carp::croak ("JSON::XS::to_json has been renamed to encode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
-}
-
-sub from_json($) {
-   require Carp;
-   Carp::croak ("JSON::XS::from_json has been renamed to decode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
-}
+our @EXPORT = qw(encode_json decode_json);
 
 use Exporter;
 use XSLoader;
@@ -434,7 +424,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,
@@ -668,22 +659,14 @@
 
 =item $json_text = $json->encode ($perl_scalar)
 
-Converts the given Perl data structure (a simple scalar or a reference
-to a hash or array) to its JSON representation. Simple scalars will be
-converted into JSON string or number sequences, while references to arrays
-become JSON arrays and references to hashes become JSON objects. Undefined
-Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
-nor C<false> values will be generated.
+Converts the given Perl value or data structure to its JSON
+representation. Croaks on error.
 
 =item $perl_scalar = $json->decode ($json_text)
 
 The opposite of C<encode>: expects a JSON text and tries to parse it,
 returning the resulting simple scalar or reference. Croaks on error.
 
-JSON numbers and strings become simple Perl scalars. JSON arrays become
-Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
-C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
-
 =item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
 
 This works like the C<decode> method, but instead of raising an exception
@@ -692,8 +675,7 @@
 so far.
 
 This is useful if your JSON texts are not delimited by an outer protocol
-(which is not the brightest thing to do in the first place) and you need
-to know where the JSON text ends.
+and you need to know where the JSON text ends.
 
    JSON::XS->new->decode_prefix ("[1] the tail")
    => ([], 3)
@@ -715,8 +697,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.
@@ -742,7 +724,7 @@
 exactly I<one> JSON object. If that is successful, it will return this
 object, otherwise it will return C<undef>. If there is a parse error,
 this method will croak just as C<decode> would do (one can then use
-C<incr_skip> to skip the errornous part). This is the most common way of
+C<incr_skip> to skip the erroneous part). This is the most common way of
 using the method.
 
 And finally, in list context, it will try to extract as many objects
@@ -753,6 +735,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
@@ -776,7 +763,7 @@
 parse state.
 
 The difference to C<incr_reset> is that only text until the parse error
-occured is removed.
+occurred is removed.
 
 =item $json->incr_reset
 
@@ -792,10 +779,10 @@
 =head2 LIMITATIONS
 
 All options that affect decoding are supported, except
-C<allow_nonref>. The reason for this is that it cannot be made to
-work sensibly: JSON objects and arrays are self-delimited, i.e. you can concatenate
-them back to back and still decode them perfectly. This does not hold true
-for JSON numbers, however.
+C<allow_nonref>. The reason for this is that it cannot be made to work
+sensibly: JSON objects and arrays are self-delimited, i.e. you can
+concatenate them back to back and still decode them perfectly. This does
+not hold true for JSON numbers, however.
 
 For example, is the string C<1> a single JSON number, or is it simply the
 start of C<12>? Or is C<12> a single JSON number, or the concatenation
@@ -984,13 +971,18 @@
 a numeric (floating point) value if that is possible without loss of
 precision. Otherwise it will preserve the number as a string value (in
 which case you lose roundtripping ability, as the JSON number will be
-re-encoded toa JSON string).
+re-encoded to a JSON string).
 
 Numbers containing a fractional or exponential part will always be
 represented as numeric (floating point) values, possibly at a loss of
 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 least significant bit.
+
 =item true, false
 
 These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
@@ -1015,15 +1007,13 @@
 
 =item hash references
 
-Perl hash references become JSON objects. As there is no inherent ordering
-in hash keys (or JSON objects), they will usually be encoded in a
-pseudo-random order that can change between runs of the same program but
-stays generally the same within a single run of a program. JSON::XS can
-optionally sort the hash keys (determined by the I<canonical> flag), so
-the same datastructure will serialise to the same JSON text (given same
-settings and version of JSON::XS), but this incurs a runtime overhead
-and is only rarely useful, e.g. when you want to compare some JSON text
-against another for equality.
+Perl hash references become JSON objects. As there is no inherent
+ordering in hash keys (or JSON objects), they will usually be encoded
+in a pseudo-random order. JSON::XS can optionally sort the hash keys
+(determined by the I<canonical> flag), so the same datastructure will
+serialise to the same JSON text (given same settings and version of
+JSON::XS), but this incurs a runtime overhead and is only rarely useful,
+e.g. when you want to compare some JSON text against another for equality.
 
 =item array references
 
@@ -1087,6 +1077,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
 
 
@@ -1122,7 +1119,7 @@
 When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
 and expect Unicode strings, that is, characters with high ordinal Unicode
 values (> 255) will be encoded as such characters, and likewise such
-characters are decoded as-is, no canges to them will be done, except
+characters are decoded as-is, no changes to them will be done, except
 "(re-)interpreting" them as Unicode codepoints or Unicode characters,
 respectively (to Perl, these are the same thing in strings unless you do
 funny/weird/dumb stuff).
@@ -1240,7 +1237,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.:
@@ -1248,7 +1245,7 @@
    $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
 
 This works because C<__proto__> is not valid outside of strings, so every
-occurence of C<"__proto__"\s*:> must be a string used as property name.
+occurrence of C<"__proto__"\s*:> must be a string used as property name.
 
 If you know of other incompatibilities, please let me know.
 
@@ -1304,10 +1301,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 +1427,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 correctly (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