[ViewVC] Diff of: cvs/JSON-XS/README

Comparing JSON-XS/README (file contents):
Revision 1.5 by root, Sat Mar 24 01:15:22 2007 UTC vs.
Revision 1.10 by root, Wed Apr 4 00:01:44 2007 UTC

…		…
2	JSON::XS - JSON serialising/deserialising, done correctly and fast	2	JSON::XS - JSON serialising/deserialising, done correctly and fast
3		3
4	SYNOPSIS	4	SYNOPSIS
5	use JSON::XS;	5	use JSON::XS;
6		6
7	# exported functions, croak on error	7	# exported functions, they croak on error
		8	# and expect/generate UTF-8
8		9
9	$utf8_encoded_json_text = to_json $perl_hash_or_arrayref;	10	$utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
10	$perl_hash_or_arrayref = from_json $utf8_encoded_json_text;	11	$perl_hash_or_arrayref = from_json $utf8_encoded_json_text;
11		12
		13	# objToJson and jsonToObj aliases to to_json and from_json
		14	# are exported for compatibility to the JSON module,
		15	# but should not be used in new code.
		16
12	# oo-interface	17	# OO-interface
13		18
14	$coder = JSON::XS->new->ascii->pretty->allow_nonref;	19	$coder = JSON::XS->new->ascii->pretty->allow_nonref;
15	$pretty_printed_unencoded = $coder->encode ($perl_scalar);	20	$pretty_printed_unencoded = $coder->encode ($perl_scalar);
16	$perl_scalar = $coder->decode ($unicode_json_text);	21	$perl_scalar = $coder->decode ($unicode_json_text);
17		22
…		…
30		35
31	See MAPPING, below, on how JSON::XS maps perl values to JSON values and	36	See MAPPING, below, on how JSON::XS maps perl values to JSON values and
32	vice versa.	37	vice versa.
33		38
34	FEATURES	39	FEATURES
35	* correct handling of unicode issues	40	* correct unicode handling
36	This module knows how to handle Unicode, and even documents how and	41	This module knows how to handle Unicode, and even documents how and
37	when it does so.	42	when it does so.
38		43
39	* round-trip integrity	44	* round-trip integrity
40	When you serialise a perl data structure using only datatypes	45	When you serialise a perl data structure using only datatypes
41	supported by JSON, the deserialised data structure is identical on	46	supported by JSON, the deserialised data structure is identical on
42	the Perl level. (e.g. the string "2.0" doesn't suddenly become "2").	47	the Perl level. (e.g. the string "2.0" doesn't suddenly become "2"
		48	just because it looks like a number).
43		49
44	* strict checking of JSON correctness	50	* strict checking of JSON correctness
45	There is no guessing, no generating of illegal JSON strings by	51	There is no guessing, no generating of illegal JSON texts by
46	default, and only JSON is accepted as input by default (the latter	52	default, and only JSON is accepted as input by default (the latter
47	is a security feature).	53	is a security feature).
48		54
49	* fast	55	* fast
50	Compared to other JSON modules, this module compares favourably in	56	Compared to other JSON modules, this module compares favourably in
…		…
55	interface.	61	interface.
56		62
57	* reasonably versatile output formats	63	* reasonably versatile output formats
58	You can choose between the most compact guarenteed single-line	64	You can choose between the most compact guarenteed single-line
59	format possible (nice for simple line-based protocols), a pure-ascii	65	format possible (nice for simple line-based protocols), a pure-ascii
60	format (for when your transport is not 8-bit clean), or a	66	format (for when your transport is not 8-bit clean, still supports
61	pretty-printed format (for when you want to read that stuff). Or you	67	the whole unicode range), or a pretty-printed format (for when you
62	can combine those features in whatever way you like.	68	want to read that stuff). Or you can combine those features in
		69	whatever way you like.
63		70
64	FUNCTIONAL INTERFACE	71	FUNCTIONAL INTERFACE
65	The following convinience methods are provided by this module. They are	72	The following convinience methods are provided by this module. They are
66	exported by default:	73	exported by default:
67		74
68	$json_string = to_json $perl_scalar	75	$json_text = to_json $perl_scalar
69	Converts the given Perl data structure (a simple scalar or a	76	Converts the given Perl data structure (a simple scalar or a
70	reference to a hash or array) to a UTF-8 encoded, binary string	77	reference to a hash or array) to a UTF-8 encoded, binary string
71	(that is, the string contains octets only). Croaks on error.	78	(that is, the string contains octets only). Croaks on error.
72		79
73	This function call is functionally identical to	80	This function call is functionally identical to:
		81
