overview.rst revision 12037:d28054ac6ec9 
1Overview
2########
3
4.. rubric:: 1. Native type in C++, wrapper in Python
5
6Exposing a custom C++ type using :class:`py::class_` was covered in detail
7in the :doc:`/classes` section. There, the underlying data structure is
8always the original C++ class while the :class:`py::class_` wrapper provides
9a Python interface. Internally, when an object like this is sent from C++ to
10Python, pybind11 will just add the outer wrapper layer over the native C++
11object. Getting it back from Python is just a matter of peeling off the
12wrapper.
13
14.. rubric:: 2. Wrapper in C++, native type in Python
15
16This is the exact opposite situation. Now, we have a type which is native to
17Python, like a ``tuple`` or a ``list``. One way to get this data into C++ is
18with the :class:`py::object` family of wrappers. These are explained in more
19detail in the :doc:`/advanced/pycpp/object` section. We'll just give a quick
20example here:
21
22.. code-block:: cpp
23
24    void print_list(py::list my_list) {
25        for (auto item : my_list)
26            std::cout << item << " ";
27    }
28
29.. code-block:: pycon
30
31    >>> print_list([1, 2, 3])
32    1 2 3
33
34The Python ``list`` is not converted in any way -- it's just wrapped in a C++
35:class:`py::list` class. At its core it's still a Python object. Copying a
36:class:`py::list` will do the usual reference-counting like in Python.
37Returning the object to Python will just remove the thin wrapper.
38
39.. rubric:: 3. Converting between native C++ and Python types
40
41In the previous two cases we had a native type in one language and a wrapper in
42the other. Now, we have native types on both sides and we convert between them.
43
44.. code-block:: cpp
45
46    void print_vector(const std::vector<int> &v) {
47        for (auto item : v)
48            std::cout << item << "\n";
49    }
50
51.. code-block:: pycon
52
53    >>> print_vector([1, 2, 3])
54    1 2 3
55
56In this case, pybind11 will construct a new ``std::vector<int>`` and copy each
57element from the Python ``list``. The newly constructed object will be passed
58to ``print_vector``. The same thing happens in the other direction: a new
59``list`` is made to match the value returned from C++.
60
61Lots of these conversions are supported out of the box, as shown in the table
62below. They are very convenient, but keep in mind that these conversions are
63fundamentally based on copying data. This is perfectly fine for small immutable
64types but it may become quite expensive for large data structures. This can be
65avoided by overriding the automatic conversion with a custom wrapper (i.e. the
66above-mentioned approach 1). This requires some manual effort and more details
67are available in the :ref:`opaque` section.
68
69.. _conversion_table:
70
71List of all builtin conversions
72-------------------------------
73
74The following basic data types are supported out of the box (some may require
75an additional extension header to be included). To pass other data structures
76as arguments and return values, refer to the section on binding :ref:`classes`.
77
78+------------------------------------+---------------------------+-------------------------------+
79|  Data type                         |  Description              | Header file                   |
80+====================================+===========================+===============================+
81| ``int8_t``, ``uint8_t``            | 8-bit integers            | :file:`pybind11/pybind11.h`   |
82+------------------------------------+---------------------------+-------------------------------+
83| ``int16_t``, ``uint16_t``          | 16-bit integers           | :file:`pybind11/pybind11.h`   |
84+------------------------------------+---------------------------+-------------------------------+
85| ``int32_t``, ``uint32_t``          | 32-bit integers           | :file:`pybind11/pybind11.h`   |
86+------------------------------------+---------------------------+-------------------------------+
87| ``int64_t``, ``uint64_t``          | 64-bit integers           | :file:`pybind11/pybind11.h`   |
88+------------------------------------+---------------------------+-------------------------------+
89| ``ssize_t``, ``size_t``            | Platform-dependent size   | :file:`pybind11/pybind11.h`   |
90+------------------------------------+---------------------------+-------------------------------+
91| ``float``, ``double``              | Floating point types      | :file:`pybind11/pybind11.h`   |
92+------------------------------------+---------------------------+-------------------------------+
93| ``bool``                           | Two-state Boolean type    | :file:`pybind11/pybind11.h`   |
94+------------------------------------+---------------------------+-------------------------------+
95| ``char``                           | Character literal         | :file:`pybind11/pybind11.h`   |
96+------------------------------------+---------------------------+-------------------------------+
97| ``char16_t``                       | UTF-16 character literal  | :file:`pybind11/pybind11.h`   |
98+------------------------------------+---------------------------+-------------------------------+
99| ``char32_t``                       | UTF-32 character literal  | :file:`pybind11/pybind11.h`   |
100+------------------------------------+---------------------------+-------------------------------+
101| ``wchar_t``                        | Wide character literal    | :file:`pybind11/pybind11.h`   |
102+------------------------------------+---------------------------+-------------------------------+
103| ``const char *``                   | UTF-8 string literal      | :file:`pybind11/pybind11.h`   |
104+------------------------------------+---------------------------+-------------------------------+
105| ``const char16_t *``               | UTF-16 string literal     | :file:`pybind11/pybind11.h`   |
106+------------------------------------+---------------------------+-------------------------------+
107| ``const char32_t *``               | UTF-32 string literal     | :file:`pybind11/pybind11.h`   |
108+------------------------------------+---------------------------+-------------------------------+
109| ``const wchar_t *``                | Wide string literal       | :file:`pybind11/pybind11.h`   |
110+------------------------------------+---------------------------+-------------------------------+
111| ``std::string``                    | STL dynamic UTF-8 string  | :file:`pybind11/pybind11.h`   |
112+------------------------------------+---------------------------+-------------------------------+
113| ``std::u16string``                 | STL dynamic UTF-16 string | :file:`pybind11/pybind11.h`   |
114+------------------------------------+---------------------------+-------------------------------+
115| ``std::u32string``                 | STL dynamic UTF-32 string | :file:`pybind11/pybind11.h`   |
116+------------------------------------+---------------------------+-------------------------------+
117| ``std::wstring``                   | STL dynamic wide string   | :file:`pybind11/pybind11.h`   |
118+------------------------------------+---------------------------+-------------------------------+
119| ``std::pair<T1, T2>``              | Pair of two custom types  | :file:`pybind11/pybind11.h`   |
120+------------------------------------+---------------------------+-------------------------------+
121| ``std::tuple<...>``                | Arbitrary tuple of types  | :file:`pybind11/pybind11.h`   |
122+------------------------------------+---------------------------+-------------------------------+
123| ``std::reference_wrapper<...>``    | Reference type wrapper    | :file:`pybind11/pybind11.h`   |
124+------------------------------------+---------------------------+-------------------------------+
125| ``std::complex<T>``                | Complex numbers           | :file:`pybind11/complex.h`    |
126+------------------------------------+---------------------------+-------------------------------+
127| ``std::array<T, Size>``            | STL static array          | :file:`pybind11/stl.h`        |
128+------------------------------------+---------------------------+-------------------------------+
129| ``std::vector<T>``                 | STL dynamic array         | :file:`pybind11/stl.h`        |
130+------------------------------------+---------------------------+-------------------------------+
131| ``std::valarray<T>``               | STL value array           | :file:`pybind11/stl.h`        |
132+------------------------------------+---------------------------+-------------------------------+
133| ``std::list<T>``                   | STL linked list           | :file:`pybind11/stl.h`        |
134+------------------------------------+---------------------------+-------------------------------+
135| ``std::map<T1, T2>``               | STL ordered map           | :file:`pybind11/stl.h`        |
136+------------------------------------+---------------------------+-------------------------------+
137| ``std::unordered_map<T1, T2>``     | STL unordered map         | :file:`pybind11/stl.h`        |
138+------------------------------------+---------------------------+-------------------------------+
139| ``std::set<T>``                    | STL ordered set           | :file:`pybind11/stl.h`        |
140+------------------------------------+---------------------------+-------------------------------+
141| ``std::unordered_set<T>``          | STL unordered set         | :file:`pybind11/stl.h`        |
142+------------------------------------+---------------------------+-------------------------------+
143| ``std::optional<T>``               | STL optional type (C++17) | :file:`pybind11/stl.h`        |
144+------------------------------------+---------------------------+-------------------------------+
145| ``std::experimental::optional<T>`` | STL optional type (exp.)  | :file:`pybind11/stl.h`        |
146+------------------------------------+---------------------------+-------------------------------+
147| ``std::function<...>``             | STL polymorphic function  | :file:`pybind11/functional.h` |
148+------------------------------------+---------------------------+-------------------------------+
149| ``std::chrono::duration<...>``     | STL time duration         | :file:`pybind11/chrono.h`     |
150+------------------------------------+---------------------------+-------------------------------+
151| ``std::chrono::time_point<...>``   | STL date/time             | :file:`pybind11/chrono.h`     |
152+------------------------------------+---------------------------+-------------------------------+
153| ``Eigen::Matrix<...>``             | Eigen: dense matrix       | :file:`pybind11/eigen.h`      |
154+------------------------------------+---------------------------+-------------------------------+
155| ``Eigen::Map<...>``                | Eigen: mapped memory      | :file:`pybind11/eigen.h`      |
156+------------------------------------+---------------------------+-------------------------------+
157| ``Eigen::SparseMatrix<...>``       | Eigen: sparse matrix      | :file:`pybind11/eigen.h`      |
158+------------------------------------+---------------------------+-------------------------------+
159