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.25 by root, Thu Nov 28 12:08:07 2013 UTC vs.
Revision 1.27 by root, Thu Nov 28 15:43:24 2013 UTC

… …
191sharing extension. This also makes it possible to encode cyclic data 191sharing extension. This also makes it possible to encode cyclic data
192structures. 192structures.
193 193
194It is recommended to leave it off unless you know your 194It is recommended to leave it off unless you know your
195communication partner supports the value sharing extensions to CBOR 195communication partner supports the value sharing extensions to CBOR
196(http://cbor.schmorp.de/value-sharing), as without decoder support, the 196(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the
197resulting data structure might be unusable. 197resulting data structure might be unusable.
198 198
199Detecting shared values incurs a runtime overhead when values are encoded 199Detecting shared values incurs a runtime overhead when values are encoded
200that have a reference counter large than one, and might unnecessarily 200that have a reference counter large than one, and might unnecessarily
201increase the encoded size, as potentially shared values are encode as 201increase the encoded size, as potentially shared values are encode as
… …
224also 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
2252-4 times as high as without). 2252-4 times as high as without).
226 226
227It is recommended to leave it off unless you know your 227It is recommended to leave it off unless you know your
228communications partner supports the stringref extension to CBOR 228communications partner supports the stringref extension to CBOR
229(http://cbor.schmorp.de/stringref), as without decoder support, the 229(L<http://cbor.schmorp.de/stringref>), as without decoder support, the
230resulting data structure might not be usable. 230resulting data structure might not be usable.
231 231
232If C<$enable> is false (the default), then C<encode> will encode strings 232If C<$enable> is false (the default), then C<encode> will encode strings
233the standard CBOR way. 233the standard CBOR way.
234 234
… …
323CBOR integers become (numeric) perl scalars. On perls without 64 bit 323CBOR integers become (numeric) perl scalars. On perls without 64 bit
324support, 64 bit integers will be truncated or otherwise corrupted. 324support, 64 bit integers will be truncated or otherwise corrupted.
325 325
326=item byte strings 326=item byte strings
327 327
328Byte strings will become octet strings in Perl (the byte values 0..255 328Byte strings will become octet strings in Perl (the Byte values 0..255
329will simply become characters of the same value in Perl). 329will simply become characters of the same value in Perl).
330 330
331=item UTF-8 strings 331=item UTF-8 strings
332 332
333UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be 333UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
… …
424 # dump as number 424 # dump as number
425 encode_cbor [2] # yields [2] 425 encode_cbor [2] # yields [2]
426 encode_cbor [-3.0e17] # yields [-3e+17] 426 encode_cbor [-3.0e17] # yields [-3e+17]
427 my $value = 5; encode_cbor [$value] # yields [5] 427 my $value = 5; encode_cbor [$value] # yields [5]
428 428
429 # used as string, so dump as string 429 # used as string, so dump as string (either byte or text)
430 print $value; 430 print $value;
431 encode_cbor [$value] # yields ["5"] 431 encode_cbor [$value] # yields ["5"]
432 432
433 # undef becomes null 433 # undef becomes null
434 encode_cbor [undef] # yields [null] 434 encode_cbor [undef] # yields [null]
… …
437 437
438 my $x = 3.1; # some variable containing a number 438 my $x = 3.1; # some variable containing a number
439 "$x"; # stringified 439 "$x"; # stringified
440 $x .= ""; # another, more awkward way to stringify 440 $x .= ""; # another, more awkward way to stringify
441 print $x; # perl does it for you, too, quite often 441 print $x; # perl does it for you, too, quite often
442
443You can force whether a string ie encoded as byte or text string by using
444C<utf8::upgrade> and C<utf8::downgrade>):
445
446 utf8::upgrade $x; # encode $x as text string
447 utf8::downgrade $x; # encode $x as byte string
448
449Perl doesn't define what operations up- and downgrade strings, so if the
450difference between byte and text is important, you should up- or downgrade
451your string as late as possible before encoding.
442 452
443You can force the type to be a CBOR number by numifying it: 453You can force the type to be a CBOR number by numifying it:
444 454
445 my $x = "3"; # some variable containing a string 455 my $x = "3"; # some variable containing a string
446 $x += 0; # numify it, ensuring it will be dumped as a number 456 $x += 0; # numify it, ensuring it will be dumped as a number
… …
679These tags are always handled when decoding, and their handling cannot be 689These tags are always handled when decoding, and their handling cannot be
680overriden by the user. 690overriden by the user.
681 691
682=over 4 692=over 4
683 693
684=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>) 694=item 26 (perl-object, L<http://cbor.schmorp.de/perl-object>)
685 695
686These tags are automatically created (and decoded) for serialisable 696These tags are automatically created (and decoded) for serialisable
687objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object 697objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
688serialisation protocol). See L<OBJECT SERIALISATION> for details. 698serialisation protocol). See L<OBJECT SERIALISATION> for details.
689 699
690=item <unassigned>, <unassigned> (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>) 700=item 28, 29 (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
691 701
692These tags are automatically decoded when encountered, resulting in 702These tags are automatically decoded when encountered, resulting in
693shared values in the decoded object. They are only encoded, however, when 703shared values in the decoded object. They are only encoded, however, when
694C<allow_sharable> is enabled. 704C<allow_sharable> is enabled.
695 705
696=item <unassigned>, <unassigned> (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>) 706=item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>)
697 707
698These tags are automatically decoded when encountered. They are only 708These tags are automatically decoded when encountered. They are only
699encoded, however, when C<pack_strings> is enabled. 709encoded, however, when C<pack_strings> is enabled.
700 710
701=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>) 711=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>)

Diff Legend

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