overview.rst revision 11986:c12e4625ab56
111663Stushar@ece.gatech.eduOverview 211663Stushar@ece.gatech.edu######## 311663Stushar@ece.gatech.edu 411663Stushar@ece.gatech.edu.. rubric:: 1. Native type in C++, wrapper in Python 511663Stushar@ece.gatech.edu 611663Stushar@ece.gatech.eduExposing a custom C++ type using :class:`py::class_` was covered in detail 711663Stushar@ece.gatech.eduin the :doc:`/classes` section. There, the underlying data structure is 811663Stushar@ece.gatech.edualways the original C++ class while the :class:`py::class_` wrapper provides 911663Stushar@ece.gatech.edua Python interface. Internally, when an object like this is sent from C++ to 1011663Stushar@ece.gatech.eduPython, pybind11 will just add the outer wrapper layer over the native C++ 1111663Stushar@ece.gatech.eduobject. Getting it back from Python is just a matter of peeling off the 1211663Stushar@ece.gatech.eduwrapper. 1311663Stushar@ece.gatech.edu 1411663Stushar@ece.gatech.edu.. rubric:: 2. Wrapper in C++, native type in Python 1511663Stushar@ece.gatech.edu 1611663Stushar@ece.gatech.eduThis is the exact opposite situation. Now, we have a type which is native to 1711663Stushar@ece.gatech.eduPython, like a ``tuple`` or a ``list``. One way to get this data into C++ is 1811663Stushar@ece.gatech.eduwith the :class:`py::object` family of wrappers. These are explained in more 1911663Stushar@ece.gatech.edudetail in the :doc:`/advanced/pycpp/object` section. We'll just give a quick 2011663Stushar@ece.gatech.eduexample here: 2111663Stushar@ece.gatech.edu 2211663Stushar@ece.gatech.edu.. code-block:: cpp 2311663Stushar@ece.gatech.edu 2411663Stushar@ece.gatech.edu void print_list(py::list my_list) { 2511663Stushar@ece.gatech.edu for (auto item : my_list) 2611663Stushar@ece.gatech.edu std::cout << item << " "; 2711663Stushar@ece.gatech.edu } 2811663Stushar@ece.gatech.edu 2911663Stushar@ece.gatech.edu.. code-block:: pycon 3013774Sandreas.sandberg@arm.com 3113774Sandreas.sandberg@arm.com >>> print_list([1, 2, 3]) 3211663Stushar@ece.gatech.edu 1 2 3 3311663Stushar@ece.gatech.edu 3411663Stushar@ece.gatech.eduThe Python ``list`` is not converted in any way -- it's just wrapped in a C++ 3511663Stushar@ece.gatech.edu:class:`py::list` class. At its core it's still a Python object. Copying a 3613774Sandreas.sandberg@arm.com:class:`py::list` will do the usual reference-counting like in Python. 3711663Stushar@ece.gatech.eduReturning the object to Python will just remove the thin wrapper. 3811663Stushar@ece.gatech.edu 3911663Stushar@ece.gatech.edu.. rubric:: 3. Converting between native C++ and Python types 4011663Stushar@ece.gatech.edu 4111663Stushar@ece.gatech.eduIn the previous two cases we had a native type in one language and a wrapper in 4211663Stushar@ece.gatech.eduthe other. Now, we have native types on both sides and we convert between them. 4311663Stushar@ece.gatech.edu 4411663Stushar@ece.gatech.edu.. code-block:: cpp 4511663Stushar@ece.gatech.edu 4611663Stushar@ece.gatech.edu void print_vector(const std::vector<int> &v) { 4711663Stushar@ece.gatech.edu for (auto item : v) 4811663Stushar@ece.gatech.edu std::cout << item << "\n"; 4911663Stushar@ece.gatech.edu } 5011663Stushar@ece.gatech.edu 5111663Stushar@ece.gatech.edu.. code-block:: pycon 5211663Stushar@ece.gatech.edu 5311663Stushar@ece.gatech.edu >>> print_vector([1, 2, 3]) 5411663Stushar@ece.gatech.edu 1 2 3 5511663Stushar@ece.gatech.edu 5611663Stushar@ece.gatech.eduIn this case, pybind11 will construct a new ``std::vector<int>`` and copy each 5711663Stushar@ece.gatech.eduelement from the Python ``list``. The newly constructed object will be passed 5811663Stushar@ece.gatech.eduto ``print_vector``. The same thing happens in the other direction: a new 5911663Stushar@ece.gatech.edu``list`` is made to match the value returned from C++. 6011663Stushar@ece.gatech.edu 6111663Stushar@ece.gatech.eduLots of these conversions are supported out of the box, as shown in the table 6211663Stushar@ece.gatech.edubelow. They are very convenient, but keep in mind that these conversions are 6311666Stushar@ece.gatech.edufundamentally based on copying data. This is perfectly fine for small immutable 6411666Stushar@ece.gatech.edutypes but it may become quite expensive for large data structures. This can be 6511666Stushar@ece.gatech.eduavoided by overriding the automatic conversion with a custom wrapper (i.e. the 6611666Stushar@ece.gatech.eduabove-mentioned approach 1). This requires some manual effort and more details 6711666Stushar@ece.gatech.eduare available in the :ref:`opaque` section. 6811663Stushar@ece.gatech.edu 6911663Stushar@ece.gatech.edu.. _conversion_table: 7011663Stushar@ece.gatech.edu 7111666Stushar@ece.gatech.eduList of all builtin conversions 7211663Stushar@ece.gatech.edu------------------------------- 7311663Stushar@ece.gatech.edu 7411663Stushar@ece.gatech.eduThe following basic data types are supported out of the box (some may require 7511663Stushar@ece.gatech.eduan additional extension header to be included). To pass other data structures 7611666Stushar@ece.gatech.eduas arguments and return values, refer to the section on binding :ref:`classes`. 7711666Stushar@ece.gatech.edu 7811663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 7911663Stushar@ece.gatech.edu| Data type | Description | Header file | 8011663Stushar@ece.gatech.edu+====================================+===========================+===============================+ 8111663Stushar@ece.gatech.edu| ``int8_t``, ``uint8_t`` | 8-bit integers | :file:`pybind11/pybind11.h` | 8211663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 8311663Stushar@ece.gatech.edu| ``int16_t``, ``uint16_t`` | 16-bit integers | :file:`pybind11/pybind11.h` | 8411663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 8511663Stushar@ece.gatech.edu| ``int32_t``, ``uint32_t`` | 32-bit integers | :file:`pybind11/pybind11.h` | 8611663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 8713731Sandreas.sandberg@arm.com| ``int64_t``, ``uint64_t`` | 64-bit integers | :file:`pybind11/pybind11.h` | 8811663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 8911663Stushar@ece.gatech.edu| ``ssize_t``, ``size_t`` | Platform-dependent size | :file:`pybind11/pybind11.h` | 9011663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 9111663Stushar@ece.gatech.edu| ``float``, ``double`` | Floating point types | :file:`pybind11/pybind11.h` | 9211663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 9311663Stushar@ece.gatech.edu| ``bool`` | Two-state Boolean type | :file:`pybind11/pybind11.h` | 9411663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 9511663Stushar@ece.gatech.edu| ``char`` | Character literal | :file:`pybind11/pybind11.h` | 9611663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 9711663Stushar@ece.gatech.edu| ``wchar_t`` | Wide character literal | :file:`pybind11/pybind11.h` | 9811663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 9911666Stushar@ece.gatech.edu| ``const char *`` | UTF-8 string literal | :file:`pybind11/pybind11.h` | 10011666Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 10111663Stushar@ece.gatech.edu| ``const wchar_t *`` | Wide string literal | :file:`pybind11/pybind11.h` | 10211663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 10311663Stushar@ece.gatech.edu| ``std::string`` | STL dynamic UTF-8 string | :file:`pybind11/pybind11.h` | 10411663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 10511663Stushar@ece.gatech.edu| ``std::wstring`` | STL dynamic wide string | :file:`pybind11/pybind11.h` | 10611663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 10711663Stushar@ece.gatech.edu| ``std::pair<T1, T2>`` | Pair of two custom types | :file:`pybind11/pybind11.h` | 10811663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 10911666Stushar@ece.gatech.edu| ``std::tuple<...>`` | Arbitrary tuple of types | :file:`pybind11/pybind11.h` | 11011666Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 11111663Stushar@ece.gatech.edu| ``std::reference_wrapper<...>`` | Reference type wrapper | :file:`pybind11/pybind11.h` | 11211663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 11311663Stushar@ece.gatech.edu| ``std::complex<T>`` | Complex numbers | :file:`pybind11/complex.h` | 11411663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 11511663Stushar@ece.gatech.edu| ``std::array<T, Size>`` | STL static array | :file:`pybind11/stl.h` | 11611663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 11711663Stushar@ece.gatech.edu| ``std::vector<T>`` | STL dynamic array | :file:`pybind11/stl.h` | 11811663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 11913731Sandreas.sandberg@arm.com| ``std::valarray<T>`` | STL value array | :file:`pybind11/stl.h` | 12013731Sandreas.sandberg@arm.com+------------------------------------+---------------------------+-------------------------------+ 12111663Stushar@ece.gatech.edu| ``std::list<T>`` | STL linked list | :file:`pybind11/stl.h` | 12211663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 12311663Stushar@ece.gatech.edu| ``std::map<T1, T2>`` | STL ordered map | :file:`pybind11/stl.h` | 12411663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 12511663Stushar@ece.gatech.edu| ``std::unordered_map<T1, T2>`` | STL unordered map | :file:`pybind11/stl.h` | 12611663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 12711666Stushar@ece.gatech.edu| ``std::set<T>`` | STL ordered set | :file:`pybind11/stl.h` | 12811663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 12911663Stushar@ece.gatech.edu| ``std::unordered_set<T>`` | STL unordered set | :file:`pybind11/stl.h` | 13011663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 13111663Stushar@ece.gatech.edu| ``std::optional<T>`` | STL optional type (C++17) | :file:`pybind11/stl.h` | 13213731Sandreas.sandberg@arm.com+------------------------------------+---------------------------+-------------------------------+ 13313731Sandreas.sandberg@arm.com| ``std::experimental::optional<T>`` | STL optional type (exp.) | :file:`pybind11/stl.h` | 13411663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 13511663Stushar@ece.gatech.edu| ``std::function<...>`` | STL polymorphic function | :file:`pybind11/functional.h` | 13611663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 13711663Stushar@ece.gatech.edu| ``std::chrono::duration<...>`` | STL time duration | :file:`pybind11/chrono.h` | 13811663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 13911663Stushar@ece.gatech.edu| ``std::chrono::time_point<...>`` | STL date/time | :file:`pybind11/chrono.h` | 14011666Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 14111663Stushar@ece.gatech.edu| ``Eigen::Matrix<...>`` | Eigen: dense matrix | :file:`pybind11/eigen.h` | 14211663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 14311663Stushar@ece.gatech.edu| ``Eigen::Map<...>`` | Eigen: mapped memory | :file:`pybind11/eigen.h` | 14411663Stushar@ece.gatech.edu+------------------------------------+---------------------------+-------------------------------+ 14511663Stushar@ece.gatech.edu| ``Eigen::SparseMatrix<...>`` | Eigen: sparse matrix | :file:`pybind11/eigen.h` | 14613731Sandreas.sandberg@arm.com+------------------------------------+---------------------------+-------------------------------+ 14713731Sandreas.sandberg@arm.com