blob: ac22df558bf9e23f635083e30654e6b5b92aa1b2 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
|
.. _opaque-containers:
*****************
Opaque Containers
*****************
Normally, Python containers such as ``list`` or ``dict`` are passed when
calling C++ functions taking a corresponding C++ container (see
:ref:`container-type`).
This means that for each call, the entire Python container is converted to
a C++ container, which can be inefficient when for example creating plots
from lists of points.
To work around this, special opaque containers can generated which wrap an
underlying C++ container directly (currently implemented for ``list`` types).
They implement the sequence protocol and can be passed to the function
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`.
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,
(see :ref:`modify-field`), it is possible to obtain an opaque container
which avoids the conversion and allows for direct modification of elements.
Getters returning references can also be modified to return opaque containers.
This is done by modifying the return type to the name of the opaque container
(see :ref:`replace-type`).
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. |
+-------------------------------------------+-----------------------------------+
|
