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.69 by root, Sat Nov 9 07:23:31 2019 UTC vs.
Revision 1.71 by root, Sun Nov 29 21:32:01 2020 UTC

… …
330strings as CBOR byte strings. 330strings as CBOR byte strings.
331 331
332This option does not affect C<decode> in any way. 332This option does not affect C<decode> in any way.
333 333
334This option has similar advantages and disadvantages as C<text_keys>. In 334This option has similar advantages and disadvantages as C<text_keys>. In
335addition, this option effectively removes the ability to encode byte 335addition, this option effectively removes the ability to automatically
336strings, which might break some C<FREEZE> and C<TO_CBOR> methods that rely 336encode byte strings, which might break some C<FREEZE> and C<TO_CBOR>
337on this, such as bignum encoding, so this option is mainly useful for very 337methods that rely on this.
338simple data. 338
339A workaround is to use explicit type casts, which are unaffected by this option.
339 340
340=item $cbor = $cbor->validate_utf8 ([$enable]) 341=item $cbor = $cbor->validate_utf8 ([$enable])
341 342
342=item $enabled = $cbor->get_validate_utf8 343=item $enabled = $cbor->get_validate_utf8
343 344
… …
453when there is trailing garbage after the CBOR string, it will silently 454when there is trailing garbage after the CBOR string, it will silently
454stop parsing there and return the number of characters consumed so far. 455stop parsing there and return the number of characters consumed so far.
455 456
456This is useful if your CBOR texts are not delimited by an outer protocol 457This is useful if your CBOR texts are not delimited by an outer protocol
457and you need to know where the first CBOR string ends amd the next one 458and you need to know where the first CBOR string ends amd the next one
458starts. 459starts - CBOR strings are self-delimited, so it is possible to concatenate
460CBOR strings without any delimiters or size fields and recover their data.
459 461
460 CBOR::XS->new->decode_prefix ("......") 462 CBOR::XS->new->decode_prefix ("......")
461 => ("...", 3) 463 => ("...", 3)
462 464
463=back 465=back
… …
667 "$x"; # stringified 669 "$x"; # stringified
668 $x .= ""; # another, more awkward way to stringify 670 $x .= ""; # another, more awkward way to stringify
669 print $x; # perl does it for you, too, quite often 671 print $x; # perl does it for you, too, quite often
670 672
671You can force whether a string is encoded as byte or text string by using 673You can force whether a string is encoded as byte or text string by using
672C<utf8::upgrade> and C<utf8::downgrade> (if C<text_strings> is disabled): 674C<utf8::upgrade> and C<utf8::downgrade> (if C<text_strings> is disabled).
673 675
674 utf8::upgrade $x; # encode $x as text string 676 utf8::upgrade $x; # encode $x as text string
675 utf8::downgrade $x; # encode $x as byte string 677 utf8::downgrade $x; # encode $x as byte string
678
679More options are available, see L<TYPE CASTS>, below, and the C<text_keys>
680and C<text_strings> options.
676 681
677Perl doesn't define what operations up- and downgrade strings, so if the 682Perl doesn't define what operations up- and downgrade strings, so if the
678difference between byte and text is important, you should up- or downgrade 683difference between byte and text is important, you should up- or downgrade
679your string as late as possible before encoding. You can also force the 684your string as late as possible before encoding. You can also force the
680use of CBOR text strings by using C<text_keys> or C<text_strings>. 685use of CBOR text strings by using C<text_keys> or C<text_strings>.
… …
695format will be used. Perls that use formats other than IEEE double to 700format will be used. Perls that use formats other than IEEE double to
696represent numerical values are supported, but might suffer loss of 701represent numerical values are supported, but might suffer loss of
697precision. 702precision.
698 703
699=back 704=back
705
706=head2 TYPE CASTS
707
708B<EXPERIMENTAL>: As an experimental extension, C<CBOR::XS> allows you to
709force specific cbor types to be used when encoding. That allows you to
710encode types not normally accessible (e.g. half floats) as well as force
711string types even when C<text_strings> is in effect.
712
713Type forcing is done by calling a special "cast" function which keeps a
714copy of the value and returns a new value that can be handed over to any
715CBOR encoder function.
716
717The following casts are currently available (all of which are unary operators):
718
719=over
720
721=item CBOR::XS::as_text $value
722
723Forces the value to be encoded as (UTF-8) text values.
724
725=item CBOR::XS::as_bytes $value
726
727Forces the value to be encoded as a (binary) string value.
728
729=item CBOR::XS::as_float16 $value
730
731Forces half-float (IEEE 754 binary16) encoding of the given value.
732
733=item CBOR::XS::as_float32 $value
734
735Forces single-float (IEEE 754 binary32) encoding of the given value.
736
737=item CBOR::XS::as_float64 $value
738
739Forces double-float (IEEE 754 binary64) encoding of the given value.
740
741=item, CBOR::XS::as_cbor $cbor_text
742
743Bot a type cast per-se, this type cast forces the argument to eb encoded
744as-is. This can be used to embed pre-encoded CBOR data.
745
746Note that no checking on the validity of the C<$cbor_text> is done - it's
747the callers responsibility to correctly encode values.
748
749=back
750
751Example: encode a perl string as binary even though C<text_strings> is in
752effect.
753
754 CBOR::XS->new->text_strings->encode ([4, "text", CBOR::XS::bytes "bytevalue"]);
755
756=cut
757
758sub CBOR::XS::as_cbor ($) { bless [$_[0], 0, undef], CBOR::XS::Tagged:: }
759sub CBOR::XS::as_bytes ($) { bless [$_[0], 1, undef], CBOR::XS::Tagged:: }
760sub CBOR::XS::as_text ($) { bless [$_[0], 2, undef], CBOR::XS::Tagged:: }
761sub CBOR::XS::as_float16 ($) { bless [$_[0], 3, undef], CBOR::XS::Tagged:: }
762sub CBOR::XS::as_float32 ($) { bless [$_[0], 4, undef], CBOR::XS::Tagged:: }
763sub CBOR::XS::as_float64 ($) { bless [$_[0], 5, undef], CBOR::XS::Tagged:: }
700 764
701=head2 OBJECT SERIALISATION 765=head2 OBJECT SERIALISATION
702 766
703This module implements both a CBOR-specific and the generic 767This module implements both a CBOR-specific and the generic
704L<Types::Serialier> object serialisation protocol. The following 768L<Types::Serialier> object serialisation protocol. The following
… …
1227=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT 1291=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
1228 1292
1229On perls that were built without 64 bit integer support (these are rare 1293On perls that were built without 64 bit integer support (these are rare
1230nowadays, even on 32 bit architectures, as all major Perl distributions 1294nowadays, even on 32 bit architectures, as all major Perl distributions
1231are built with 64 bit integer support), support for any kind of 64 bit 1295are built with 64 bit integer support), support for any kind of 64 bit
1232integer in CBOR is very limited - most likely, these 64 bit values will 1296value in CBOR is very limited - most likely, these 64 bit values will
1233be truncated, corrupted, or otherwise not decoded correctly. This also 1297be truncated, corrupted, or otherwise not decoded correctly. This also
1234includes string, array and map sizes that are stored as 64 bit integers. 1298includes string, float, array and map sizes that are stored as 64 bit
1299integers.
1235 1300
1236 1301
1237=head1 THREADS 1302=head1 THREADS
1238 1303
1239This module is I<not> guaranteed to be thread safe and there are no 1304This module is I<not> guaranteed to be thread safe and there are no

Diff Legend

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