index.rst revision 11986:c12e4625ab56 
1Type conversions
2################
3
4Apart from enabling cross-language function calls, a fundamental problem
5that a binding tool like pybind11 must address is to provide access to
6native Python types in C++ and vice versa. There are three fundamentally
7different ways to do this—which approach is preferable for a particular type
8depends on the situation at hand.
9
101. Use a native C++ type everywhere. In this case, the type must be wrapped
11   using pybind11-generated bindings so that Python can interact with it.
12
132. Use a native Python type everywhere. It will need to be wrapped so that
14   C++ functions can interact with it.
15
163. Use a native C++ type on the C++ side and a native Python type on the
17   Python side. pybind11 refers to this as a *type conversion*.
18
19   Type conversions are the most "natural" option in the sense that native
20   (non-wrapped) types are used everywhere. The main downside is that a copy
21   of the data must be made on every Python ↔ C++ transition: this is
22   needed since the C++ and Python versions of the same type generally won't
23   have the same memory layout.
24
25   pybind11 can perform many kinds of conversions automatically. An overview
26   is provided in the table ":ref:`conversion_table`".
27
28The following subsections discuss the differences between these options in more
29detail. The main focus in this section is on type conversions, which represent
30the last case of the above list.
31
32.. toctree::
33   :maxdepth: 1
34
35   overview
36   stl
37   functional
38   chrono
39   eigen
40   custom
41
42