74	"JSON::XS->new->utf8->encode ($perl_scalar)".	82	$json_text = JSON::XS->new->utf8->encode ($perl_scalar)
75		83
		84	except being faster.
		85
76	$perl_scalar = from_json $json_string	86	$perl_scalar = from_json $json_text
77	The opposite of "to_json": expects an UTF-8 (binary) string and	87	The opposite of "to_json": expects an UTF-8 (binary) string and
78	tries to parse that as an UTF-8 encoded JSON string, returning the	88	tries to parse that as an UTF-8 encoded JSON text, returning the
79	resulting simple scalar or reference. Croaks on error.	89	resulting simple scalar or reference. Croaks on error.
80		90
81	This function call is functionally identical to	91	This function call is functionally identical to:
		92
82	"JSON::XS->new->utf8->decode ($json_string)".	93	$perl_scalar = JSON::XS->new->utf8->decode ($json_text)
		94
		95	except being faster.
83		96
84	OBJECT-ORIENTED INTERFACE	97	OBJECT-ORIENTED INTERFACE
85	The object oriented interface lets you configure your own encoding or	98	The object oriented interface lets you configure your own encoding or
86	decoding style, within the limits of supported formats.	99	decoding style, within the limits of supported formats.
87		100
…		…
91	disabled.	104	disabled.
92		105
93	The mutators for flags all return the JSON object again and thus	106	The mutators for flags all return the JSON object again and thus
94	calls can be chained:	107	calls can be chained:
95		108
96	my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]})	109	my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
97	=> {"a": [1, 2]}	110	=> {"a": [1, 2]}
98		111
99	$json = $json->ascii ([$enable])	112	$json = $json->ascii ([$enable])
100	If $enable is true (or missing), then the "encode" method will not	113	If $enable is true (or missing), then the "encode" method will not
101	generate characters outside the code range 0..127. Any unicode	114	generate characters outside the code range 0..127 (which is ASCII).
102	characters outside that range will be escaped using either a single	115	Any unicode characters outside that range will be escaped using
103	\uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,	116	either a single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL
104	as per RFC4627.	117	escape sequence, as per RFC4627.
105		118
106	If $enable is false, then the "encode" method will not escape	119	If $enable is false, then the "encode" method will not escape
107	Unicode characters unless necessary.	120	Unicode characters unless required by the JSON syntax. This results
		121	in a faster and more compact format.
108		122
109	JSON::XS->new->ascii (1)->encode (chr 0x10401)	123	JSON::XS->new->ascii (1)->encode ([chr 0x10401])
110	=> \ud801\udc01	124	=> ["\ud801\udc01"]
111		125
112	$json = $json->utf8 ([$enable])	126	$json = $json->utf8 ([$enable])
113	If $enable is true (or missing), then the "encode" method will	127	If $enable is true (or missing), then the "encode" method will
114	encode the JSON string into UTF-8, as required by many protocols,	128	encode the JSON result into UTF-8, as required by many protocols,
115	while the "decode" method expects to be handled an UTF-8-encoded	129	while the "decode" method expects to be handled an UTF-8-encoded
116	string. Please note that UTF-8-encoded strings do not contain any	130	string. Please note that UTF-8-encoded strings do not contain any
117	characters outside the range 0..255, they are thus useful for	131	characters outside the range 0..255, they are thus useful for
118	bytewise/binary I/O.	132	bytewise/binary I/O. In future versions, enabling this option might
		133	enable autodetection of the UTF-16 and UTF-32 encoding families, as
		134	described in RFC4627.
119		135
120	If $enable is false, then the "encode" method will return the JSON	136	If $enable is false, then the "encode" method will return the JSON
121	string as a (non-encoded) unicode string, while "decode" expects	137	string as a (non-encoded) unicode string, while "decode" expects
122	thus a unicode string. Any decoding or encoding (e.g. to UTF-8 or	138	thus a unicode string. Any decoding or encoding (e.g. to UTF-8 or
123	UTF-16) needs to be done yourself, e.g. using the Encode module.	139	UTF-16) needs to be done yourself, e.g. using the Encode module.
124		140
125	Example, output UTF-16-encoded JSON:	141	Example, output UTF-16BE-encoded JSON:
		142
		143	use Encode;
		144	$jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
		145
		146	Example, decode UTF-32LE-encoded JSON:
		147
		148	use Encode;
		149	$object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
