--- CBOR-XS/XS.pm	2020/12/11 06:03:40	1.79
+++ CBOR-XS/XS.pm	2023/11/18 18:19:57	1.90
@@ -66,7 +66,7 @@
 
 use common::sense;
 
-our $VERSION = 1.83;
+our $VERSION = 1.87;
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_cbor decode_cbor);
@@ -123,6 +123,7 @@
 
    my $cbor = CBOR::XS
       ->new
+      ->validate_utf8
       ->forbid_objects
       ->filter (\&CBOR::XS::safe_filter)
       ->max_size (1e8);
@@ -135,6 +136,7 @@
 sub new_safe {
    CBOR::XS
       ->new
+      ->validate_utf8
       ->forbid_objects
       ->filter (\&CBOR::XS::safe_filter)
       ->max_size (1e8)
@@ -216,7 +218,7 @@
 resulting data structure might be unusable.
 
 Detecting shared values incurs a runtime overhead when values are encoded
-that have a reference counter large than one, and might unnecessarily
+that have a reference counter larger than one, and might unnecessarily
 increase the encoded size, as potentially shared values are encoded as
 shareable whether or not they are actually shared.
 
@@ -245,10 +247,22 @@
 If C<$enable> is false (the default), then C<decode> will throw an error
 when it encounters a self-referential/cyclic data structure.
 
-FUTURE DIRECTION: the motivation behind this option is to avoid I<real>
-cycles - future versions of this module might chose to decode cyclic data
-structures using weak references when this option is off, instead of
-throwing an error.
+This option does not affect C<encode> in any way - shared values and
+references will always be encoded properly if present.
+
+=item $cbor = $cbor->allow_weak_cycles ([$enable])
+
+=item $enabled = $cbor->get_allow_weak_cycles
+
+This works like C<allow_cycles> in that it allows the resulting data
+structures to contain cycles, but unlike C<allow_cycles>, those cyclic
+rreferences will be weak. That means that code that recurrsively walks
+the data structure must be prepared with cycles, but at least not special
+precautions must be implemented to free these data structures.
+
+Only those references leading to actual cycles will be weakened - other
+references, e.g. when the same hash or arrray is referenced multiple times
+in an arrray, will be normal references.
 
 This option does not affect C<encode> in any way - shared values and
 references will always be encoded properly if present.
@@ -434,7 +448,7 @@
 
 
 Example: use the safe filter function (see L<SECURITY CONSIDERATIONS> for
-more considerations on security).
+more considerations regarding security).
 
    CBOR::XS->new->filter (\&CBOR::XS::safe_filter)->decode ($cbor_data);
 
@@ -473,7 +487,7 @@
 if a full CBOR object is available, but is much more efficient.
 
 It basically works by parsing as much of a CBOR string as possible - if
-the CBOR data is not complete yet, the pasrer will remember where it was,
+the CBOR data is not complete yet, the parser will remember where it was,
 to be able to restart when more data has been accumulated. Once enough
 data is available to either decode a complete CBOR value or raise an
 error, a real decode will be attempted.
@@ -635,8 +649,7 @@
 =item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
 
 These special values become CBOR true, CBOR false and CBOR undefined
-values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly
-if you want.
+values, respectively.
 
 =item other blessed objects
 
@@ -706,7 +719,7 @@
 =head2 TYPE CASTS
 
 B<EXPERIMENTAL>: As an experimental extension, C<CBOR::XS> allows you to
-force specific cbor types to be used when encoding. That allows you to
+force specific CBOR types to be used when encoding. That allows you to
 encode types not normally accessible (e.g. half floats) as well as force
 string types even when C<text_strings> is in effect.
 
@@ -758,7 +771,7 @@
 
 =item CBOR::XS::as_cbor $cbor_text
 
-Not a type cast per-se, this type cast forces the argument to eb encoded
+Not a type cast per-se, this type cast forces the argument to be encoded
 as-is. This can be used to embed pre-encoded CBOR data.
 
 Note that no checking on the validity of the C<$cbor_text> is done - it's
@@ -768,12 +781,16 @@
 
 Treat the array reference as key value pairs and output a CBOR map. This
 allows you to generate CBOR maps with arbitrary key types (or, if you
-don't care about semantics, duplicate keys or prairs in a custom order),
+don't care about semantics, duplicate keys or pairs in a custom order),
 which is otherwise hard to do with Perl.
 
 The single argument must be an array reference with an even number of
 elements.
 
+Note that only the reference to the array is copied, the array itself is
+not. Modifications done to the array before calling an encoding function
+will be reflected in the encoded output.
+
 Example: encode a CBOR map with a string and an integer as keys.
 
    encode_cbor CBOR::XS::as_map [string => "value", 5 => "value"]