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

Comparing CBOR-XS/README (file contents):
Revision 1.21 by root, Tue Dec 8 08:29:44 2020 UTC vs.
Revision 1.23 by root, Fri Sep 8 20:03:06 2023 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
… …
164 partner supports the value sharing extensions to CBOR 165 partner supports the value sharing extensions to CBOR
165 (<http://cbor.schmorp.de/value-sharing>), as without decoder 166 (<http://cbor.schmorp.de/value-sharing>), as without decoder
166 support, the resulting data structure might be unusable. 167 support, the resulting data structure might be unusable.
167 168
168 Detecting shared values incurs a runtime overhead when values are 169 Detecting shared values incurs a runtime overhead when values are
169 encoded that have a reference counter large than one, and might 170 encoded that have a reference counter larger than one, and might
170 unnecessarily increase the encoded size, as potentially shared 171 unnecessarily increase the encoded size, as potentially shared
171 values are encoded as shareable whether or not they are actually 172 values are encoded as shareable whether or not they are actually
172 shared. 173 shared.
173 174
174 At the moment, only targets of references can be shared (e.g. 175 At the moment, only targets of references can be shared (e.g.
… …
192 code that isn't prepared for this will not leak memory. 193 code that isn't prepared for this will not leak memory.
193 194
194 If $enable is false (the default), then "decode" will throw an error 195 If $enable is false (the default), then "decode" will throw an error
195 when it encounters a self-referential/cyclic data structure. 196 when it encounters a self-referential/cyclic data structure.
196 197
197 FUTURE DIRECTION: the motivation behind this option is to avoid 198 This option does not affect "encode" in any way - shared values and
198 *real* cycles - future versions of this module might chose to decode 199 references will always be encoded properly if present.
199 cyclic data structures using weak references when this option is 200
200 off, instead of throwing an error. 201 $cbor = $cbor->allow_weak_cycles ([$enable])
202 $enabled = $cbor->get_allow_weak_cycles
203 This works like "allow_cycles" in that it allows the resulting data
204 structures to contain cycles, but unlike "allow_cycles", those
205 cyclic rreferences will be weak. That means that code that
206 recurrsively walks the data structure must be prepared with cycles,
207 but at least not special precautions must be implemented to free
208 these data structures.
209
210 Only those references leading to actual cycles will be weakened -
211 other references, e.g. when the same hash or arrray is referenced
212 multiple times in an arrray, will be normal references.
201 213
202 This option does not affect "encode" in any way - shared values and 214 This option does not affect "encode" in any way - shared values and
203 references will always be encoded properly if present. 215 references will always be encoded properly if present.
204 216
205 $cbor = $cbor->forbid_objects ([$enable]) 217 $cbor = $cbor->forbid_objects ([$enable])
… …
413 data structure in memory at one time, it does allow you to parse a CBOR 425 data structure in memory at one time, it does allow you to parse a CBOR
414 stream incrementally, using a similar to using "decode_prefix" to see if 426 stream incrementally, using a similar to using "decode_prefix" to see if
415 a full CBOR object is available, but is much more efficient. 427 a full CBOR object is available, but is much more efficient.
416 428
417 It basically works by parsing as much of a CBOR string as possible - if 429 It basically works by parsing as much of a CBOR string as possible - if
418 the CBOR data is not complete yet, the pasrer will remember where it 430 the CBOR data is not complete yet, the parser will remember where it
419 was, to be able to restart when more data has been accumulated. Once 431 was, to be able to restart when more data has been accumulated. Once
420 enough data is available to either decode a complete CBOR value or raise 432 enough data is available to either decode a complete CBOR value or raise
421 an error, a real decode will be attempted. 433 an error, a real decode will be attempted.
422 434
423 A typical use case would be a network protocol that consists of sending 435 A typical use case would be a network protocol that consists of sending
… …
547 "CBOR::XS::tag" to create such objects. 559 "CBOR::XS::tag" to create such objects.
548 560
549 Types::Serialiser::true, Types::Serialiser::false, 561 Types::Serialiser::true, Types::Serialiser::false,
550 Types::Serialiser::error 562 Types::Serialiser::error
551 These special values become CBOR true, CBOR false and CBOR undefined 563 These special values become CBOR true, CBOR false and CBOR undefined
552 values, respectively. You can also use "\1", "\0" and "\undef" 564 values, respectively.
553 directly if you want.
554 565
555 other blessed objects 566 other blessed objects
556 Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See 567 Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
557 "TAG HANDLING AND EXTENSIONS" for specific classes handled by this 568 "TAG HANDLING AND EXTENSIONS" for specific classes handled by this
558 module, and "OBJECT SERIALISATION" for generic object serialisation. 569 module, and "OBJECT SERIALISATION" for generic object serialisation.
… …
616 than IEEE double to represent numerical values are supported, but 627 than IEEE double to represent numerical values are supported, but
617 might suffer loss of precision. 628 might suffer loss of precision.
618 629
619 TYPE CASTS 630 TYPE CASTS
620 EXPERIMENTAL: As an experimental extension, "CBOR::XS" allows you to 631 EXPERIMENTAL: As an experimental extension, "CBOR::XS" allows you to
621 force specific cbor types to be used when encoding. That allows you to 632 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 633 encode types not normally accessible (e.g. half floats) as well as force
623 string types even when "text_strings" is in effect. 634 string types even when "text_strings" is in effect.
624 635
625 Type forcing is done by calling a special "cast" function which keeps a 636 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 637 copy of the value and returns a new value that can be handed over to any
627 CBOR encoder function. 638 CBOR encoder function.
628 639
629 The following casts are currently available (all of which are unary 640 The following casts are currently available (all of which are unary
630 operators): 641 operators, that is, have a prototype of "$"):
631 642
632 CBOR::XS::as_int $value 643 CBOR::XS::as_int $value
633 Forces the value to be encoded as some form of (basic, not bignum) 644 Forces the value to be encoded as some form of (basic, not bignum)
634 integer type. 645 integer type.
635 646
… …
658 669
659 CBOR::XS::as_float64 $value 670 CBOR::XS::as_float64 $value
660 Forces double-float (IEEE 754 binary64) encoding of the given value. 671 Forces double-float (IEEE 754 binary64) encoding of the given value.
661 672
662 CBOR::XS::as_cbor $cbor_text 673 CBOR::XS::as_cbor $cbor_text
663 Not a type cast per-se, this type cast forces the argument to eb 674 Not a type cast per-se, this type cast forces the argument to be
664 encoded as-is. This can be used to embed pre-encoded CBOR data. 675 encoded as-is. This can be used to embed pre-encoded CBOR data.
665 676
666 Note that no checking on the validity of the $cbor_text is done - 677 Note that no checking on the validity of the $cbor_text is done -
667 it's the callers responsibility to correctly encode values. 678 it's the callers responsibility to correctly encode values.
668 679
669 CBOR::XS::as_map [key => value...] 680 CBOR::XS::as_map [key => value...]
670 Treat the array reference as key value pairs and output a CBOR map. 681 Treat the array reference as key value pairs and output a CBOR map.
671 This allows you to generate CBOR maps with arbitrary key types (or, 682 This allows you to generate CBOR maps with arbitrary key types (or,
672 if you don't care about semantics, duplicate keys or prairs in a 683 if you don't care about semantics, duplicate keys or pairs in a
673 custom order), which is otherwise hard to do with Perl. 684 custom order), which is otherwise hard to do with Perl.
674 685
675 The single argument must be an array reference with an even number 686 The single argument must be an array reference with an even number
676 of elements. 687 of elements.
688
689 Note that only the reference to the array is copied, the array
690 itself is not. Modifications done to the array before calling an
691 encoding function will be reflected in the encoded output.
677 692
678 Example: encode a CBOR map with a string and an integer as keys. 693 Example: encode a CBOR map with a string and an integer as keys.
679 694
680 encode_cbor CBOR::XS::as_map [string => "value", 5 => "value"] 695 encode_cbor CBOR::XS::as_map [string => "value", 5 => "value"]
681 696

Diff Legend

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