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

Comparing CBOR-XS/README (file contents):
Revision 1.20 by root, Tue Dec 1 01:50:01 2020 UTC vs.
Revision 1.22 by root, Thu Oct 21 01:14:58 2021 UTC

… …
86 but configures the coder object to be safe to use with untrusted 86 but configures the coder object to be safe to use with untrusted
87 data. Currently, this is equivalent to: 87 data. Currently, this is equivalent to:
88 88
89 my $cbor = CBOR::XS 89 my $cbor = CBOR::XS
90 ->new 90 ->new
91 ->validate_utf8
91 ->forbid_objects 92 ->forbid_objects
92 ->filter (\&CBOR::XS::safe_filter) 93 ->filter (\&CBOR::XS::safe_filter)
93 ->max_size (1e8); 94 ->max_size (1e8);
94 95
95 But is more future proof (it is better to crash because of a change 96 But is more future proof (it is better to crash because of a change
… …
616 than IEEE double to represent numerical values are supported, but 617 than IEEE double to represent numerical values are supported, but
617 might suffer loss of precision. 618 might suffer loss of precision.
618 619
619 TYPE CASTS 620 TYPE CASTS
620 EXPERIMENTAL: As an experimental extension, "CBOR::XS" allows you to 621 EXPERIMENTAL: As an experimental extension, "CBOR::XS" allows you to
621 force specific cbor types to be used when encoding. That allows you to 622 force specific CBOR types to be used when encoding. That allows you to
622 encode types not normally accessible (e.g. half floats) as well as force 623 encode types not normally accessible (e.g. half floats) as well as force
623 string types even when "text_strings" is in effect. 624 string types even when "text_strings" is in effect.
624 625
625 Type forcing is done by calling a special "cast" function which keeps a 626 Type forcing is done by calling a special "cast" function which keeps a
626 copy of the value and returns a new value that can be handed over to any 627 copy of the value and returns a new value that can be handed over to any
627 CBOR encoder function. 628 CBOR encoder function.
628 629
629 The following casts are currently available (all of which are unary 630 The following casts are currently available (all of which are unary
630 operators): 631 operators, that is, have a prototype of "$"):
631 632
632 CBOR::XS::as_int $value 633 CBOR::XS::as_int $value
633 Forces the value to be encoded as some form of (basic, not bignum) 634 Forces the value to be encoded as some form of (basic, not bignum)
634 integer type. 635 integer type.
635 636
… …
637 Forces the value to be encoded as (UTF-8) text values. 638 Forces the value to be encoded as (UTF-8) text values.
638 639
639 CBOR::XS::as_bytes $value 640 CBOR::XS::as_bytes $value
640 Forces the value to be encoded as a (binary) string value. 641 Forces the value to be encoded as a (binary) string value.
641 642
643 Example: encode a perl string as binary even though "text_strings"
644 is in effect.
645
646 CBOR::XS->new->text_strings->encode ([4, "text", CBOR::XS::bytes "bytevalue"]);
647
642 CBOR::XS::as_bool $value 648 CBOR::XS::as_bool $value
643 Converts a Perl boolean (which can be any kind of scalar) into a 649 Converts a Perl boolean (which can be any kind of scalar) into a
644 CBOR boolean. Strictly the same, but shorter to write, than: 650 CBOR boolean. Strictly the same, but shorter to write, than:
645 651
646 $value ? Types::Serialiser::true : Types::Serialiser::false 652 $value ? Types::Serialiser::true : Types::Serialiser::false
… …
652 Forces single-float (IEEE 754 binary32) encoding of the given value. 658 Forces single-float (IEEE 754 binary32) encoding of the given value.
653 659
654 CBOR::XS::as_float64 $value 660 CBOR::XS::as_float64 $value
655 Forces double-float (IEEE 754 binary64) encoding of the given value. 661 Forces double-float (IEEE 754 binary64) encoding of the given value.
656 662
657 =item, CBOR::XS::as_cbor $cbor_text 663 CBOR::XS::as_cbor $cbor_text
658
659 Bot a type cast per-se, this type cast forces the argument to eb 664 Not a type cast per-se, this type cast forces the argument to be
660 encoded as-is. This can be used to embed pre-encoded CBOR data. 665 encoded as-is. This can be used to embed pre-encoded CBOR data.
661 666
662 Note that no checking on the validity of the $cbor_text is done - 667 Note that no checking on the validity of the $cbor_text is done -
663 it's the callers responsibility to correctly encode values. 668 it's the callers responsibility to correctly encode values.
664 669
665 Example: encode a perl string as binary even though "text_strings" is in 670 CBOR::XS::as_map [key => value...]
666 effect. 671 Treat the array reference as key value pairs and output a CBOR map.
672 This allows you to generate CBOR maps with arbitrary key types (or,
673 if you don't care about semantics, duplicate keys or pairs in a
674 custom order), which is otherwise hard to do with Perl.
667 675
668 CBOR::XS->new->text_strings->encode ([4, "text", CBOR::XS::bytes "bytevalue"]); 676 The single argument must be an array reference with an even number
677 of elements.
678
679 Note that only the reference to the array is copied, the array
680 itself is not. Modifications done to the array before calling an
681 encoding function will be reflected in the encoded output.
682
683 Example: encode a CBOR map with a string and an integer as keys.
684
685 encode_cbor CBOR::XS::as_map [string => "value", 5 => "value"]
669 686
670 OBJECT SERIALISATION 687 OBJECT SERIALISATION
671 This module implements both a CBOR-specific and the generic 688 This module implements both a CBOR-specific and the generic
672 Types::Serialier object serialisation protocol. The following 689 Types::Serialier object serialisation protocol. The following
673 subsections explain both methods. 690 subsections explain both methods.

Diff Legend

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