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.62 by root, Thu Oct 11 22:52:52 2007 UTC vs.
Revision 1.66 by root, Sun Oct 14 20:02:57 2007 UTC

1=encoding utf-8
2
3=head1 NAME 1=head1 NAME
4 2
5JSON::XS - JSON serialising/deserialising, done correctly and fast 3JSON::XS - JSON serialising/deserialising, done correctly and fast
6 4
7JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ 5JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
… …
86 84
87package JSON::XS; 85package JSON::XS;
88 86
89use strict; 87use strict;
90 88
91our $VERSION = '1.5'; 89our $VERSION = '1.51';
92our @ISA = qw(Exporter); 90our @ISA = qw(Exporter);
93 91
94our @EXPORT = qw(to_json from_json); 92our @EXPORT = qw(to_json from_json);
95 93
96use Exporter; 94use Exporter;
… …
103 101
104=over 4 102=over 4
105 103
106=item $json_text = to_json $perl_scalar 104=item $json_text = to_json $perl_scalar
107 105
108Converts the given Perl data structure (a simple scalar or a reference to 106Converts the given Perl data structure to a UTF-8 encoded, binary string
109a hash or array) to a UTF-8 encoded, binary string (that is, the string contains 107(that is, the string contains octets only). Croaks on error.
110octets only). Croaks on error.
111 108
112This function call is functionally identical to: 109This function call is functionally identical to:
113 110
114 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 111 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
115 112
116except being faster. 113except being faster.
117 114
118=item $perl_scalar = from_json $json_text 115=item $perl_scalar = from_json $json_text
119 116
120The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to 117The opposite of C<to_json>: expects an UTF-8 (binary) string and tries
121parse that as an UTF-8 encoded JSON text, returning the resulting simple 118to parse that as an UTF-8 encoded JSON text, returning the resulting
122scalar or reference. Croaks on error. 119reference. Croaks on error.
123 120
124This function call is functionally identical to: 121This function call is functionally identical to:
125 122
126 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 123 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
127 124
… …
135 132
136See MAPPING, below, for more information on how JSON values are mapped to 133See MAPPING, below, for more information on how JSON values are mapped to
137Perl. 134Perl.
138 135
139=back 136=back
137
138
139=head1 A FEW NOTES ON UNICODE AND PERL
140
141Since this often leads to confusion, here are a few very clear words on
142how Unicode works in Perl, modulo bugs.
143
144=over 4
145
146=item 1. Perl strings can store characters with ordinal values > 255.
147
148This enables you to store unicode characters as single characters in a
149Perl string - very natural.
150
151=item 2. Perl does I<not> associate an encoding with your strings.
152
153Unless you force it to, e.g. when matching it against a regex, or printing
154the scalar to a file, in which case Perl either interprets your string as
155locale-encoded text, octets/binary, or as Unicode, depending on various
156settings. In no case is an encoding stored together with your data, it is
157I<use> that decides encoding, not any magical metadata.
158
159=item 3. The internal utf-8 flag has no meaning with regards to the
160encoding of your string.
161
162Just ignore that flag unless you debug a Perl bug, a module written in
163XS or want to dive into the internals of perl. Otherwise it will only
164confuse you, as, despite the name, it says nothing about how your string
165is encoded. You can have unicode strings with that flag set, with that
166flag clear, and you can have binary data with that flag set and that flag
167clear. Other possibilities exist, too.
168
169If you didn't know about that flag, just the better, pretend it doesn't
170exist.
171
172=item 4. A "Unicode String" is simply a string where each character can be
173validly interpreted as a Unicode codepoint.
174
175If you have UTF-8 encoded data, it is no longer a Unicode string, but a
176Unicode string encoded in UTF-8, giving you a binary string.
177
178=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
179
180Its a fact. Learn to live with it.
181
182=back
183
184I hope this helps :)
140 185
141 186
142=head1 OBJECT-ORIENTED INTERFACE 187=head1 OBJECT-ORIENTED INTERFACE
143 188
144The object oriented interface lets you configure your own encoding or 189The object oriented interface lets you configure your own encoding or
… …
931design bugs, but it is still you who will have to deal with it, as major 976design bugs, but it is still you who will have to deal with it, as major
932browser developers care only for features, not about doing security 977browser developers care only for features, not about doing security
933right). 978right).
934 979
935 980
981=head1 THREADS
982
983This module is I<not> guarenteed to be thread safe and there are no
984plans to change this until Perl gets thread support (as opposed to the
985horribly slow so-called "threads" which are simply slow and bloated
986process simulations - use fork, its I<much> faster, cheaper, better).
987
988(It might actually work, but you ahve ben warned).
989
990
936=head1 BUGS 991=head1 BUGS
937 992
938While the goal of this module is to be correct, that unfortunately does 993While the goal of this module is to be correct, that unfortunately does
939not mean its bug-free, only that I think its design is bug-free. It is 994not mean its bug-free, only that I think its design is bug-free. It is
940still relatively early in its development. If you keep reporting bugs they 995still relatively early in its development. If you keep reporting bugs they
941will be fixed swiftly, though. 996will be fixed swiftly, though.
997
998Please refrain from using rt.cpan.org or any other bug reporting
999service. I put the contact address into my modules for a reason.
942 1000
943=cut 1001=cut
944 1002
945our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" }; 1003our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
946our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" }; 1004our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };

Diff Legend

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