126		150
127	$json = $json->pretty ([$enable])	151	$json = $json->pretty ([$enable])
128	This enables (or disables) all of the "indent", "space_before" and	152	This enables (or disables) all of the "indent", "space_before" and
129	"space_after" (and in the future possibly more) flags in one call to	153	"space_after" (and in the future possibly more) flags in one call to
130	generate the most readable (or most compact) form possible.	154	generate the most readable (or most compact) form possible.
…		…
145	multiline format as output, putting every array member or	169	multiline format as output, putting every array member or
146	object/hash key-value pair into its own line, identing them	170	object/hash key-value pair into its own line, identing them
147	properly.	171	properly.
148		172
149	If $enable is false, no newlines or indenting will be produced, and	173	If $enable is false, no newlines or indenting will be produced, and
150	the resulting JSON strings is guarenteed not to contain any	174	the resulting JSON text is guarenteed not to contain any "newlines".
151	"newlines".
152		175
153	This setting has no effect when decoding JSON strings.	176	This setting has no effect when decoding JSON texts.
154		177
155	$json = $json->space_before ([$enable])	178	$json = $json->space_before ([$enable])
156	If $enable is true (or missing), then the "encode" method will add	179	If $enable is true (or missing), then the "encode" method will add
157	an extra optional space before the ":" separating keys from values	180	an extra optional space before the ":" separating keys from values
158	in JSON objects.	181	in JSON objects.
159		182
160	If $enable is false, then the "encode" method will not add any extra	183	If $enable is false, then the "encode" method will not add any extra
161	space at those places.	184	space at those places.
162		185
163	This setting has no effect when decoding JSON strings. You will also	186	This setting has no effect when decoding JSON texts. You will also
164	most likely combine this setting with "space_after".	187	most likely combine this setting with "space_after".
165		188
166	Example, space_before enabled, space_after and indent disabled:	189	Example, space_before enabled, space_after and indent disabled:
167		190
168	{"key" :"value"}	191	{"key" :"value"}
…		…
174	pairs and array members.	197	pairs and array members.
175		198
176	If $enable is false, then the "encode" method will not add any extra	199	If $enable is false, then the "encode" method will not add any extra
177	space at those places.	200	space at those places.
178		201
179	This setting has no effect when decoding JSON strings.	202	This setting has no effect when decoding JSON texts.
180		203
181	Example, space_before and indent disabled, space_after enabled:	204	Example, space_before and indent disabled, space_after enabled:
182		205
183	{"key": "value"}	206	{"key": "value"}
184		207
…		…
190	If $enable is false, then the "encode" method will output key-value	213	If $enable is false, then the "encode" method will output key-value
191	pairs in the order Perl stores them (which will likely change	214	pairs in the order Perl stores them (which will likely change
192	between runs of the same script).	215	between runs of the same script).
193		216
194	This option is useful if you want the same data structure to be	217	This option is useful if you want the same data structure to be
195	encoded as the same JSON string (given the same overall settings).	218	encoded as the same JSON text (given the same overall settings). If
196	If it is disabled, the same hash migh be encoded differently even if	219	it is disabled, the same hash migh be encoded differently even if
197	contains the same data, as key-value pairs have no inherent ordering	220	contains the same data, as key-value pairs have no inherent ordering
198	in Perl.	221	in Perl.
199		222
200	This setting has no effect when decoding JSON strings.	223	This setting has no effect when decoding JSON texts.
201		224
202	$json = $json->allow_nonref ([$enable])	225	$json = $json->allow_nonref ([$enable])
203	If $enable is true (or missing), then the "encode" method can	226	If $enable is true (or missing), then the "encode" method can
204	convert a non-reference into its corresponding string, number or	227	convert a non-reference into its corresponding string, number or
205	null JSON value, which is an extension to RFC4627. Likewise,	228	null JSON value, which is an extension to RFC4627. Likewise,
206	"decode" will accept those JSON values instead of croaking.	229	"decode" will accept those JSON values instead of croaking.
207		230
208	If $enable is false, then the "encode" method will croak if it isn't	231	If $enable is false, then the "encode" method will croak if it isn't
209	passed an arrayref or hashref, as JSON strings must either be an	232	passed an arrayref or hashref, as JSON texts must either be an
210	object or array. Likewise, "decode" will croak if given something	233	object or array. Likewise, "decode" will croak if given something
211	that is not a JSON object or array.	234	that is not a JSON object or array.
212		235
213	Example, encode a Perl scalar as JSON value with enabled	236	Example, encode a Perl scalar as JSON value with enabled
214	"allow_nonref", resulting in an invalid JSON text:	237	"allow_nonref", resulting in an invalid JSON text:
…		…
218		241
219	$json = $json->shrink ([$enable])	242	$json = $json->shrink ([$enable])
220	Perl usually over-allocates memory a bit when allocating space for	243	Perl usually over-allocates memory a bit when allocating space for
221	strings. This flag optionally resizes strings generated by either	244	strings. This flag optionally resizes strings generated by either
222	"encode" or "decode" to their minimum size possible. This can save	245	"encode" or "decode" to their minimum size possible. This can save
223	memory when your JSON strings are either very very long or you have	246	memory when your JSON texts are either very very long or you have
224	many short strings. It will also try to downgrade any strings to	247	many short strings. It will also try to downgrade any strings to
225	octet-form if possible: perl stores strings internally either in an	248	octet-form if possible: perl stores strings internally either in an
226	encoding called UTF-X or in octet-form. The latter cannot store	249	encoding called UTF-X or in octet-form. The latter cannot store
227	everything but uses less space in general.	250	everything but uses less space in general (and some buggy Perl or C
		251	code might even rely on that internal representation being used).
		252
		253	The actual definition of what shrink does might change in future
		254	versions, but it will always try to save space at the expense of
		255	time.
