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

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.24 by root, Fri Nov 22 16:18:59 2013 UTC vs.
Revision 1.25 by root, Thu Nov 28 12:08:07 2013 UTC

… …
56As for compactness, C<CBOR::XS> encoded data structures are usually about 56As for compactness, C<CBOR::XS> encoded data structures are usually about
5720% smaller than the same data encoded as (compact) JSON or L<Storable>. 5720% smaller than the same data encoded as (compact) JSON or L<Storable>.
58 58
59In addition to the core CBOR data format, this module implements a number 59In addition to the core CBOR data format, this module implements a number
60of extensions, to support cyclic and self-referencing data structures 60of extensions, to support cyclic and self-referencing data structures
61(see C<allow_sharing>), string deduplication (see C<allow_stringref>) and 61(see C<allow_sharing>), string deduplication (see C<pack_strings>) and
62scalar references (always enabled). 62scalar references (always enabled).
63 63
64The primary goal of this module is to be I<correct> and the secondary goal 64The primary goal of this module is to be I<correct> and the secondary goal
65is to be I<fast>. To reach the latter goal it was written in C. 65is to be I<fast>. To reach the latter goal it was written in C.
66 66
… …
186as an array, is referenced multiple times), but instead will emit a 186as an array, is referenced multiple times), but instead will emit a
187reference to the earlier value. 187reference to the earlier value.
188 188
189This means that such values will only be encoded once, and will not result 189This means that such values will only be encoded once, and will not result
190in a deep cloning of the value on decode, in decoders supporting the value 190in a deep cloning of the value on decode, in decoders supporting the value
191sharing extension. 191sharing extension. This also makes it possible to encode cyclic data
192structures.
192 193
193It is recommended to leave it off unless you know your 194It is recommended to leave it off unless you know your
194communication partner supports the value sharing extensions to CBOR 195communication partner supports the value sharing extensions to CBOR
195(http://cbor.schmorp.de/value-sharing). 196(http://cbor.schmorp.de/value-sharing), as without decoder support, the
197resulting data structure might be unusable.
196 198
197Detecting shared values incurs a runtime overhead when values are encoded 199Detecting shared values incurs a runtime overhead when values are encoded
198that have a reference counter large than one, and might unnecessarily 200that have a reference counter large than one, and might unnecessarily
199increase the encoded size, as potentially shared values are encode as 201increase the encoded size, as potentially shared values are encode as
200sharable whether or not they are actually shared. 202sharable whether or not they are actually shared.
201 203
202At the moment, only targets of references can be shared (e.g. scalars, 204At the moment, only targets of references can be shared (e.g. scalars,
203arrays or hashes pointed to by a reference). Weirder constructs, such as 205arrays or hashes pointed to by a reference). Weirder constructs, such as
204an array with multiple "copies" of the I<same> string, which are hard but 206an array with multiple "copies" of the I<same> string, which are hard but
205not impossible to create in Perl, are not supported (this is the same as 207not impossible to create in Perl, are not supported (this is the same as
206for L<Storable>). 208with L<Storable>).
207 209
208If C<$enable> is false (the default), then C<encode> will encode 210If C<$enable> is false (the default), then C<encode> will encode shared
209exception when it encounters anything it cannot encode as CBOR. 211data structures repeatedly, unsharing them in the process. Cyclic data
212structures cannot be encoded in this mode.
210 213
211This option does not affect C<decode> in any way - shared values and 214This option does not affect C<decode> in any way - shared values and
212references will always be decoded properly if present. 215references will always be decoded properly if present.
213 216
214=item $cbor = $cbor->allow_stringref ([$enable]) 217=item $cbor = $cbor->pack_strings ([$enable])
215 218
216=item $enabled = $cbor->get_allow_stringref 219=item $enabled = $cbor->get_pack_strings
217 220
218If C<$enable> is true (or missing), then C<encode> will try not to encode 221If C<$enable> is true (or missing), then C<encode> will try not to encode
219the same string twice, but will instead encode a reference to the string 222the same string twice, but will instead encode a reference to the string
220instead. Depending on your data format. this can save a lot of space, but 223instead. Depending on your data format, this can save a lot of space, but
221also results in a very large runtime overhead (expect encoding times to be 224also results in a very large runtime overhead (expect encoding times to be
2222-4 times as high as without). 2252-4 times as high as without).
223 226
224It is recommended to leave it off unless you know your 227It is recommended to leave it off unless you know your
225communications partner supports the stringref extension to CBOR 228communications partner supports the stringref extension to CBOR
226(http://cbor.schmorp.de/stringref). 229(http://cbor.schmorp.de/stringref), as without decoder support, the
230resulting data structure might not be usable.
227 231
228If C<$enable> is false (the default), then C<encode> will encode 232If C<$enable> is false (the default), then C<encode> will encode strings
229exception when it encounters anything it cannot encode as CBOR. 233the standard CBOR way.
230 234
231This option does not affect C<decode> in any way - string references will 235This option does not affect C<decode> in any way - string references will
232always be decoded properly if present. 236always be decoded properly if present.
233 237
234=item $cbor = $cbor->filter ([$cb->($tag, $value)]) 238=item $cbor = $cbor->filter ([$cb->($tag, $value)])
… …
690C<allow_sharable> is enabled. 694C<allow_sharable> is enabled.
691 695
692=item <unassigned>, <unassigned> (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>) 696=item <unassigned>, <unassigned> (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>)
693 697
694These tags are automatically decoded when encountered. They are only 698These tags are automatically decoded when encountered. They are only
695encoded, however, when C<allow_stringref> is enabled. 699encoded, however, when C<pack_strings> is enabled.
696 700
697=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>) 701=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>)
698 702
699This tag is automatically generated when a reference are encountered (with 703This tag is automatically generated when a reference are encountered (with
700the exception of hash and array refernces). It is converted to a reference 704the exception of hash and array refernces). It is converted to a reference

Diff Legend

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