lib/qcbor/README.md

3 **QCBOR** is a powerful, commercial-quality CBOR encoder-decoder that
25   analyzers easier.  Simpler code because there is no support for
28   to native C representations is supported.
30 **Small simple memory model** – Malloc is not needed. The encode
31   context is 176 bytes, decode context is 312 bytes and the
32   description of decoded data item is 56 bytes. Stack use is light and
33   there is no recursion. The caller supplies the memory to hold the
40   items is automatically performed. This makes decoding of complex
44   and formats in the specification are supported. Map sorting is main
45   CBOR feature that is not supported.  The same decoding API supports
47   indefinite length strings is supported but requires a string
48   allocator be set up. Encoding of indefinite length strings is
58   code is less than 4KB on 64-bit x86 CPUs. The design is such that
59   object code for QCBOR APIs not used is not referenced.
61 **Clear documented public interface** – The public interface is
78 map labels, an error, is automatically performed.
80 An internal error state is maintained. This simplifies the decode
81 implementation as an error check is only needed at the end of the
84 An outcome is that decoding implementations are simple and involve
113 TinyCBOR is a popular widely used implementation. Like QCBOR,
114 it is a solid, well-maintained commercial quality implementation. This
115 section is for folks trying to understand the difference in
118 TinyCBOR's API is more minimalist and closer to the CBOR
119 encoding mechanics than QCBOR's. QCBOR's API is at a somewhat higher
123 RFC 8949. The main part missing is sorting of maps when encoding.
128 larger.  QCBOR encoding is actually smaller, but QCBOR decoding is
129 larger. This includes the code to call the library, which is about the
131 is a bit more powerful, so you get value for the extra code brought
136 decode function. In many cases the error check is only needed as the
153 fetched and converted to a C uint64_t whether the input CBOR is an
155 big number, decimal fraction or a big float. The conversion is
159 treats this similar to entering an array with one item. This is
161 byte-string wrapping.  The implementation of these protocols is
164 QCBOR's test suite is written in the same portable C that QCBOR is
165 where TinyCBOR requires Qt for its test. QCBOR's test suite is
171 The official current release is version 1.4.1 Changes over the last few
173 documentation improvements. QCBOR 1.x is highly stable.
175 Work on some larger feature additions is ongoing in "dev" branch.
186 There is a simple makefile for the UNIX style command line binary that
187 compiles everything to run the tests. CMake is also available, please read
209 this work straight away, whatever your development environment is.
232 existing CMake environment. The result of the build process is a static library,
281 If full floating-point is not needed, the following #defines can be
308 When this is defined, the QCBOR functionality lost is minimal and only
312 * There is no conversion between floats and integers when decoding. For
323 defining this is to remove dependency on floating point hardware and
336 such is also supported. Floating-point dates are still
339 The primary reason to define this is to save object code.
347 headers). This is useful if the compiler options deny the usage of floating
348 point operations completely, and the usage soft floating point ABI is not
354 which float-point related code is generated. For example,
355 it is usually possible to give options to the compiler to avoid all
381 All QCBOR_DISABLE_XXX are set and compiler stack frame checking is disabled
382 for smallest but not for largest. Smallest is the library functions for a
394  main factor is the number of QCBOR functions called and
396  interdependency so only code necessary for the called functions is
399  Encoding is simpler and smaller. An encode-only implementation may
421  The gcc compiler output is usually smaller than llvm because stack
424  stack gaurds with llvm. It is safe to turn off stack gaurds with this
428  If QCBOR is installed as a shared library, then of course only one
429  copy of the code is in memory no matter how many applications use it.
434 code. The amount saved is an approximation.
451 when you are confident that an encoding implementation is complete and
457 it. Their main use is when encoding has to be done on a very
459 device, it is good to prohibit use of indefinite lengths so the
482 a single tag, the error is unrecoverable so it is suitable only for protocols that
489 QCBOR_DECODE_MODE_MAP_STRINGS_ONLY. It is fairly common for CBOR-based
496  When creating a decode implementation, there is a choice of whether
503  brings in about 2KB of object code.  If object code size is not a
504  concern, then it is probably better to use spiffy decode because it
505  is less work, there is less complexity and less testing to worry
508  If code size is a concern, then use of QCBORDecode_GetNext() will
510  protocols. However, if the CBOR protocol is complex then use of
512  protocol is one that involves decoding a lot of maps or maps that
514  because the general purpose spiffy decode map processor is the one
526 * [ctoken](https://github.com/laurencelundblade/ctoken) is an implementation of
543 QCBOR is available under what is essentially the 3-Clause BSD License.