228		256
229	If $enable is true (or missing), the string returned by "encode"	257	If $enable is true (or missing), the string returned by "encode"
230	will be shrunk-to-fit, while all strings generated by "decode" will	258	will be shrunk-to-fit, while all strings generated by "decode" will
231	also be shrunk-to-fit.	259	also be shrunk-to-fit.
232		260
…		…
236	In the future, this setting might control other things, such as	264	In the future, this setting might control other things, such as
237	converting strings that look like integers or floats into integers	265	converting strings that look like integers or floats into integers
238	or floats internally (there is no difference on the Perl level),	266	or floats internally (there is no difference on the Perl level),
239	saving space.	267	saving space.
240		268
		269	$json = $json->max_depth ([$maximum_nesting_depth])
		270	Sets the maximum nesting level (default 512) accepted while encoding
		271	or decoding. If the JSON text or Perl data structure has an equal or
		272	higher nesting level then this limit, then the encoder and decoder
		273	will stop and croak at that point.
		274
		275	Nesting level is defined by number of hash- or arrayrefs that the
		276	encoder needs to traverse to reach a given point or the number of
		277	"{" or "[" characters without their matching closing parenthesis
		278	crossed to reach a given character in a string.
		279
		280	Setting the maximum depth to one disallows any nesting, so that
		281	ensures that the object is only a single hash/object or array.
		282
		283	The argument to "max_depth" will be rounded up to the next nearest
		284	power of two.
		285
		286	See SECURITY CONSIDERATIONS, below, for more info on why this is
		287	useful.
		288
