diff options
Diffstat (limited to 'sources/shiboken6/doc/typesystem_containers.rst')
| -rw-r--r-- | sources/shiboken6/doc/typesystem_containers.rst | 114 |
1 files changed, 62 insertions, 52 deletions
diff --git a/sources/shiboken6/doc/typesystem_containers.rst b/sources/shiboken6/doc/typesystem_containers.rst index 5c4abee44..b5593e20f 100644 --- a/sources/shiboken6/doc/typesystem_containers.rst +++ b/sources/shiboken6/doc/typesystem_containers.rst @@ -19,7 +19,8 @@ instead of a Python list. Manipulations like adding or removing elements can applied directly to them using the C++ container functions. This is achieved by specifying the name and the instantiated type -in the ``opaque-containers`` attribute of :ref:`container-type`. +in the ``opaque-containers`` attribute of :ref:`container-type` +or using the :ref:`opaque-container` element for existing container types. A second use case are public fields of container types. In the normal case, they are converted to Python containers on read access. By a field modification, @@ -34,41 +35,50 @@ The table below lists the functions supported for opaque sequence containers besides the sequence protocol (element access via index and ``len()``). Both the STL and the Qt naming convention (which resembles Python's) are supported: - +-------------------------------------------+-----------------------------------+ - |Function | Description | - +-------------------------------------------+-----------------------------------+ - | ``push_back(value)``, ``append(value)`` | Appends *value* to the sequence. | - +-------------------------------------------+-----------------------------------+ - | ``push_front(value)``, ``prepend(value)`` | Prepends *value* to the sequence. | - +-------------------------------------------+-----------------------------------+ - | ``clear()`` | Clears the sequence. | - +-------------------------------------------+-----------------------------------+ - | ``pop_back()``, ``removeLast()`` | Removes the last element. | - +-------------------------------------------+-----------------------------------+ - | ``pop_front()``, ``removeFirst()`` | Removes the first element. | - +-------------------------------------------+-----------------------------------+ - | ``reserve(size)`` | For containers that support it | - | | (``std::vector``, ``QList``), | - | | allocate memory for at least | - | | ``size`` elements, preventing | - | | reallocations. | - +-------------------------------------------+-----------------------------------+ - | ``capacity()`` | For containers that support it | - | | (``std::vector``, ``QList``), | - | | return the number of elements | - | | that can be stored without | - | | reallocation. | - +-------------------------------------------+-----------------------------------+ - | ``data()`` | For containers that support it | - | | (``std::vector``, ``QList``), | - | | return a buffer viewing the | - | | memory. | - +-------------------------------------------+-----------------------------------+ - | ``constData()`` | For containers that support it | - | | (``std::vector``, ``QList``), | - | | return a read-only buffer viewing | - | | the memory. | - +-------------------------------------------+-----------------------------------+ ++-------------------------------------------+-----------------------------------+ +|Function | Description | ++-------------------------------------------+-----------------------------------+ +| ``push_back(value)``, ``append(value)`` | Appends *value* to the sequence. | ++-------------------------------------------+-----------------------------------+ +| ``push_front(value)``, ``prepend(value)`` | Prepends *value* to the sequence. | ++-------------------------------------------+-----------------------------------+ +| ``clear()`` | Clears the sequence. | ++-------------------------------------------+-----------------------------------+ +| ``pop_back()``, ``removeLast()`` | Removes the last element. | ++-------------------------------------------+-----------------------------------+ +| ``pop_front()``, ``removeFirst()`` | Removes the first element. | ++-------------------------------------------+-----------------------------------+ +| ``reserve(size)`` | For containers that support it | +| | (``std::vector``, ``QList``), | +| | allocate memory for at least | +| | ``size`` elements, preventing | +| | reallocations. | ++-------------------------------------------+-----------------------------------+ +| ``capacity()`` | For containers that support it | +| | (``std::vector``, ``QList``), | +| | return the number of elements | +| | that can be stored without | +| | reallocation. | ++-------------------------------------------+-----------------------------------+ +| ``data()`` | For containers that support it | +| | (``std::vector``, ``QList``), | +| | return a buffer viewing the | +| | memory. | ++-------------------------------------------+-----------------------------------+ +| ``constData()`` | For containers that support it | +| | (``std::vector``, ``QList``), | +| | return a read-only buffer viewing | +| | the memory. | ++-------------------------------------------+-----------------------------------+ + + +.. note:: ``std::span``, being a non-owning container, is currently replaced by a + ``std::vector`` for argument passing. This means that an opaque container + wrapping a ``std::span`` obtained from a function will be converted + to a ``std::vector`` by sequence conversion when passed to a function + taking a ``std::span``. + Opaque containers wrapping a ``std::vector`` can be passed without conversion. + This is currently experimental and subject to change. Following is an example on creating an opaque container named ``IntVector`` from `std::vector<int>`, and using it in Python. @@ -76,7 +86,7 @@ from `std::vector<int>`, and using it in Python. We will consider three separate use cases. **Case 1** - When a Python list is passed to C++ function -`TestOpaqueContainer.getVectorSum(const std::vector<int>&)` as an opaque container +``TestOpaqueContainer.getVectorSum(const std::vector<int>&)`` as an opaque container .. code-block:: c @@ -89,7 +99,7 @@ We will consider three separate use cases. } }; -**Case 2** - When we have a C++ class named `TestOpaqueContainer` with a `std::vector<int>` +**Case 2** - When we have a C++ class named ``TestOpaqueContainer`` with a ``std::vector<int>`` public variable .. code-block:: c @@ -101,7 +111,7 @@ public variable }; -**Case 3** - When we have a C++ class named `TestOpaqueContainer` with a `std::vector<int>` as +**Case 3** - When we have a C++ class named ``TestOpaqueContainer`` with a ``std::vector<int>`` as private variable and the variable is returned by a reference through a getter. .. code-block:: c @@ -123,9 +133,9 @@ private variable and the variable is returned by a reference through a getter. of these examples are rather to show the different possibilities with opaque containers in Shiboken than the class design. -In all the three cases, we want to use `intVector` in Python through an opaque-container. The -first thing to do is to create the corresponding `<container-type />` attribute in the typesystem -file, making Shiboken aware of the `IntVector`. +In all the three cases, we want to use ``intVector`` in Python through an opaque-container. The +first thing to do is to create the corresponding ``<container-type />`` attribute in the typesystem +file, making Shiboken aware of the ``IntVector``. .. code-block:: xml @@ -147,17 +157,17 @@ For the rest of the steps, we consider the three cases separately. **Case 1** - When a Python list is passed to a C++ function -As the next step, we create a typesystem entry for the class `TestOpaqueContainer`. +As the next step, we create a typesystem entry for the class ``TestOpaqueContainer``. .. code-block:: xml <value-type name="TestOpaqueContainer" /> In this case, the typesystem entry is simple and the function -`getVectorSum(const std::vector<int>&)` accepts `IntVector` as the parameter. This is -because inherantly `IntVector` is the same as `std::vector<int>`. +``getVectorSum(const std::vector<int>&)`` accepts ``IntVector`` as the parameter. This is +because inherantly ``IntVector`` is the same as ``std::vector<int>``. -Now, build the code to create the \*_wrapper.cpp and \*.so files which we import into Python. +Now, build the code to create the ``*_wrapper.cpp`` and ``*.so`` files which we import into Python. Verifying the usage in Python @@ -173,7 +183,7 @@ Verifying the usage in Python **Case 2** - When the variable is public -We create a typesystem entry for the class `TestOpaqueContainer`. +We create a typesystem entry for the class ``TestOpaqueContainer``. .. code-block:: xml @@ -181,11 +191,11 @@ We create a typesystem entry for the class `TestOpaqueContainer`. <modify-field name="intVector" opaque-container="yes"/> </value-type> -In the `<modify-field />` notice the `opaque-container="yes"`. Since the type -of `intVector' is `std::vector<int>`, it picks up the ``IntVector`` opaque +In the ``<modify-field />`` notice the ``opaque-container="yes"``. Since the type +of ``intVector`` is ``std::vector<int>``, it picks up the ``IntVector`` opaque container. -Build the code to create the \*_wrapper.cpp and \*.so files which we import into Python. +Build the code to create the ``*_wrapper.cpp`` and ``*.so`` files which we import into Python. Verifying the usage in Python @@ -206,7 +216,7 @@ Verifying the usage in Python **Case 3** - When the variable is private and returned by reference through a getter -Similar to the previous cases, we create a typesystem entry for the class `TestOpaqueContainer`. +Similar to the previous cases, we create a typesystem entry for the class ``TestOpaqueContainer``. .. code-block:: xml @@ -218,7 +228,7 @@ Similar to the previous cases, we create a typesystem entry for the class `TestO </modify-function> </value-type> -In this case, we specify the name of the opaque container `IntVector` in the <replace-type /> +In this case, we specify the name of the opaque container ``IntVector`` in the ``<replace-type />`` field. Build the code to create the \*_wrapper.cpp and \*.so files which we import into Python. |