diff options
| author | Ed Maste <emaste@FreeBSD.org> | 2026-03-23 15:41:51 +0000 |
|---|---|---|
| committer | Ed Maste <emaste@FreeBSD.org> | 2026-04-22 14:24:02 +0000 |
| commit | 967186fe0a54faf0681a49f78701c20afb3aa0ff (patch) | |
| tree | f2ac0ec63057189a45fd05d6ab4acceeee3ba141 /contrib/libcbor/doc | |
| parent | 9b8f4cfea45631b3c236e5b8e69e21ec085bd0be (diff) | |
libcbor: Update to 0.13.0
Sponsored by: The FreeBSD Foundation
(cherry picked from commit b5b9517bfe394e55088f5a05882eabae7e9b7b29)
Diffstat (limited to 'contrib/libcbor/doc')
20 files changed, 263 insertions, 245 deletions
diff --git a/contrib/libcbor/doc/source/api.rst b/contrib/libcbor/doc/source/api.rst index 75b0541cb94e..616f12103124 100644 --- a/contrib/libcbor/doc/source/api.rst +++ b/contrib/libcbor/doc/source/api.rst @@ -30,12 +30,12 @@ The API is designed to allow both very tight control & flexibility and general c api/encoding api/streaming_decoding api/streaming_encoding - api/type_0_1 - api/type_2 - api/type_3 - api/type_4 - api/type_5 - api/type_6 - api/type_7 + api/type_0_1_integers + api/type_2_byte_strings + api/type_3_strings + api/type_4_arrays + api/type_5_maps + api/type_6_tags + api/type_7_floats_ctrls .. [#] http://softwareengineering.vazexqi.com/files/pattern.html diff --git a/contrib/libcbor/doc/source/api/item_reference_counting.rst b/contrib/libcbor/doc/source/api/item_reference_counting.rst index 70075cb67e5b..f590ac2e2292 100644 --- a/contrib/libcbor/doc/source/api/item_reference_counting.rst +++ b/contrib/libcbor/doc/source/api/item_reference_counting.rst @@ -36,3 +36,4 @@ The destruction is synchronous and renders any pointers to items with refcount z .. doxygenfunction:: cbor_refcount .. doxygenfunction:: cbor_move .. doxygenfunction:: cbor_copy +.. doxygenfunction:: cbor_copy_definite diff --git a/contrib/libcbor/doc/source/api/streaming_encoding.rst b/contrib/libcbor/doc/source/api/streaming_encoding.rst index 25100da9b5e0..ebb2f72057af 100644 --- a/contrib/libcbor/doc/source/api/streaming_encoding.rst +++ b/contrib/libcbor/doc/source/api/streaming_encoding.rst @@ -7,7 +7,7 @@ exposes a low-level encoding API to encode CBOR objects on the fly. Unlike strings, etc.) instead of :type:`cbor_item_t`. The client is responsible for constructing the compound types correctly (e.g. terminating arrays). -Streaming encoding is typically used to create an streaming (indefinite length) CBOR :doc:`strings <type_2>`, :doc:`byte strings <type_3>`, :doc:`arrays <type_4>`, and :doc:`maps <type_5>`. Complete example: `examples/streaming_array.c <https://github.com/PJK/libcbor/blob/master/examples/streaming_array.c>`_ +Streaming encoding is typically used to create an streaming (indefinite length) CBOR :doc:`strings <type_2_byte_strings>`, :doc:`byte strings <type_3_strings>`, :doc:`arrays <type_4_arrays>`, and :doc:`maps <type_5_maps>`. Complete example: `examples/streaming_array.c <https://github.com/PJK/libcbor/blob/master/examples/streaming_array.c>`_ .. doxygenfunction:: cbor_encode_uint8 diff --git a/contrib/libcbor/doc/source/api/type_0_1.rst b/contrib/libcbor/doc/source/api/type_0_1_integers.rst index 4fc851dd1ed1..4fc851dd1ed1 100644 --- a/contrib/libcbor/doc/source/api/type_0_1.rst +++ b/contrib/libcbor/doc/source/api/type_0_1_integers.rst diff --git a/contrib/libcbor/doc/source/api/type_2.rst b/contrib/libcbor/doc/source/api/type_2_byte_strings.rst index ff9369a90d67..d0644fffb137 100644 --- a/contrib/libcbor/doc/source/api/type_2.rst +++ b/contrib/libcbor/doc/source/api/type_2_byte_strings.rst @@ -1,7 +1,7 @@ Type 2 – Byte strings ============================= -CBOR byte strings are just (ordered) series of bytes without further interpretation (unless there is a :doc:`tag <type_6>`). Byte string's length may or may not be known during encoding. These two kinds of byte strings can be distinguished using :func:`cbor_bytestring_is_definite` and :func:`cbor_bytestring_is_indefinite` respectively. +CBOR byte strings are just (ordered) series of bytes without further interpretation (unless there is a :doc:`tag <type_6_tags>`). Byte string's length may or may not be known during encoding. These two kinds of byte strings can be distinguished using :func:`cbor_bytestring_is_definite` and :func:`cbor_bytestring_is_indefinite` respectively. In case a byte string is indefinite, it is encoded as a series of definite byte strings. These are called "chunks". For example, the encoded item diff --git a/contrib/libcbor/doc/source/api/type_3.rst b/contrib/libcbor/doc/source/api/type_3_strings.rst index be06fc176566..847c474b0417 100644 --- a/contrib/libcbor/doc/source/api/type_3.rst +++ b/contrib/libcbor/doc/source/api/type_3_strings.rst @@ -1,7 +1,7 @@ Type 3 – UTF-8 strings ============================= -CBOR strings have the same structure as :doc:`type_2`. +CBOR strings have the same structure as :doc:`type_2_byte_strings`. ================================== ====================================================== Corresponding :type:`cbor_type` ``CBOR_TYPE_STRING`` diff --git a/contrib/libcbor/doc/source/api/type_4.rst b/contrib/libcbor/doc/source/api/type_4_arrays.rst index a76202f4a0fd..2fa615df0eb4 100644 --- a/contrib/libcbor/doc/source/api/type_4.rst +++ b/contrib/libcbor/doc/source/api/type_4_arrays.rst @@ -1,7 +1,7 @@ Type 4 – Arrays ============================= -CBOR arrays, just like :doc:`byte strings <type_2>` and :doc:`strings <type_3>`, can be encoded either as definite, or as indefinite. +CBOR arrays, just like :doc:`byte strings <type_2_byte_strings>` and :doc:`strings <type_3_strings>`, can be encoded either as definite, or as indefinite. Definite arrays have a fixed size which is stored in the header, whereas indefinite arrays do not and are terminated by a special "break" byte instead. Arrays are explicitly created or decoded as definite or indefinite and will be encoded using the corresponding wire representation, regardless of whether the actual size is known at the time of encoding. diff --git a/contrib/libcbor/doc/source/api/type_5.rst b/contrib/libcbor/doc/source/api/type_5_maps.rst index 7f7be273aba9..7f7be273aba9 100644 --- a/contrib/libcbor/doc/source/api/type_5.rst +++ b/contrib/libcbor/doc/source/api/type_5_maps.rst diff --git a/contrib/libcbor/doc/source/api/type_6.rst b/contrib/libcbor/doc/source/api/type_6_tags.rst index e98457ceae2a..1ee5f6949a2e 100644 --- a/contrib/libcbor/doc/source/api/type_6.rst +++ b/contrib/libcbor/doc/source/api/type_6_tags.rst @@ -5,7 +5,12 @@ Tag are additional metadata that can be used to extend or specialize the meaning For example, one might tag an array of numbers to communicate that it should be interpreted as a vector. -Please consult the official `IANA repository of CBOR tags <https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml>`_ before inventing new ones. +Please consult the official `IANA repository of CBOR tags <https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml>`_ for known registered values. + +Please note that libcbor does *not* understand the semantics of tags and will +process all `well-formed <https://datatracker.ietf.org/doc/html/rfc8949#name-terminology>`_ +tags regardless of whether they are valid with respect to the data they are +applied to. ================================== ====================================================== Corresponding :type:`cbor_type` ``CBOR_TYPE_TAG`` diff --git a/contrib/libcbor/doc/source/api/type_7.rst b/contrib/libcbor/doc/source/api/type_7_floats_ctrls.rst index b105402a08b2..d893fe37cb7b 100644 --- a/contrib/libcbor/doc/source/api/type_7.rst +++ b/contrib/libcbor/doc/source/api/type_7_floats_ctrls.rst @@ -60,9 +60,16 @@ Manipulating existing items .. doxygenfunction:: cbor_set_float8 -.. _api_type_7_hard_floats: +.. _api_type_7_floats_ctrls_half_floats: Half floats ~~~~~~~~~~~~ CBOR supports two `bytes wide ("half-precision") <https://en.wikipedia.org/wiki/Half-precision_floating-point_format>`_ floats which are not supported by the C language. *libcbor* represents them using `float <https://en.cppreference.com/w/c/language/type>` values throughout the API. Encoding will be performed by :func:`cbor_encode_half`, which will handle any values that cannot be represented as a half-float. + +Signaling NaNs +~~~~~~~~~~~~~~~~ + +`Signaling NaNs <https://en.wikipedia.org/wiki/NaN#Signaling_NaN)>`_ are always encoded as a standard, "quiet" NaN. + +The reason for this simplification is that standard C does not offer a way to handle the signaling payload without assumptions about the host architecture. See https://github.com/PJK/libcbor/issues/336 for more context. diff --git a/contrib/libcbor/doc/source/conf.py b/contrib/libcbor/doc/source/conf.py index 0eee7103bb5a..52c19154d04e 100644 --- a/contrib/libcbor/doc/source/conf.py +++ b/contrib/libcbor/doc/source/conf.py @@ -77,8 +77,8 @@ copyright = '2014 - 2020, Pavel Kalvoda' # built documents. # # The short X.Y version. -version = '0.11' -release = '0.11.0' +version = '0.13' +release = '0.13.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/contrib/libcbor/doc/source/development.rst b/contrib/libcbor/doc/source/development.rst index 0b0ac21007ed..9715476a55d6 100644 --- a/contrib/libcbor/doc/source/development.rst +++ b/contrib/libcbor/doc/source/development.rst @@ -99,7 +99,8 @@ Development dependencies - There are some `Ruby <https://www.ruby-lang.org/en/>`_ scripts in ``misc`` - `Valgrind <http://valgrind.org/>`_ (memory correctness & profiling) - `GCOV/LCOV <http://ltp.sourceforge.net/coverage/lcov.php>`_ (test coverage) -- `clang-format` +- `clang-format` (linter) +- `cmakelang <https://cmake-format.readthedocs.io/en/latest/index.html>`_ (linter) Installing *sphinx* @@ -107,13 +108,16 @@ Installing *sphinx* .. code-block:: bash - pip install sphinx - pip install sphinx_rtd_theme - pip install breathe - pip install https://github.com/lepture/python-livereload/archive/master.zip - pip install sphinx-autobuild + pip install -r doc/source/requirements.txt -Further instructions on configuring advanced features can be found at `<http://read-the-docs.readthedocs.org/en/latest/install.html>`_. + +To update the Python dependencies: + +.. code-block:: bash + + pip-compile --upgrade doc/source/requirements.in + +Sphinx reference: `<http://read-the-docs.readthedocs.org/en/latest/install.html>`_. Live preview of docs diff --git a/contrib/libcbor/doc/source/getting_started.rst b/contrib/libcbor/doc/source/getting_started.rst index 98c5a3956337..5f67a86f66c1 100644 --- a/contrib/libcbor/doc/source/getting_started.rst +++ b/contrib/libcbor/doc/source/getting_started.rst @@ -38,31 +38,73 @@ Prerequisites: A handful of configuration flags can be passed to `cmake`. The following table lists libcbor compile-time directives and several important generic flags. -======================== ======================================================= ====================== ===================================================================================================================== -Option Meaning Default Possible values ------------------------- ------------------------------------------------------- ---------------------- --------------------------------------------------------------------------------------------------------------------- -``CMAKE_C_COMPILER`` C compiler to use ``cc`` ``gcc``, ``clang``, ``clang-3.5``, ... -``CMAKE_INSTALL_PREFIX`` Installation prefix System-dependent ``/usr/local/lib``, ... -``BUILD_SHARED_LIBS`` Build as a shared library ``OFF`` ``ON``, ``OFF`` -``HUGE_FUZZ`` :doc:`Fuzz test </tests>` with 8GB of data ``OFF`` ``ON``, ``OFF`` -``SANE_MALLOC`` Assume ``malloc`` will refuse unreasonable allocations ``OFF`` ``ON``, ``OFF`` -``COVERAGE`` Generate test coverage instrumentation ``OFF`` ``ON``, ``OFF`` -``WITH_TESTS`` Build unit tests (see :doc:`development`) ``OFF`` ``ON``, ``OFF`` -======================== ======================================================= ====================== ===================================================================================================================== +.. list-table:: + :header-rows: 1 + + * - Option + - Meaning + - Default + - Possible values + * - ``CMAKE_C_COMPILER`` + - C compiler to use + - ``cc`` + - ``gcc``, ``clang``, ``clang-3.5``, ... + * - ``CMAKE_INSTALL_PREFIX`` + - Installation prefix + - System-dependent + - ``/usr/local/lib``, ... + * - ``CMAKE_INTERPROCEDURAL_OPTIMIZATION`` + - Enable LTO (if supported) + - System-dependent + - ``ON``, ``OFF`` + * - ``BUILD_SHARED_LIBS`` + - Build as a shared library + - ``OFF`` + - ``ON``, ``OFF`` + * - ``HUGE_FUZZ`` + - :doc:`Fuzz test </tests>` with 8GB of data + - ``OFF`` + - ``ON``, ``OFF`` + * - ``SANE_MALLOC`` + - Assume ``malloc`` will refuse unreasonable allocations + - ``OFF`` + - ``ON``, ``OFF`` + * - ``COVERAGE`` + - Generate test coverage instrumentation + - ``OFF`` + - ``ON``, ``OFF`` + * - ``WITH_TESTS`` + - Build unit tests (see :doc:`development`) + - ``OFF`` + - ``ON``, ``OFF`` + The following configuration options will also be defined as macros [#]_ in ``<cbor/common.h>`` and can therefore be used in client code: -======================== ======================================================= ====================== ===================================================================================================================== -Option Meaning Default Possible values ------------------------- ------------------------------------------------------- ---------------------- --------------------------------------------------------------------------------------------------------------------- -``CBOR_PRETTY_PRINTER`` Include a pretty-printing routine ``ON`` ``ON``, ``OFF`` -``CBOR_BUFFER_GROWTH`` Factor for buffer growth & shrinking ``2`` Decimals > 1 -======================== ======================================================= ====================== ===================================================================================================================== +.. list-table:: + :header-rows: 1 + + * - Option + - Meaning + - Default + - Possible values + * - ``CBOR_PRETTY_PRINTER`` + - Include a pretty-printing routine + - ``ON`` + - ``ON``, ``OFF`` + * - ``CBOR_BUFFER_GROWTH`` + - Factor for buffer growth & shrinking + - ``2`` + - Decimals > 1 + .. [#] ``ON`` & ``OFF`` will be translated to ``1`` and ``0`` using `cmakedefine <https://cmake.org/cmake/help/v3.2/command/configure_file.html?highlight=cmakedefine>`_. If you want to pass other custom configuration options, please refer to `<http://www.cmake.org/Wiki/CMake_Useful_Variables>`_. +.. note:: + When ``CMAKE_INTERPROCEDURAL_OPTIMIZATION`` is enabled, the generated static library (`libcbor.a`) should be used with an LTO-enabled linker downstream. On LLVM toolchains without bitcode embedding (`-fembed-bitcode`), the archive will contain LLVM IR only and linking without LTO `will not work <https://github.com/PJK/libcbor/issues/372>`_. + .. warning:: ``CBOR_CUSTOM_ALLOC`` has been `removed <https://github.com/PJK/libcbor/pull/237>`_. Custom allocators (historically a controlled by a build flag) are always enabled. diff --git a/contrib/libcbor/doc/source/index.rst b/contrib/libcbor/doc/source/index.rst index d3d62cf75c41..06ef1a059891 100644 --- a/contrib/libcbor/doc/source/index.rst +++ b/contrib/libcbor/doc/source/index.rst @@ -3,6 +3,8 @@ libcbor Documentation for version |release|, updated on |today|. +Git repo: https://github.com/PJK/libcbor + Overview -------- *libcbor* is a C library for parsing and generating CBOR_, the general-purpose schema-less binary data format. @@ -28,7 +30,7 @@ Contents .. toctree:: getting_started - using + tutorial api tests standard_conformance diff --git a/contrib/libcbor/doc/source/internal.rst b/contrib/libcbor/doc/source/internal.rst index e30cb11dffa1..07cd7cfc10c6 100644 --- a/contrib/libcbor/doc/source/internal.rst +++ b/contrib/libcbor/doc/source/internal.rst @@ -82,7 +82,7 @@ Generally speaking, data items consist of three parts: .. member:: unsigned char * data - Contains pointer to the actual data. Small, fixed size items (:doc:`api/type_0_1`, :doc:`api/type_6`, :doc:`api/type_7`) are allocated as a single memory block. + Contains pointer to the actual data. Small, fixed size items (:doc:`api/type_0_1_integers`, :doc:`api/type_6_tags`, :doc:`api/type_7_floats_ctrls`) are allocated as a single memory block. Consider the following snippet @@ -103,7 +103,7 @@ Generally speaking, data items consist of three parts: | | +--- item +--- item->data - Dynamically sized types (:doc:`api/type_2`, :doc:`api/type_3`, :doc:`api/type_4`, :doc:`api/type_5`) may store handle and data in separate locations. This enables creating large items (e.g :doc:`byte strings <api/type_2>`) without :func:`realloc` or copying large blocks of memory. One simply attaches the correct pointer to the handle. + Dynamically sized types (:doc:`api/type_2_byte_strings`, :doc:`api/type_3_strings`, :doc:`api/type_4_arrays`, :doc:`api/type_5_maps`) may store handle and data in separate locations. This enables creating large items (e.g :doc:`byte strings <api/type_2_byte_strings>`) without :func:`realloc` or copying large blocks of memory. One simply attaches the correct pointer to the handle. .. type:: cbor_item_metadata @@ -112,7 +112,7 @@ Generally speaking, data items consist of three parts: .. member:: struct _cbor_int_metadata int_metadata - Used both by both :doc:`api/type_0_1` + Used both by both :doc:`api/type_0_1_integers` .. member:: struct _cbor_bytestring_metadata bytestring_metadata .. member:: struct _cbor_string_metadata string_metadata diff --git a/contrib/libcbor/doc/source/requirements.in b/contrib/libcbor/doc/source/requirements.in new file mode 100644 index 000000000000..000ba6286d17 --- /dev/null +++ b/contrib/libcbor/doc/source/requirements.in @@ -0,0 +1,5 @@ +sphinx +sphinx_rtd_theme +breathe +livereload +sphinx-autobuild diff --git a/contrib/libcbor/doc/source/requirements.txt b/contrib/libcbor/doc/source/requirements.txt index 502d79cc62e6..44b77ded4f36 100644 --- a/contrib/libcbor/doc/source/requirements.txt +++ b/contrib/libcbor/doc/source/requirements.txt @@ -1,31 +1,91 @@ -alabaster==0.7.13 -Babel==2.13.1 -breathe==4.35.0 -certifi==2023.11.17 -charset-normalizer==3.3.2 +# +# This file is autogenerated by pip-compile with Python 3.13 +# by the following command: +# +# pip-compile doc/source/requirements.in +# +alabaster==1.0.0 + # via sphinx +anyio==4.9.0 + # via + # starlette + # watchfiles +babel==2.17.0 + # via sphinx +breathe==4.36.0 + # via -r doc/source/requirements.in +certifi==2025.1.31 + # via requests +charset-normalizer==3.4.1 + # via requests +click==8.1.8 + # via uvicorn colorama==0.4.6 -docutils==0.18.1 -idna==3.4 + # via sphinx-autobuild +docutils==0.21.2 + # via + # sphinx + # sphinx-rtd-theme +h11==0.14.0 + # via uvicorn +idna==3.10 + # via + # anyio + # requests imagesize==1.4.1 -importlib-metadata==6.8.0 -Jinja2==3.1.2 -livereload==2.6.3 -MarkupSafe==2.1.3 -packaging==23.2 -Pygments==2.16.1 -pyparsing==3.1.1 -pytz==2021.3 -requests==2.31.0 + # via sphinx +jinja2==3.1.6 + # via sphinx +livereload==2.7.1 + # via -r doc/source/requirements.in +markupsafe==3.0.2 + # via jinja2 +packaging==25.0 + # via sphinx +pygments==2.19.1 + # via sphinx +requests==2.32.3 + # via sphinx +roman-numerals-py==3.1.0 + # via sphinx +sniffio==1.3.1 + # via anyio snowballstemmer==2.2.0 -Sphinx==7.2.6 -sphinx-autobuild==2021.3.14 -sphinx-rtd-theme==1.3.0 -sphinxcontrib-applehelp==1.0.7 -sphinxcontrib-devhelp==1.0.5 -sphinxcontrib-htmlhelp==2.0.4 + # via sphinx +sphinx==8.2.3 + # via + # -r doc/source/requirements.in + # breathe + # sphinx-autobuild + # sphinx-rtd-theme + # sphinxcontrib-jquery +sphinx-autobuild==2024.10.3 + # via -r doc/source/requirements.in +sphinx-rtd-theme==3.0.2 + # via -r doc/source/requirements.in +sphinxcontrib-applehelp==2.0.0 + # via sphinx +sphinxcontrib-devhelp==2.0.0 + # via sphinx +sphinxcontrib-htmlhelp==2.1.0 + # via sphinx +sphinxcontrib-jquery==4.1 + # via sphinx-rtd-theme sphinxcontrib-jsmath==1.0.1 -sphinxcontrib-qthelp==1.0.6 -sphinxcontrib-serializinghtml==1.1.9 -tornado==6.3.3 -urllib3==2.1.0 -zipp==3.17.0 + # via sphinx +sphinxcontrib-qthelp==2.0.0 + # via sphinx +sphinxcontrib-serializinghtml==2.0.0 + # via sphinx +starlette==0.46.2 + # via sphinx-autobuild +tornado==6.4.2 + # via livereload +urllib3==2.4.0 + # via requests +uvicorn==0.34.2 + # via sphinx-autobuild +watchfiles==1.0.5 + # via sphinx-autobuild +websockets==15.0.1 + # via sphinx-autobuild diff --git a/contrib/libcbor/doc/source/standard_conformance.rst b/contrib/libcbor/doc/source/standard_conformance.rst index 62965f0c4493..4f57bb4c091f 100644 --- a/contrib/libcbor/doc/source/standard_conformance.rst +++ b/contrib/libcbor/doc/source/standard_conformance.rst @@ -13,5 +13,5 @@ There is no explicit limitation of indefinite length byte strings. [#]_ *libcbor --------------------------------- As of C99 and even C11, there is no standard implementation for 2 bytes floats. *libcbor* packs them as a `float <https://en.cppreference.com/w/c/language/type>`. When encoding, *libcbor* selects the appropriate wire representation based on metadata and the actual value. This applies both to canonical and normal mode. -For more information on half-float serialization, please refer to the section on :ref:`api_type_7_hard_floats`. +For more information on half-float serialization, please refer to the section on :ref:`api_type_7_floats_ctrls_half_floats`. diff --git a/contrib/libcbor/doc/source/tutorial.rst b/contrib/libcbor/doc/source/tutorial.rst new file mode 100644 index 000000000000..81859ccb2192 --- /dev/null +++ b/contrib/libcbor/doc/source/tutorial.rst @@ -0,0 +1,66 @@ +Tutorial +=========================== + +*libcbor* is a C library to encode, decode, and manipulate CBOR data. It is to CBOR to what `cJSON <https://github.com/DaveGamble/cJSON>`_ is to JSON. We assume you are familiar with the CBOR standard. If not, we recommend `cbor.io <http://cbor.io/>`_. + + +Where to start +-------------- + +- Skim through the Crash course section below. +- Examples of of how to read, write, manipulate, and translate data to and from JSON using *libcbor* are in the `examples directory <https://github.com/PJK/libcbor/tree/master/examples>`_. +- The :doc:`API documentation <api>` is a complete reference of *libcbor*. + + +Crash course +---------------- + +CBOR data objects are ``cbor_item_t`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. literalinclude:: ../../examples/crash_course.c + :language: C + :start-after: // Part 1: Begin + :end-before: // Part 1: End + + +Objects can be serialized and deserialized +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. literalinclude:: ../../examples/crash_course.c + :language: C + :start-after: // Part 2: Begin + :end-before: // Part 2: End + + +Reference counting +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. literalinclude:: ../../examples/crash_course.c + :language: C + :start-after: // Part 3: Begin + :end-before: // Part 3: End + + +Moving intermediate values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. literalinclude:: ../../examples/crash_course.c + :language: C + :start-after: // Part 4: Begin + :end-before: // Part 4: End + + +Ownership +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. literalinclude:: ../../examples/crash_course.c + :language: C + :start-after: // Part 5: Begin + :end-before: // Part 5: End + + +Streaming IO +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +See https://github.com/PJK/libcbor/blob/master/examples/streaming_array.c, https://github.com/PJK/libcbor/blob/master/examples/streaming_parser.c
\ No newline at end of file diff --git a/contrib/libcbor/doc/source/using.rst b/contrib/libcbor/doc/source/using.rst deleted file mode 100644 index ccb7372f23b6..000000000000 --- a/contrib/libcbor/doc/source/using.rst +++ /dev/null @@ -1,174 +0,0 @@ -Usage & preliminaries -======================= - -Version information --------------------- - -libcbor exports its version using three self-explanatory macros: - - - ``CBOR_MAJOR_VERSION`` - - ``CBOR_MINOR_VERSION`` - - ``CBOR_PATCH_VERSION`` - -The ``CBOR_VERSION`` is a string concatenating these three identifiers into one (e.g. ``0.2.0``). - -In order to simplify version comparisons, the version is also exported as - -.. code-block:: c - - #define CBOR_HEX_VERSION ((CBOR_MAJOR_VERSION << 16) | (CBOR_MINOR_VERSION << 8) | CBOR_PATCH_VERSION) - -Since macros are difficult to work with through FFIs, the same information is also available through three ``uint8_t`` constants, -namely - - - ``cbor_major_version`` - - ``cbor_minor_version`` - - ``cbor_patch_version`` - - -Headers to include ---------------------- - -The ``cbor.h`` header includes all the symbols. If, for any reason, you don't want to include all the exported symbols, -feel free to use just some of the ``cbor/*.h`` headers: - - - ``cbor/arrays.h`` - :doc:`api/type_4` - - ``cbor/bytestrings.h`` - :doc:`api/type_2` - - ``cbor/callbacks.h`` - Callbacks used for :doc:`api/streaming_decoding` - - ``cbor/common.h`` - Common utilities - always transitively included - - ``cbor/data.h`` - Data types definitions - always transitively included - - ``cbor/encoding.h`` - Streaming encoders for :doc:`api/streaming_encoding` - - ``cbor/floats_ctrls.h`` - :doc:`api/type_7` - - ``cbor/ints.h`` - :doc:`api/type_0_1` - - ``cbor/maps.h`` - :doc:`api/type_5` - - ``cbor/serialization.h`` - High level serialization such as :func:`cbor_serialize` - - ``cbor/streaming.h`` - Home of :func:`cbor_stream_decode` - - ``cbor/strings.h`` - :doc:`api/type_3` - - ``cbor/tags.h`` - :doc:`api/type_6` - - -Using libcbor --------------- - -If you want to get more familiar with CBOR, we recommend the `cbor.io <http://cbor.io/>`_ website. Once you get the grasp -of what is it CBOR does, the examples (located in the ``examples`` directory) should give you a good feel of the API. The -:doc:`API documentation <api>` should then provide with all the information you may need. - - -**Creating and serializing items** - -.. code-block:: c - - #include "cbor.h" - #include <stdio.h> - - int main(int argc, char * argv[]) - { - /* Preallocate the map structure */ - cbor_item_t * root = cbor_new_definite_map(2); - /* Add the content */ - cbor_map_add(root, (struct cbor_pair) { - .key = cbor_move(cbor_build_string("Is CBOR awesome?")), - .value = cbor_move(cbor_build_bool(true)) - }); - cbor_map_add(root, (struct cbor_pair) { - .key = cbor_move(cbor_build_uint8(42)), - .value = cbor_move(cbor_build_string("Is the answer")) - }); - /* Output: `buffer_size` bytes of data in the `buffer` */ - unsigned char * buffer; - size_t buffer_size; - cbor_serialize_alloc(root, &buffer, &buffer_size); - - fwrite(buffer, 1, buffer_size, stdout); - free(buffer); - - fflush(stdout); - cbor_decref(&root); - } - - -**Reading serialized data** - -.. code-block:: c - - #include "cbor.h" - #include <stdio.h> - - /* - * Reads data from a file. Example usage: - * $ ./examples/readfile examples/data/nested_array.cbor - */ - - int main(int argc, char * argv[]) - { - FILE * f = fopen(argv[1], "rb"); - fseek(f, 0, SEEK_END); - size_t length = (size_t)ftell(f); - fseek(f, 0, SEEK_SET); - unsigned char * buffer = malloc(length); - fread(buffer, length, 1, f); - - /* Assuming `buffer` contains `info.st_size` bytes of input data */ - struct cbor_load_result result; - cbor_item_t * item = cbor_load(buffer, length, &result); - /* Pretty-print the result */ - cbor_describe(item, stdout); - fflush(stdout); - /* Deallocate the result */ - cbor_decref(&item); - - fclose(f); - } - - -**Using the streaming parser** - -.. code-block:: c - - #include "cbor.h" - #include <stdio.h> - #include <string.h> - - /* - * Illustrates how one might skim through a map (which is assumed to have - * string keys and values only), looking for the value of a specific key - * - * Use the examples/data/map.cbor input to test this. - */ - - const char * key = "a secret key"; - bool key_found = false; - - void find_string(void * _ctx, cbor_data buffer, size_t len) - { - if (key_found) { - printf("Found the value: %*s\n", (int) len, buffer); - key_found = false; - } else if (len == strlen(key)) { - key_found = (memcmp(key, buffer, len) == 0); - } - } - - int main(int argc, char * argv[]) - { - FILE * f = fopen(argv[1], "rb"); - fseek(f, 0, SEEK_END); - size_t length = (size_t)ftell(f); - fseek(f, 0, SEEK_SET); - unsigned char * buffer = malloc(length); - fread(buffer, length, 1, f); - - struct cbor_callbacks callbacks = cbor_empty_callbacks; - struct cbor_decoder_result decode_result; - size_t bytes_read = 0; - callbacks.string = find_string; - while (bytes_read < length) { - decode_result = cbor_stream_decode(buffer + bytes_read, - length - bytes_read, - &callbacks, NULL); - bytes_read += decode_result.read; - } - - fclose(f); - } |