241	$json_string = $json->encode ($perl_scalar)	289	$json_text = $json->encode ($perl_scalar)
242	Converts the given Perl data structure (a simple scalar or a	290	Converts the given Perl data structure (a simple scalar or a
243	reference to a hash or array) to its JSON representation. Simple	291	reference to a hash or array) to its JSON representation. Simple
244	scalars will be converted into JSON string or number sequences,	292	scalars will be converted into JSON string or number sequences,
245	while references to arrays become JSON arrays and references to	293	while references to arrays become JSON arrays and references to
246	hashes become JSON objects. Undefined Perl values (e.g. "undef")	294	hashes become JSON objects. Undefined Perl values (e.g. "undef")
247	become JSON "null" values. Neither "true" nor "false" values will be	295	become JSON "null" values. Neither "true" nor "false" values will be
248	generated.	296	generated.
249		297
250	$perl_scalar = $json->decode ($json_string)	298	$perl_scalar = $json->decode ($json_text)
251	The opposite of "encode": expects a JSON string and tries to parse	299	The opposite of "encode": expects a JSON text and tries to parse it,
252	it, returning the resulting simple scalar or reference. Croaks on	300	returning the resulting simple scalar or reference. Croaks on error.
253	error.
254		301
255	JSON numbers and strings become simple Perl scalars. JSON arrays	302	JSON numbers and strings become simple Perl scalars. JSON arrays
256	become Perl arrayrefs and JSON objects become Perl hashrefs. "true"	303	become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
257	becomes 1, "false" becomes 0 and "null" becomes "undef".	304	becomes 1, "false" becomes 0 and "null" becomes "undef".
258		305
…		…
302	truly typeless language, so we can only guess which JSON type is meant	349	truly typeless language, so we can only guess which JSON type is meant
303	by a Perl value.	350	by a Perl value.
304		351
305	hash references	352	hash references
306	Perl hash references become JSON objects. As there is no inherent	353	Perl hash references become JSON objects. As there is no inherent
307	ordering in hash keys, they will usually be encoded in a	354	ordering in hash keys (or JSON objects), they will usually be
308	pseudo-random order that can change between runs of the same program	355	encoded in a pseudo-random order that can change between runs of the
309	but stays generally the same within a single run of a program.	356	same program but stays generally the same within a single run of a
310	JSON::XS can optionally sort the hash keys (determined by the	357	program. JSON::XS can optionally sort the hash keys (determined by
311	canonical flag), so the same datastructure will serialise to the	358	the canonical flag), so the same datastructure will serialise to
312	same JSON text (given same settings and version of JSON::XS), but	359	the same JSON text (given same settings and version of JSON::XS),
313	this incurs a runtime overhead.	360	but this incurs a runtime overhead and is only rarely useful, e.g.
		361	when you want to compare some JSON text against another for
		362	equality.
314		363
315	array references	364	array references
316	Perl array references become JSON arrays.	365	Perl array references become JSON arrays.
		366
		367	other references
		368	Other unblessed references are generally not allowed and will cause
		369	an exception to be thrown, except for references to the integers 0
		370	and 1, which get turned into "false" and "true" atoms in JSON. You
		371	can also use "JSON::XS::false" and "JSON::XS::true" to improve
		372	readability.
		373
		374	to_json [\0,JSON::XS::true] # yields [false,true]
