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.70 by root, Sat Nov 9 07:30:36 2019 UTC vs.
Revision 1.79 by root, Fri Dec 11 06:03:40 2020 UTC

… …
64 64
65package CBOR::XS; 65package CBOR::XS;
66 66
67use common::sense; 67use common::sense;
68 68
69our $VERSION = 1.71; 69our $VERSION = 1.83;
70our @ISA = qw(Exporter); 70our @ISA = qw(Exporter);
71 71
72our @EXPORT = qw(encode_cbor decode_cbor); 72our @EXPORT = qw(encode_cbor decode_cbor);
73 73
74use Exporter; 74use Exporter;
… …
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
… …
668 "$x"; # stringified 669 "$x"; # stringified
669 $x .= ""; # another, more awkward way to stringify 670 $x .= ""; # another, more awkward way to stringify
670 print $x; # perl does it for you, too, quite often 671 print $x; # perl does it for you, too, quite often
671 672
672You 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
673C<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).
674 675
675 utf8::upgrade $x; # encode $x as text string 676 utf8::upgrade $x; # encode $x as text string
676 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.
677 681
678Perl 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
679difference between byte and text is important, you should up- or downgrade 683difference between byte and text is important, you should up- or downgrade
680your 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
681use 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>.
… …
696format 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
697represent numerical values are supported, but might suffer loss of 701represent numerical values are supported, but might suffer loss of
698precision. 702precision.
699 703
700=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
718operators, that is, have a prototype of C<$>):
719
720=over
721
722=item CBOR::XS::as_int $value
723
724Forces the value to be encoded as some form of (basic, not bignum) integer
725type.
726
727=item CBOR::XS::as_text $value
728
729Forces the value to be encoded as (UTF-8) text values.
730
731=item CBOR::XS::as_bytes $value
732
733Forces the value to be encoded as a (binary) string value.
734
735Example: encode a perl string as binary even though C<text_strings> is in
736effect.
737
738 CBOR::XS->new->text_strings->encode ([4, "text", CBOR::XS::bytes "bytevalue"]);
739
740=item CBOR::XS::as_bool $value
741
742Converts a Perl boolean (which can be any kind of scalar) into a CBOR
743boolean. Strictly the same, but shorter to write, than:
744
745 $value ? Types::Serialiser::true : Types::Serialiser::false
746
747=item CBOR::XS::as_float16 $value
748
749Forces half-float (IEEE 754 binary16) encoding of the given value.
750
751=item CBOR::XS::as_float32 $value
752
753Forces single-float (IEEE 754 binary32) encoding of the given value.
754
755=item CBOR::XS::as_float64 $value
756
757Forces double-float (IEEE 754 binary64) encoding of the given value.
758
759=item CBOR::XS::as_cbor $cbor_text
760
761Not a type cast per-se, this type cast forces the argument to eb encoded
762as-is. This can be used to embed pre-encoded CBOR data.
763
764Note that no checking on the validity of the C<$cbor_text> is done - it's
765the callers responsibility to correctly encode values.
766
767=item CBOR::XS::as_map [key => value...]
768
769Treat the array reference as key value pairs and output a CBOR map. This
770allows you to generate CBOR maps with arbitrary key types (or, if you
771don't care about semantics, duplicate keys or prairs in a custom order),
772which is otherwise hard to do with Perl.
773
774The single argument must be an array reference with an even number of
775elements.
776
777Example: encode a CBOR map with a string and an integer as keys.
778
779 encode_cbor CBOR::XS::as_map [string => "value", 5 => "value"]
780
781=back
782
783=cut
784
785sub CBOR::XS::as_cbor ($) { bless [$_[0], 0, undef], CBOR::XS::Tagged:: }
786sub CBOR::XS::as_int ($) { bless [$_[0], 1, undef], CBOR::XS::Tagged:: }
787sub CBOR::XS::as_bytes ($) { bless [$_[0], 2, undef], CBOR::XS::Tagged:: }
788sub CBOR::XS::as_text ($) { bless [$_[0], 3, undef], CBOR::XS::Tagged:: }
789sub CBOR::XS::as_float16 ($) { bless [$_[0], 4, undef], CBOR::XS::Tagged:: }
790sub CBOR::XS::as_float32 ($) { bless [$_[0], 5, undef], CBOR::XS::Tagged:: }
791sub CBOR::XS::as_float64 ($) { bless [$_[0], 6, undef], CBOR::XS::Tagged:: }
792
793sub CBOR::XS::as_bool ($) { $_[0] ? $Types::Serialiser::true : $Types::Serialiser::false }
794
795sub CBOR::XS::as_map ($) {
796 ARRAY:: eq ref $_[0]
797 and $#{ $_[0] } & 1
798 or do { require Carp; Carp::croak ("CBOR::XS::as_map only acepts array references with an even number of elements, caught") };
799
800 bless [$_[0], 7, undef], CBOR::XS::Tagged::
801}
701 802
702=head2 OBJECT SERIALISATION 803=head2 OBJECT SERIALISATION
703 804
704This module implements both a CBOR-specific and the generic 805This module implements both a CBOR-specific and the generic
705L<Types::Serialier> object serialisation protocol. The following 806L<Types::Serialier> object serialisation protocol. The following
… …
1228=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT 1329=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
1229 1330
1230On perls that were built without 64 bit integer support (these are rare 1331On perls that were built without 64 bit integer support (these are rare
1231nowadays, even on 32 bit architectures, as all major Perl distributions 1332nowadays, even on 32 bit architectures, as all major Perl distributions
1232are built with 64 bit integer support), support for any kind of 64 bit 1333are built with 64 bit integer support), support for any kind of 64 bit
1233integer in CBOR is very limited - most likely, these 64 bit values will 1334value in CBOR is very limited - most likely, these 64 bit values will
1234be truncated, corrupted, or otherwise not decoded correctly. This also 1335be truncated, corrupted, or otherwise not decoded correctly. This also
1235includes string, array and map sizes that are stored as 64 bit integers. 1336includes string, float, array and map sizes that are stored as 64 bit
1337integers.
1236 1338
1237 1339
1238=head1 THREADS 1340=head1 THREADS
1239 1341
1240This module is I<not> guaranteed to be thread safe and there are no 1342This module is I<not> guaranteed to be thread safe and there are no

Diff Legend

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