--- CBOR-XS/README	2013/12/01 17:10:42	1.12
+++ CBOR-XS/README	2016/02/08 04:37:12	1.16
@@ -180,8 +180,13 @@
         If $enable is false (the default), then "decode" will throw an error
         when it encounters a self-referential/cyclic data structure.
 
+        FUTURE DIRECTION: the motivation behind this option is to avoid
+        *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 "encode" in any way - shared values and
-        references will always be decoded properly if present.
+        references will always be encoded properly if present.
 
     $cbor = $cbor->pack_strings ([$enable])
     $enabled = $cbor->get_pack_strings
@@ -289,6 +294,64 @@
            CBOR::XS->new->decode_prefix ("......")
            => ("...", 3)
 
+  INCREMENTAL PARSING
+    In some cases, there is the need for incremental parsing of JSON texts.
+    While this module always has to keep both CBOR text and resulting Perl
+    data structure in memory at one time, it does allow you to parse a CBOR
+    stream incrementally, using a similar to using "decode_prefix" to see 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, 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.
+
+    A typical use case would be a network protocol that consists of sending
+    and receiving CBOR-encoded messages. The solution that works with CBOR
+    and about anything else is by prepending a length to every CBOR value,
+    so the receiver knows how many octets to read. More compact (and
+    slightly slower) would be to just send CBOR values back-to-back, as
+    "CBOR::XS" knows where a CBOR value ends, and doesn't need an explicit
+    length.
+
+    The following methods help with this:
+
+    @decoded = $cbor->incr_parse ($buffer)
+        This method attempts to decode exactly one CBOR value from the
+        beginning of the given $buffer. The value is removed from the
+        $buffer on success. When $buffer doesn't contain a complete value
+        yet, it returns nothing. Finally, when the $buffer doesn't start
+        with something that could ever be a valid CBOR value, it raises an
+        exception, just as "decode" would. In the latter case the decoder
+        state is undefined and must be reset before being able to parse
+        further.
+
+        This method modifies the $buffer in place. When no CBOR value can be
+        decoded, the decoder stores the current string offset. On the next
+        call, continues decoding at the place where it stopped before. For
+        this to make sense, the $buffer must begin with the same octets as
+        on previous unsuccessful calls.
+
+        You can call this method in scalar context, in which case it either
+        returns a decoded value or "undef". This makes it impossible to
+        distinguish between CBOR null values (which decode to "undef") and
+        an unsuccessful decode, which is often acceptable.
+
+    @decoded = $cbor->incr_parse_multiple ($buffer)
+        Same as "incr_parse", but attempts to decode as many CBOR values as
+        possible in one go, instead of at most one. Calls to "incr_parse"
+        and "incr_parse_multiple" can be interleaved.
+
+    $cbor->incr_reset
+        Resets the incremental decoder. This throws away any saved state, so
+        that subsequent calls to "incr_parse" or "incr_parse_multiple" start
+        to parse a new CBOR value from the beginning of the $buffer again.
+
+        This method can be caled at any time, but it *must* be called if you
+        want to change your $buffer or there was a decoding error and you
+        want to reuse the $cbor object for future incremental parsings.
+
 MAPPING
     This section describes how CBOR::XS maps Perl values to CBOR values and
     vice versa. These mappings are designed to "do the right thing" in most
@@ -633,7 +696,7 @@
         objects using the "FREEZE/THAW" methods (the Types::Serialier object
         serialisation protocol). See "OBJECT SERIALISATION" for details.
 
-    28, 29 (shareable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
+    28, 29 (shareable, sharedref, <http://cbor.schmorp.de/value-sharing>)
         These tags are automatically decoded when encountered (and they do
         not result in a cyclic data structure, see "allow_cycles"),
         resulting in shared values in the decoded object. They are only
@@ -652,7 +715,7 @@
         considered too unimportant to be supported in the encoder. The
         decoder, however, will decode these values as shared values.
 
-    256, 25 (stringref-namespace, stringref, L
+    256, 25 (stringref-namespace, stringref,
     <http://cbor.schmorp.de/stringref>)
         These tags are automatically decoded when encountered. They are only
         encoded, however, when "pack_strings" is enabled.
@@ -778,7 +841,8 @@
 
 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
     On perls that were built without 64 bit integer support (these are rare
-    nowadays, even on 32 bit architectures), support for any kind of 64 bit
+    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
     be truncated, corrupted, or otherwise not decoded correctly. This also
     includes string, array and map sizes that are stored as 64 bit integers.