317		375
318	blessed objects	376	blessed objects
319	Blessed objects are not allowed. JSON::XS currently tries to encode	377	Blessed objects are not allowed. JSON::XS currently tries to encode
320	their underlying representation (hash- or arrayref), but this	378	their underlying representation (hash- or arrayref), but this
321	behaviour might change in future versions.	379	behaviour might change in future versions.
…		…
353	$x *= 1; # same thing, the choise is yours.	411	$x *= 1; # same thing, the choise is yours.
354		412
355	You can not currently output JSON booleans or force the type in	413	You can not currently output JSON booleans or force the type in
356	other, less obscure, ways. Tell me if you need this capability.	414	other, less obscure, ways. Tell me if you need this capability.
357		415
358	circular data structures
359	Those will be encoded until memory or stackspace runs out.
360
361	COMPARISON	416	COMPARISON
362	As already mentioned, this module was created because none of the	417	As already mentioned, this module was created because none of the
363	existing JSON modules could be made to work correctly. First I will	418	existing JSON modules could be made to work correctly. First I will
364	describe the problems (or pleasures) I encountered with various existing	419	describe the problems (or pleasures) I encountered with various existing
365	JSON modules, followed by some benchmark values. JSON::XS was designed	420	JSON modules, followed by some benchmark values. JSON::XS was designed
…		…
386		441
387	Has problems handling many Perl values (e.g. regex results and other	442	Has problems handling many Perl values (e.g. regex results and other
388	magic values will make it croak).	443	magic values will make it croak).
389		444
390	Does not even generate valid JSON ("{1,2}" gets converted to "{1:2}"	445	Does not even generate valid JSON ("{1,2}" gets converted to "{1:2}"
391	which is not a valid JSON string.	446	which is not a valid JSON text.
392		447
393	Unmaintained (maintainer unresponsive for many months, bugs are not	448	Unmaintained (maintainer unresponsive for many months, bugs are not
394	getting fixed).	449	getting fixed).
395		450
396	JSON::Syck 0.21	451	JSON::Syck 0.21
397	Very buggy (often crashes).	452	Very buggy (often crashes).
398		453
399	Very inflexible (no human-readable format supported, format pretty	454	Very inflexible (no human-readable format supported, format pretty
400	much undocumented. I need at least a format for easy reading by	455	much undocumented. I need at least a format for easy reading by
401	humans and a single-line compact format for use in a protocol, and	456	humans and a single-line compact format for use in a protocol, and
402	preferably a way to generate ASCII-only JSON strings).	457	preferably a way to generate ASCII-only JSON texts).
403		458
404	Completely broken (and confusingly documented) Unicode handling	459	Completely broken (and confusingly documented) Unicode handling
405	(unicode escapes are not working properly, you need to set	460	(unicode escapes are not working properly, you need to set
406	ImplicitUnicode to different values on en- and decoding to get	461	ImplicitUnicode to different values on en- and decoding to get
407	symmetric behaviour).	462	symmetric behaviour).
…		…
430		485
431	Very inflexible.	486	Very inflexible.
432		487
433	No roundtripping.	488	No roundtripping.
434		489
435	Does not generate valid JSON (key strings are often unquoted, empty	490	Does not generate valid JSON texts (key strings are often unquoted,
436	keys result in nothing being output)	491	empty keys result in nothing being output)
437		492
438	Does not check input for validity.	493	Does not check input for validity.
439		494
440	SPEED	495	SPEED
441	It seems that JSON::XS is surprisingly fast, as shown in the following	496	It seems that JSON::XS is surprisingly fast, as shown in the following
442	tables. They have been generated with the help of the "eg/bench" program	497	tables. They have been generated with the help of the "eg/bench" program
443	in the JSON::XS distribution, to make it easy to compare on your own	498	in the JSON::XS distribution, to make it easy to compare on your own
444	system.	499	system.
445		500
446	First comes a comparison between various modules using a very short JSON	501	First comes a comparison between various modules using a very short JSON
447	string (83 bytes), showing the number of encodes/decodes per second	502	string:
448	(JSON::XS is the functional interface, while JSON::XS/2 is the OO	503
		504	{"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
		505
		506	It shows the number of encodes/decodes per second (JSON::XS uses the
		507	functional interface, while JSON::XS/2 uses the OO interface with
449	interface with pretty-printing and hashkey sorting enabled). Higher is	508	pretty-printing and hashkey sorting enabled). Higher is better:
450	better:
451		509
452	module \| encode \| decode \|	510	module \| encode \| decode \|
453	-----------\|------------\|------------\|	511	-----------\|------------\|------------\|
454	JSON \| 14006 \| 6820 \|	512	JSON \| 11488.516 \| 7823.035 \|
455	JSON::DWIW \| 200937 \| 120386 \|	513	JSON::DWIW \| 94708.054 \| 129094.260 \|
456	JSON::PC \| 85065 \| 129366 \|	514	JSON::PC \| 63884.157 \| 128528.212 \|
457	JSON::Syck \| 59898 \| 44232 \|	515	JSON::Syck \| 34898.677 \| 42096.911 \|
458	JSON::XS \| 1171478 \| 342435 \|	516	JSON::XS \| 654027.064 \| 396423.669 \|
459	JSON::XS/2 \| 730760 \| 328714 \|	517	JSON::XS/2 \| 371564.190 \| 371725.613 \|
460	-----------+------------+------------+	518	-----------+------------+------------+
461		519
462	That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80	520	That is, JSON::XS is more than six times faster than JSON::DWIW on
		521	encoding, more than three times faster on decoding, and about thirty
463	times faster than JSON, even with pretty-printing and key sorting.	522	times faster than JSON, even with pretty-printing and key sorting.
464		523
465	Using a longer test string (roughly 18KB, generated from Yahoo! Locals	524	Using a longer test string (roughly 18KB, generated from Yahoo! Locals
466	search API (http://nanoref.com/yahooapis/mgPdGg):	525	search API (http://nanoref.com/yahooapis/mgPdGg):
467		526
468	module \| encode \| decode \|	527	module \| encode \| decode \|
469	-----------\|------------\|------------\|	528	-----------\|------------\|------------\|
470	JSON \| 673 \| 38 \|	529	JSON \| 273.023 \| 44.674 \|
471	JSON::DWIW \| 5271 \| 770 \|	530	JSON::DWIW \| 1089.383 \| 1145.704 \|
472	JSON::PC \| 9901 \| 2491 \|	531	JSON::PC \| 3097.419 \| 2393.921 \|
473	JSON::Syck \| 2360 \| 786 \|	532	JSON::Syck \| 514.060 \| 843.053 \|
474	JSON::XS \| 37398 \| 3202 \|	533	JSON::XS \| 6479.668 \| 3636.364 \|
475	JSON::XS/2 \| 13765 \| 3153 \|	534	JSON::XS/2 \| 3774.221 \| 3599.124 \|
476	-----------+------------+------------+	535	-----------+------------+------------+
477		536
478	Again, JSON::XS leads by far in the encoding case, while still beating	537	Again, JSON::XS leads by far.
479	every other module in the decoding case.
480		538
481	On large strings containing lots of unicode characters, some modules	539	On large strings containing lots of high unicode characters, some
482	(such as JSON::PC) decode faster than JSON::XS, but the result will be	540	modules (such as JSON::PC) seem to decode faster than JSON::XS, but the
483	broken due to missing unicode handling. Others refuse to decode or	541	result will be broken due to missing (or wrong) unicode handling. Others
484	encode properly, so it was impossible to prepare a fair comparison table	542	refuse to decode or encode properly, so it was impossible to prepare a
485	for that case.	543	fair comparison table for that case.
486		544
487	RESOURCE LIMITS	545	SECURITY CONSIDERATIONS
488	JSON::XS does not impose any limits on the size of JSON texts or Perl	546	When you are using JSON in a protocol, talking to untrusted potentially
489	values they represent - if your machine can handle it, JSON::XS will	547	hostile creatures requires relatively few measures.
490	encode or decode it. Future versions might optionally impose structure	548
491	depth and memory use resource limits.	549	First of all, your JSON decoder should be secure, that is, should not
		550	have any buffer overflows. Obviously, this module should ensure that and
		551	I am trying hard on making that true, but you never know.
		552
		553	Second, you need to avoid resource-starving attacks. That means you
		554	should limit the size of JSON texts you accept, or make sure then when
		555	your resources run out, thats just fine (e.g. by using a separate
		556	process that can crash safely). The size of a JSON text in octets or
		557	characters is usually a good indication of the size of the resources
		558	required to decode it into a Perl structure.
		559
		560	Third, JSON::XS recurses using the C stack when decoding objects and
		561	arrays. The C stack is a limited resource: for instance, on my amd64
		562	machine with 8MB of stack size I can decode around 180k nested arrays
		563	but only 14k nested JSON objects (due to perl itself recursing deeply on
		564	croak to free the temporary). If that is exceeded, the program crashes.
		565	to be conservative, the default nesting limit is set to 512. If your
		566	process has a smaller stack, you should adjust this setting accordingly
		567	with the "max_depth" method.
		568
		569	And last but least, something else could bomb you that I forgot to think
		570	of. In that case, you get to keep the pieces. I am alway sopen for
		571	hints, though...
492		572
493	BUGS	573	BUGS
494	While the goal of this module is to be correct, that unfortunately does	574	While the goal of this module is to be correct, that unfortunately does
495	not mean its bug-free, only that I think its design is bug-free. It is	575	not mean its bug-free, only that I think its design is bug-free. It is
496	still very young and not well-tested. If you keep reporting bugs they	576	still relatively early in its development. If you keep reporting bugs
497	will be fixed swiftly, though.	577	they will be fixed swiftly, though.
498		578
499	AUTHOR	579	AUTHOR
500	Marc Lehmann <schmorp@schmorp.de>	580	Marc Lehmann <schmorp@schmorp.de>
501	http://home.schmorp.de/	581	http://home.schmorp.de/
502		582

Diff Legend

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

Comparing JSON-XS/README (file contents): Revision 1.5 by root, Sat Mar 24 01:15:22 2007 UTC vs. Revision 1.10 by root, Wed Apr 4 00:01:44 2007 UTC

Diff Legend

Comparing JSON-XS/README (file contents):
Revision 1.5 by root, Sat Mar 24 01:15:22 2007 UTC vs.
Revision 1.10 by root, Wed Apr 4 00:01:44 2007 UTC