--- CBOR-XS/XS.pm	2019/11/09 07:23:31	1.69
+++ CBOR-XS/XS.pm	2020/11/29 21:35:51	1.73
@@ -66,7 +66,7 @@
 
 use common::sense;
 
-our $VERSION = 1.71;
+our $VERSION = 1.8;
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_cbor decode_cbor);
@@ -332,10 +332,11 @@
 This option does not affect C<decode> in any way.
 
 This option has similar advantages and disadvantages as C<text_keys>. In
-addition, this option effectively removes the ability to encode byte
-strings, which might break some C<FREEZE> and C<TO_CBOR> methods that rely
-on this, such as bignum encoding, so this option is mainly useful for very
-simple data.
+addition, this option effectively removes the ability to automatically
+encode byte strings, which might break some C<FREEZE> and C<TO_CBOR>
+methods that rely on this.
+
+A workaround is to use explicit type casts, which are unaffected by this option.
 
 =item $cbor = $cbor->validate_utf8 ([$enable])
 
@@ -455,7 +456,8 @@
 
 This is useful if your CBOR texts are not delimited by an outer protocol
 and you need to know where the first CBOR string ends amd the next one
-starts.
+starts - CBOR strings are self-delimited, so it is possible to concatenate
+CBOR strings without any delimiters or size fields and recover their data.
 
    CBOR::XS->new->decode_prefix ("......")
    => ("...", 3)
@@ -669,11 +671,14 @@
    print $x;    # perl does it for you, too, quite often
 
 You can force whether a string is encoded as byte or text string by using
-C<utf8::upgrade> and C<utf8::downgrade> (if C<text_strings> is disabled):
+C<utf8::upgrade> and C<utf8::downgrade> (if C<text_strings> is disabled).
 
   utf8::upgrade $x;   # encode $x as text string
   utf8::downgrade $x; # encode $x as byte string
 
+More options are available, see L<TYPE CASTS>, below, and the C<text_keys>
+and C<text_strings> options.
+
 Perl doesn't define what operations up- and downgrade strings, so if the
 difference between byte and text is important, you should up- or downgrade
 your string as late as possible before encoding. You can also force the
@@ -698,6 +703,71 @@
 
 =back
 
+=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
+encode types not normally accessible (e.g. half floats) as well as force
+string types even when C<text_strings> is in effect.
+
+Type forcing is done by calling a special "cast" function which keeps a
+copy of the value and returns a new value that can be handed over to any
+CBOR encoder function.
+
+The following casts are currently available (all of which are unary operators):
+
+=over
+
+=item CBOR::XS::as_int $value
+
+Forces the value to be encoded as some form of (basic, not bignum) integer
+type.
+
+=item CBOR::XS::as_text $value
+
+Forces the value to be encoded as (UTF-8) text values.
+
+=item CBOR::XS::as_bytes $value
+
+Forces the value to be encoded as a (binary) string value.
+
+=item CBOR::XS::as_float16 $value
+
+Forces half-float (IEEE 754 binary16) encoding of the given value.
+
+=item CBOR::XS::as_float32 $value
+
+Forces single-float (IEEE 754 binary32) encoding of the given value.
+
+=item CBOR::XS::as_float64 $value
+
+Forces double-float (IEEE 754 binary64) encoding of the given value.
+
+=item, CBOR::XS::as_cbor $cbor_text
+
+Bot a type cast per-se, this type cast forces the argument to eb 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
+the callers responsibility to correctly encode values.
+
+=back
+
+Example: encode a perl string as binary even though C<text_strings> is in
+effect.
+
+   CBOR::XS->new->text_strings->encode ([4, "text", CBOR::XS::bytes "bytevalue"]);
+
+=cut
+
+sub CBOR::XS::as_int     ($) { bless [$_[0], 0, undef], CBOR::XS::Tagged:: }
+sub CBOR::XS::as_cbor    ($) { bless [$_[0], 1, undef], CBOR::XS::Tagged:: }
+sub CBOR::XS::as_bytes   ($) { bless [$_[0], 2, undef], CBOR::XS::Tagged:: }
+sub CBOR::XS::as_text    ($) { bless [$_[0], 3, undef], CBOR::XS::Tagged:: }
+sub CBOR::XS::as_float16 ($) { bless [$_[0], 4, undef], CBOR::XS::Tagged:: }
+sub CBOR::XS::as_float32 ($) { bless [$_[0], 5, undef], CBOR::XS::Tagged:: }
+sub CBOR::XS::as_float64 ($) { bless [$_[0], 6, undef], CBOR::XS::Tagged:: }
+
 =head2 OBJECT SERIALISATION
 
 This module implements both a CBOR-specific and the generic
@@ -1229,9 +1299,10 @@
 On perls that were built without 64 bit integer support (these are rare
 nowadays, even on 32 bit architectures, as all major Perl distributions
 are built with 64 bit integer support), support for any kind of 64 bit
-integer in CBOR is very limited - most likely, these 64 bit values will
+value in CBOR is very limited - most likely, these 64 bit values will
 be truncated, corrupted, or otherwise not decoded correctly. This also
-includes string, array and map sizes that are stored as 64 bit integers.
+includes string, float, array and map sizes that are stored as 64 bit
+integers.
 
 
 =head1 THREADS