Warning, /jana2/src/python/externals/pybind11-2.10.3/docs/advanced/cast/overview.rst is written in an unsupported language. File is not indexed.
0001 Overview
0002 ########
0003
0004 .. rubric:: 1. Native type in C++, wrapper in Python
0005
0006 Exposing a custom C++ type using :class:`py::class_` was covered in detail
0007 in the :doc:`/classes` section. There, the underlying data structure is
0008 always the original C++ class while the :class:`py::class_` wrapper provides
0009 a Python interface. Internally, when an object like this is sent from C++ to
0010 Python, pybind11 will just add the outer wrapper layer over the native C++
0011 object. Getting it back from Python is just a matter of peeling off the
0012 wrapper.
0013
0014 .. rubric:: 2. Wrapper in C++, native type in Python
0015
0016 This is the exact opposite situation. Now, we have a type which is native to
0017 Python, like a ``tuple`` or a ``list``. One way to get this data into C++ is
0018 with the :class:`py::object` family of wrappers. These are explained in more
0019 detail in the :doc:`/advanced/pycpp/object` section. We'll just give a quick
0020 example here:
0021
0022 .. code-block:: cpp
0023
0024 void print_list(py::list my_list) {
0025 for (auto item : my_list)
0026 std::cout << item << " ";
0027 }
0028
0029 .. code-block:: pycon
0030
0031 >>> print_list([1, 2, 3])
0032 1 2 3
0033
0034 The Python ``list`` is not converted in any way -- it's just wrapped in a C++
0035 :class:`py::list` class. At its core it's still a Python object. Copying a
0036 :class:`py::list` will do the usual reference-counting like in Python.
0037 Returning the object to Python will just remove the thin wrapper.
0038
0039 .. rubric:: 3. Converting between native C++ and Python types
0040
0041 In the previous two cases we had a native type in one language and a wrapper in
0042 the other. Now, we have native types on both sides and we convert between them.
0043
0044 .. code-block:: cpp
0045
0046 void print_vector(const std::vector<int> &v) {
0047 for (auto item : v)
0048 std::cout << item << "\n";
0049 }
0050
0051 .. code-block:: pycon
0052
0053 >>> print_vector([1, 2, 3])
0054 1 2 3
0055
0056 In this case, pybind11 will construct a new ``std::vector<int>`` and copy each
0057 element from the Python ``list``. The newly constructed object will be passed
0058 to ``print_vector``. The same thing happens in the other direction: a new
0059 ``list`` is made to match the value returned from C++.
0060
0061 Lots of these conversions are supported out of the box, as shown in the table
0062 below. They are very convenient, but keep in mind that these conversions are
0063 fundamentally based on copying data. This is perfectly fine for small immutable
0064 types but it may become quite expensive for large data structures. This can be
0065 avoided by overriding the automatic conversion with a custom wrapper (i.e. the
0066 above-mentioned approach 1). This requires some manual effort and more details
0067 are available in the :ref:`opaque` section.
0068
0069 .. _conversion_table:
0070
0071 List of all builtin conversions
0072 -------------------------------
0073
0074 The following basic data types are supported out of the box (some may require
0075 an additional extension header to be included). To pass other data structures
0076 as arguments and return values, refer to the section on binding :ref:`classes`.
0077
0078 +------------------------------------+---------------------------+-----------------------------------+
0079 | Data type | Description | Header file |
0080 +====================================+===========================+===================================+
0081 | ``int8_t``, ``uint8_t`` | 8-bit integers | :file:`pybind11/pybind11.h` |
0082 +------------------------------------+---------------------------+-----------------------------------+
0083 | ``int16_t``, ``uint16_t`` | 16-bit integers | :file:`pybind11/pybind11.h` |
0084 +------------------------------------+---------------------------+-----------------------------------+
0085 | ``int32_t``, ``uint32_t`` | 32-bit integers | :file:`pybind11/pybind11.h` |
0086 +------------------------------------+---------------------------+-----------------------------------+
0087 | ``int64_t``, ``uint64_t`` | 64-bit integers | :file:`pybind11/pybind11.h` |
0088 +------------------------------------+---------------------------+-----------------------------------+
0089 | ``ssize_t``, ``size_t`` | Platform-dependent size | :file:`pybind11/pybind11.h` |
0090 +------------------------------------+---------------------------+-----------------------------------+
0091 | ``float``, ``double`` | Floating point types | :file:`pybind11/pybind11.h` |
0092 +------------------------------------+---------------------------+-----------------------------------+
0093 | ``bool`` | Two-state Boolean type | :file:`pybind11/pybind11.h` |
0094 +------------------------------------+---------------------------+-----------------------------------+
0095 | ``char`` | Character literal | :file:`pybind11/pybind11.h` |
0096 +------------------------------------+---------------------------+-----------------------------------+
0097 | ``char16_t`` | UTF-16 character literal | :file:`pybind11/pybind11.h` |
0098 +------------------------------------+---------------------------+-----------------------------------+
0099 | ``char32_t`` | UTF-32 character literal | :file:`pybind11/pybind11.h` |
0100 +------------------------------------+---------------------------+-----------------------------------+
0101 | ``wchar_t`` | Wide character literal | :file:`pybind11/pybind11.h` |
0102 +------------------------------------+---------------------------+-----------------------------------+
0103 | ``const char *`` | UTF-8 string literal | :file:`pybind11/pybind11.h` |
0104 +------------------------------------+---------------------------+-----------------------------------+
0105 | ``const char16_t *`` | UTF-16 string literal | :file:`pybind11/pybind11.h` |
0106 +------------------------------------+---------------------------+-----------------------------------+
0107 | ``const char32_t *`` | UTF-32 string literal | :file:`pybind11/pybind11.h` |
0108 +------------------------------------+---------------------------+-----------------------------------+
0109 | ``const wchar_t *`` | Wide string literal | :file:`pybind11/pybind11.h` |
0110 +------------------------------------+---------------------------+-----------------------------------+
0111 | ``std::string`` | STL dynamic UTF-8 string | :file:`pybind11/pybind11.h` |
0112 +------------------------------------+---------------------------+-----------------------------------+
0113 | ``std::u16string`` | STL dynamic UTF-16 string | :file:`pybind11/pybind11.h` |
0114 +------------------------------------+---------------------------+-----------------------------------+
0115 | ``std::u32string`` | STL dynamic UTF-32 string | :file:`pybind11/pybind11.h` |
0116 +------------------------------------+---------------------------+-----------------------------------+
0117 | ``std::wstring`` | STL dynamic wide string | :file:`pybind11/pybind11.h` |
0118 +------------------------------------+---------------------------+-----------------------------------+
0119 | ``std::string_view``, | STL C++17 string views | :file:`pybind11/pybind11.h` |
0120 | ``std::u16string_view``, etc. | | |
0121 +------------------------------------+---------------------------+-----------------------------------+
0122 | ``std::pair<T1, T2>`` | Pair of two custom types | :file:`pybind11/pybind11.h` |
0123 +------------------------------------+---------------------------+-----------------------------------+
0124 | ``std::tuple<...>`` | Arbitrary tuple of types | :file:`pybind11/pybind11.h` |
0125 +------------------------------------+---------------------------+-----------------------------------+
0126 | ``std::reference_wrapper<...>`` | Reference type wrapper | :file:`pybind11/pybind11.h` |
0127 +------------------------------------+---------------------------+-----------------------------------+
0128 | ``std::complex<T>`` | Complex numbers | :file:`pybind11/complex.h` |
0129 +------------------------------------+---------------------------+-----------------------------------+
0130 | ``std::array<T, Size>`` | STL static array | :file:`pybind11/stl.h` |
0131 +------------------------------------+---------------------------+-----------------------------------+
0132 | ``std::vector<T>`` | STL dynamic array | :file:`pybind11/stl.h` |
0133 +------------------------------------+---------------------------+-----------------------------------+
0134 | ``std::deque<T>`` | STL double-ended queue | :file:`pybind11/stl.h` |
0135 +------------------------------------+---------------------------+-----------------------------------+
0136 | ``std::valarray<T>`` | STL value array | :file:`pybind11/stl.h` |
0137 +------------------------------------+---------------------------+-----------------------------------+
0138 | ``std::list<T>`` | STL linked list | :file:`pybind11/stl.h` |
0139 +------------------------------------+---------------------------+-----------------------------------+
0140 | ``std::map<T1, T2>`` | STL ordered map | :file:`pybind11/stl.h` |
0141 +------------------------------------+---------------------------+-----------------------------------+
0142 | ``std::unordered_map<T1, T2>`` | STL unordered map | :file:`pybind11/stl.h` |
0143 +------------------------------------+---------------------------+-----------------------------------+
0144 | ``std::set<T>`` | STL ordered set | :file:`pybind11/stl.h` |
0145 +------------------------------------+---------------------------+-----------------------------------+
0146 | ``std::unordered_set<T>`` | STL unordered set | :file:`pybind11/stl.h` |
0147 +------------------------------------+---------------------------+-----------------------------------+
0148 | ``std::optional<T>`` | STL optional type (C++17) | :file:`pybind11/stl.h` |
0149 +------------------------------------+---------------------------+-----------------------------------+
0150 | ``std::experimental::optional<T>`` | STL optional type (exp.) | :file:`pybind11/stl.h` |
0151 +------------------------------------+---------------------------+-----------------------------------+
0152 | ``std::variant<...>`` | Type-safe union (C++17) | :file:`pybind11/stl.h` |
0153 +------------------------------------+---------------------------+-----------------------------------+
0154 | ``std::filesystem::path<T>`` | STL path (C++17) [#]_ | :file:`pybind11/stl/filesystem.h` |
0155 +------------------------------------+---------------------------+-----------------------------------+
0156 | ``std::function<...>`` | STL polymorphic function | :file:`pybind11/functional.h` |
0157 +------------------------------------+---------------------------+-----------------------------------+
0158 | ``std::chrono::duration<...>`` | STL time duration | :file:`pybind11/chrono.h` |
0159 +------------------------------------+---------------------------+-----------------------------------+
0160 | ``std::chrono::time_point<...>`` | STL date/time | :file:`pybind11/chrono.h` |
0161 +------------------------------------+---------------------------+-----------------------------------+
0162 | ``Eigen::Matrix<...>`` | Eigen: dense matrix | :file:`pybind11/eigen.h` |
0163 +------------------------------------+---------------------------+-----------------------------------+
0164 | ``Eigen::Map<...>`` | Eigen: mapped memory | :file:`pybind11/eigen.h` |
0165 +------------------------------------+---------------------------+-----------------------------------+
0166 | ``Eigen::SparseMatrix<...>`` | Eigen: sparse matrix | :file:`pybind11/eigen.h` |
0167 +------------------------------------+---------------------------+-----------------------------------+
0168
0169 .. [#] ``std::filesystem::path`` is converted to ``pathlib.Path`` and
0170 ``os.PathLike`` is converted to ``std::filesystem::path``.
