github.com/kaydxh/golang@v0.0.131/pkg/gocv/cgo/third_path/pybind11/docs/advanced/cast/overview.rst (about)

     1  Overview
     2  ########
     3  
     4  .. rubric:: 1. Native type in C++, wrapper in Python
     5  
     6  Exposing a custom C++ type using :class:`py::class_` was covered in detail
     7  in the :doc:`/classes` section. There, the underlying data structure is
     8  always the original C++ class while the :class:`py::class_` wrapper provides
     9  a Python interface. Internally, when an object like this is sent from C++ to
    10  Python, pybind11 will just add the outer wrapper layer over the native C++
    11  object. Getting it back from Python is just a matter of peeling off the
    12  wrapper.
    13  
    14  .. rubric:: 2. Wrapper in C++, native type in Python
    15  
    16  This is the exact opposite situation. Now, we have a type which is native to
    17  Python, like a ``tuple`` or a ``list``. One way to get this data into C++ is
    18  with the :class:`py::object` family of wrappers. These are explained in more
    19  detail in the :doc:`/advanced/pycpp/object` section. We'll just give a quick
    20  example 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  
    34  The 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.
    37  Returning the object to Python will just remove the thin wrapper.
    38  
    39  .. rubric:: 3. Converting between native C++ and Python types
    40  
    41  In the previous two cases we had a native type in one language and a wrapper in
    42  the 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  
    56  In this case, pybind11 will construct a new ``std::vector<int>`` and copy each
    57  element from the Python ``list``. The newly constructed object will be passed
    58  to ``print_vector``. The same thing happens in the other direction: a new
    59  ``list`` is made to match the value returned from C++.
    60  
    61  Lots of these conversions are supported out of the box, as shown in the table
    62  below. They are very convenient, but keep in mind that these conversions are
    63  fundamentally based on copying data. This is perfectly fine for small immutable
    64  types but it may become quite expensive for large data structures. This can be
    65  avoided by overriding the automatic conversion with a custom wrapper (i.e. the
    66  above-mentioned approach 1). This requires some manual effort and more details
    67  are available in the :ref:`opaque` section.
    68  
    69  .. _conversion_table:
    70  
    71  List of all builtin conversions
    72  -------------------------------
    73  
    74  The following basic data types are supported out of the box (some may require
    75  an additional extension header to be included). To pass other data structures
    76  as 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::filesystem::path<T>``       | STL path (C++17) [#]_     | :file:`pybind11/stl/filesystem.h` |
   155  +------------------------------------+---------------------------+-----------------------------------+
   156  | ``std::function<...>``             | STL polymorphic function  | :file:`pybind11/functional.h`     |
   157  +------------------------------------+---------------------------+-----------------------------------+
   158  | ``std::chrono::duration<...>``     | STL time duration         | :file:`pybind11/chrono.h`         |
   159  +------------------------------------+---------------------------+-----------------------------------+
   160  | ``std::chrono::time_point<...>``   | STL date/time             | :file:`pybind11/chrono.h`         |
   161  +------------------------------------+---------------------------+-----------------------------------+
   162  | ``Eigen::Matrix<...>``             | Eigen: dense matrix       | :file:`pybind11/eigen.h`          |
   163  +------------------------------------+---------------------------+-----------------------------------+
   164  | ``Eigen::Map<...>``                | Eigen: mapped memory      | :file:`pybind11/eigen.h`          |
   165  +------------------------------------+---------------------------+-----------------------------------+
   166  | ``Eigen::SparseMatrix<...>``       | Eigen: sparse matrix      | :file:`pybind11/eigen.h`          |
   167  +------------------------------------+---------------------------+-----------------------------------+
   168  
   169  .. [#] ``std::filesystem::path`` is converted to ``pathlib.Path`` and
   170     ``os.PathLike`` is converted to ``std::filesystem::path``.