ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.160 by root, Wed Nov 16 18:08:30 2016 UTC vs.
Revision 1.165 by root, Tue Sep 5 13:07:09 2017 UTC

… …
40Beginning with version 2.0 of the JSON module, when both JSON and 40Beginning with version 2.0 of the JSON module, when both JSON and
41JSON::XS are installed, then JSON will fall back on JSON::XS (this can be 41JSON::XS are installed, then JSON will fall back on JSON::XS (this can be
42overridden) with no overhead due to emulation (by inheriting constructor 42overridden) with no overhead due to emulation (by inheriting constructor
43and methods). If JSON::XS is not available, it will fall back to the 43and methods). If JSON::XS is not available, it will fall back to the
44compatible JSON::PP module as backend, so using JSON instead of JSON::XS 44compatible JSON::PP module as backend, so using JSON instead of JSON::XS
45gives you a portable JSON API that can be fast when you need and doesn't 45gives you a portable JSON API that can be fast when you need it and
46require a C compiler when that is a problem. 46doesn't require a C compiler when that is a problem.
47 47
48As this is the n-th-something JSON module on CPAN, what was the reason 48As this is the n-th-something JSON module on CPAN, what was the reason
49to write yet another JSON module? While it seems there are many JSON 49to write yet another JSON module? While it seems there are many JSON
50modules, none of them correctly handle all corner cases, and in most cases 50modules, none of them correctly handle all corner cases, and in most cases
51their maintainers are unresponsive, gone missing, or not listening to bug 51their maintainers are unresponsive, gone missing, or not listening to bug
… …
101 101
102package JSON::XS; 102package JSON::XS;
103 103
104use common::sense; 104use common::sense;
105 105
106our $VERSION = 3.02; 106our $VERSION = 3.04;
107our @ISA = qw(Exporter); 107our @ISA = qw(Exporter);
108 108
109our @EXPORT = qw(encode_json decode_json); 109our @EXPORT = qw(encode_json decode_json);
110 110
111use Exporter; 111use Exporter;
… …
131 131
132Except being faster. 132Except being faster.
133 133
134=item $perl_scalar = decode_json $json_text 134=item $perl_scalar = decode_json $json_text
135 135
136The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries 136The opposite of C<encode_json>: expects a UTF-8 (binary) string and tries
137to parse that as an UTF-8 encoded JSON text, returning the resulting 137to parse that as a UTF-8 encoded JSON text, returning the resulting
138reference. Croaks on error. 138reference. Croaks on error.
139 139
140This function call is functionally identical to: 140This function call is functionally identical to:
141 141
142 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 142 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
… …
270 270
271=item $enabled = $json->get_utf8 271=item $enabled = $json->get_utf8
272 272
273If C<$enable> is true (or missing), then the C<encode> method will encode 273If C<$enable> is true (or missing), then the C<encode> method will encode
274the JSON result into UTF-8, as required by many protocols, while the 274the JSON result into UTF-8, as required by many protocols, while the
275C<decode> method expects to be handled an UTF-8-encoded string. Please 275C<decode> method expects to be handed a UTF-8-encoded string. Please
276note that UTF-8-encoded strings do not contain any characters outside the 276note that UTF-8-encoded strings do not contain any characters outside the
277range C<0..255>, they are thus useful for bytewise/binary I/O. In future 277range C<0..255>, they are thus useful for bytewise/binary I/O. In future
278versions, enabling this option might enable autodetection of the UTF-16 278versions, enabling this option might enable autodetection of the UTF-16
279and UTF-32 encoding families, as described in RFC4627. 279and UTF-32 encoding families, as described in RFC4627.
280 280
… …
1289expect your input strings to be encoded as UTF-8, that is, no "character" 1289expect your input strings to be encoded as UTF-8, that is, no "character"
1290of the input string must have any value > 255, as UTF-8 does not allow 1290of the input string must have any value > 255, as UTF-8 does not allow
1291that. 1291that.
1292 1292
1293The C<utf8> flag therefore switches between two modes: disabled means you 1293The C<utf8> flag therefore switches between two modes: disabled means you
1294will get a Unicode string in Perl, enabled means you get an UTF-8 encoded 1294will get a Unicode string in Perl, enabled means you get a UTF-8 encoded
1295octet/binary string in Perl. 1295octet/binary string in Perl.
1296 1296
1297=item C<latin1> or C<ascii> flags enabled 1297=item C<latin1> or C<ascii> flags enabled
1298 1298
1299With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters 1299With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters
… …
1696->allow_nonref(0) >> even if this is the current default, if they cannot 1696->allow_nonref(0) >> even if this is the current default, if they cannot
1697handle non-reference values, in preparation for the day when the default 1697handle non-reference values, in preparation for the day when the default
1698will change. 1698will change.
1699 1699
1700 1700
1701=head1 THREADS 1701=head1 (I-)THREADS
1702 1702
1703This module is I<not> guaranteed to be thread safe and there are no 1703This module is I<not> guaranteed to be ithread (or MULTIPLICITY-) safe
1704plans to change this until Perl gets thread support (as opposed to the 1704and there are no plans to change this. Note that perl's builtin so-called
1705horribly slow so-called "threads" which are simply slow and bloated 1705theeads/ithreads are officially deprecated and should not be used.
1706process simulations - use fork, it's I<much> faster, cheaper, better).
1707
1708(It might actually work, but you have been warned).
1709 1706
1710 1707
1711=head1 THE PERILS OF SETLOCALE 1708=head1 THE PERILS OF SETLOCALE
1712 1709
1713Sometimes people avoid the Perl locale support and directly call the 1710Sometimes people avoid the Perl locale support and directly call the

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines