vendor/libcbor/0.13.0vendor/libcbor

9 files changed, 155 insertions, 205 deletions

diff --git a/doc/source/api/item_reference_counting.rst b/doc/source/api/item_reference_counting.rst
index 70075cb67e5b..f590ac2e2292 100644
--- a/doc/source/api/item_reference_counting.rst
+++ b/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/doc/source/conf.py b/doc/source/conf.py
index 4574669505e8..52c19154d04e 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -77,8 +77,8 @@ copyright = '2014 - 2020, Pavel Kalvoda'
 # built documents.
 #
 # The short X.Y version.
-version = '0.12'
-release = '0.12.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/doc/source/development.rst b/doc/source/development.rst
index 5471047317af..9715476a55d6 100644
--- a/doc/source/development.rst
+++ b/doc/source/development.rst
@@ -108,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/doc/source/getting_started.rst b/doc/source/getting_started.rst
index ee57c094458d..5f67a86f66c1 100644
--- a/doc/source/getting_started.rst
+++ b/doc/source/getting_started.rst
@@ -102,6 +102,9 @@ The following configuration options will also be defined as macros [#]_ in ``<cb
 
 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/doc/source/index.rst b/doc/source/index.rst
index d3d62cf75c41..06ef1a059891 100644
--- a/doc/source/index.rst
+++ b/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/doc/source/requirements.in b/doc/source/requirements.in
new file mode 100644
index 000000000000..000ba6286d17
--- /dev/null
+++ b/doc/source/requirements.in
@@ -0,0 +1,5 @@
+sphinx
+sphinx_rtd_theme
+breathe
+livereload
+sphinx-autobuild
diff --git a/doc/source/requirements.txt b/doc/source/requirements.txt
index 1b34e120b8b2..44b77ded4f36 100644
--- a/doc/source/requirements.txt
+++ b/doc/source/requirements.txt
@@ -1,47 +1,91 @@
+#
+# 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
-anyio==4.8.0
+    # via sphinx
+anyio==4.9.0
+    # via
+    #   starlette
+    #   watchfiles
 babel==2.17.0
+    # via sphinx
 breathe==4.36.0
-build==1.2.2.post1
+    # 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
+    # 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==8.6.1
-Jinja2==3.1.6
-livereload @ https://github.com/lepture/python-livereload/archive/master.zip#sha256=95371213cf9107242808ea6e1353b524d7c38d96e299604e651e43271263352c
-MarkupSafe==3.0.2
-packaging==24.2
-pip-tools==7.4.1
-Pygments==2.19.1
-pyparsing==3.2.1
-pyproject_hooks==1.2.0
-pytz==2025.1
+    # 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
-setuptools==75.8.2
-six==1.17.0
+    # via sphinx
 sniffio==1.3.1
+    # via anyio
 snowballstemmer==2.2.0
-Sphinx==8.2.3
+    # 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
+    # via sphinx
 sphinxcontrib-qthelp==2.0.0
+    # via sphinx
 sphinxcontrib-serializinghtml==2.0.0
-starlette==0.46.0
+    # via sphinx
+starlette==0.46.2
+    # via sphinx-autobuild
 tornado==6.4.2
-urllib3==2.3.0
-uvicorn==0.34.0
-watchfiles==1.0.4
-websockets==15.0
-wheel==0.45.1
-zipp==3.21.0
+    # 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/doc/source/tutorial.rst b/doc/source/tutorial.rst
new file mode 100644
index 000000000000..81859ccb2192
--- /dev/null
+++ b/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/doc/source/using.rst b/doc/source/using.rst
deleted file mode 100644
index c6688bbad7bd..000000000000
--- a/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_arrays`
- - ``cbor/bytestrings.h`` - :doc:`api/type_2_byte_strings`
- - ``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_floats_ctrls`
- - ``cbor/ints.h`` - :doc:`api/type_0_1_integers`
- - ``cbor/maps.h`` - :doc:`api/type_5_maps`
- - ``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_strings`
- - ``cbor/tags.h`` - :doc:`api/type_6_tags`
-
-
-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);
-    }