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::string_view``, | STL C++17 string views | :file:`pybind11/pybind11.h` | 120| ``std::u16string_view``, etc. | | | 121+------------------------------------+---------------------------+-------------------------------+ 122| ``std::pair<T1, T2>`` | Pair of two custom types | :file:`pybind11/pybind11.h` | 123+------------------------------------+---------------------------+-------------------------------+ 124| ``std::tuple<...>`` | Arbitrary tuple of types | :file:`pybind11/pybind11.h` | 125+------------------------------------+---------------------------+-------------------------------+ 126| ``std::reference_wrapper<...>`` | Reference type wrapper | :file:`pybind11/pybind11.h` | 127+------------------------------------+---------------------------+-------------------------------+ 128| ``std::complex<T>`` | Complex numbers | :file:`pybind11/complex.h` | 129+------------------------------------+---------------------------+-------------------------------+ 130| ``std::array<T, Size>`` | STL static array | :file:`pybind11/stl.h` | 131+------------------------------------+---------------------------+-------------------------------+ 132| ``std::vector<T>`` | STL dynamic array | :file:`pybind11/stl.h` | 133+------------------------------------+---------------------------+-------------------------------+ 134| ``std::deque<T>`` | STL double-ended queue | :file:`pybind11/stl.h` | 135+------------------------------------+---------------------------+-------------------------------+ 136| ``std::valarray<T>`` | STL value array | :file:`pybind11/stl.h` | 137+------------------------------------+---------------------------+-------------------------------+ 138| ``std::list<T>`` | STL linked list | :file:`pybind11/stl.h` | 139+------------------------------------+---------------------------+-------------------------------+ 140| ``std::map<T1, T2>`` | STL ordered map | :file:`pybind11/stl.h` | 141+------------------------------------+---------------------------+-------------------------------+ 142| ``std::unordered_map<T1, T2>`` | STL unordered map | :file:`pybind11/stl.h` | 143+------------------------------------+---------------------------+-------------------------------+ 144| ``std::set<T>`` | STL ordered set | :file:`pybind11/stl.h` | 145+------------------------------------+---------------------------+-------------------------------+ 146| ``std::unordered_set<T>`` | STL unordered set | :file:`pybind11/stl.h` | 147+------------------------------------+---------------------------+-------------------------------+ 148| ``std::optional<T>`` | STL optional type (C++17) | :file:`pybind11/stl.h` | 149+------------------------------------+---------------------------+-------------------------------+ 150| ``std::experimental::optional<T>`` | STL optional type (exp.) | :file:`pybind11/stl.h` | 151+------------------------------------+---------------------------+-------------------------------+ 152| ``std::variant<...>`` | Type-safe union (C++17) | :file:`pybind11/stl.h` | 153+------------------------------------+---------------------------+-------------------------------+ 154| ``std::function<...>`` | STL polymorphic function | :file:`pybind11/functional.h` | 155+------------------------------------+---------------------------+-------------------------------+ 156| ``std::chrono::duration<...>`` | STL time duration | :file:`pybind11/chrono.h` | 157+------------------------------------+---------------------------+-------------------------------+ 158| ``std::chrono::time_point<...>`` | STL date/time | :file:`pybind11/chrono.h` | 159+------------------------------------+---------------------------+-------------------------------+ 160| ``Eigen::Matrix<...>`` | Eigen: dense matrix | :file:`pybind11/eigen.h` | 161+------------------------------------+---------------------------+-------------------------------+ 162| ``Eigen::Map<...>`` | Eigen: mapped memory | :file:`pybind11/eigen.h` | 163+------------------------------------+---------------------------+-------------------------------+ 164| ``Eigen::SparseMatrix<...>`` | Eigen: sparse matrix | :file:`pybind11/eigen.h` | 165+------------------------------------+---------------------------+-------------------------------+ 166