[ViewVC] Diff of: cvs/CBOR-XS/doc/stringref.pod

Comparing CBOR-XS/doc/stringref.pod (file contents):
Revision 1.3 by root, Thu Nov 28 10:16:50 2013 UTC vs.
Revision 1.6 by root, Mon Apr 30 11:24:17 2018 UTC

 encoder to be under control of the sequence in which data items are
 encoded into the CBOR stream. This means these tags cannot be implemented
 on top of every generic CBOR encoder/decoder (which might reorder entries
 in a map); they typically need to be integrated into their works.
+=head2 DESIGN RATIONALE
+The stringref tag was chosen to be short, without requiring standards
+action. The namespace tag is rare, so doesn't benefit from a short
+encoding as much.
+Implicit tagging/counting was chosen to support stream encoders. Having
+to tag strings first requires either multiple passes over the data (which
+might not be available, ruling out some encoders) or tagging more strings
+than needed (wasting space). Explicit tagging also isn't necessarily
+better even under optimal conditions, as the explicit tags waste space.
+Stream decoders are affected less by implicit tagging than encoders.
+The namespace tag was introduced for two reasons: first to allow embedding
+of CBOR strings into other CBOR strings, secondly for decoding efficiency
+- the decoder only has to expect stringref tags inside namespaces and
+therefore doesn't have to maintain extra state outside of them.
 =head1 EXAMPLES
 The array-of-maps from the rationale example would normally compress to a
 CBOR text of 83 bytes. Using this extension where possible, this reduces
 to 74 bytes:
     "jjj", "kkk", "lll", "mmm", "nnn", "ooo", "ppp", "qqq", "rrr",
     "333",
     "ssss",
     "qqq", "rrr", "ssss"]
-The strings "1", "4" and "rrr" are too short to get an index assigned. All others that are
+The strings "1", "4" and "rrr" are too short to get an index assigned. All
-not encoded with a stringref do:
+others that are not encoded with a stringref do (this assumes that JSON
+strings are encoded as CBOR byte strings):
    d9 0100           # tag(256)
       98 20          # array(32)
          41          # bytes(1)
             31       # "1"
             707070   # "ppp"
          43          # bytes(3)
             717171   # "qqq"
          43          # bytes(3)
             727272   # "rrr"
+         d8 19       # tag(25)
+            01       # unsigned(1)
          44          # bytes(4)
             73737373 # "ssss"
-         d8 19       # tag(25)
-            01       # unsigned(1)
          d8 19       # tag(25)
             17       # unsigned(23)
          43          # bytes(3)
             727272   # "rrr"
          d8 19       # tag(25)
 The decoded data structure might look like this:
   ["aaa","aaa",["bbb","aaa","aaa"],["ccc","ccc"],"aaa"]
+=head1 IMPLEMENTATIONS
+This section lists known implementations of this extension (L<drop me a
+mail|mailto:cbor@schmorp.de?Subject=CBOR-stringref> if you want to be
+listed here).
+=over 4
+=item * [Perl] L<CBOR::XS|http://software.schmorp.de/pkg/CBOR-XS.html> (reference implementation)
+=back

Diff Legend

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

Comparing CBOR-XS/doc/stringref.pod (file contents): Revision 1.3 by root, Thu Nov 28 10:16:50 2013 UTC vs. Revision 1.6 by root, Mon Apr 30 11:24:17 2018 UTC

Diff Legend

Comparing CBOR-XS/doc/stringref.pod (file contents):
Revision 1.3 by root, Thu Nov 28 10:16:50 2013 UTC vs.
Revision 1.6 by root, Mon Apr 30 11:24:17 2018 UTC