--- JSON-XS/XS.pm	2011/08/11 17:06:53	1.137
+++ JSON-XS/XS.pm	2013/10/25 19:53:08	1.141
@@ -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.32';
+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
@@ -742,7 +725,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
@@ -781,7 +764,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
 
@@ -989,7 +972,7 @@
 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
@@ -999,7 +982,7 @@
 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.
+the least significant bit.
 
 =item true, false
 
@@ -1139,7 +1122,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).
@@ -1265,7 +1248,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.
 
@@ -1447,6 +1430,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