Reorganize documentation
diff --git a/docs/advanced/cast/chrono.rst b/docs/advanced/cast/chrono.rst
new file mode 100644
index 0000000..1213e2c
--- /dev/null
+++ b/docs/advanced/cast/chrono.rst
@@ -0,0 +1,81 @@
+Chrono
+======
+
+When including the additional header file :file:`pybind11/chrono.h` conversions
+from C++11 chrono datatypes to python datetime objects are automatically enabled.
+This header also enables conversions of python floats (often from sources such
+as `time.monotonic()`, `time.perf_counter()` and `time.process_time()`) into
+durations.
+
+An overview of clocks in C++11
+------------------------------
+
+A point of confusion when using these conversions is the differences between
+clocks provided in C++11. There are three clock types defined by the C++11
+standard and users can define their own if needed. Each of these clocks have
+different properties and when converting to and from python will give different
+results.
+
+The first clock defined by the standard is ``std::chrono::system_clock``. This
+clock measures the current date and time. However, this clock changes with to
+updates to the operating system time. For example, if your time is synchronised
+with a time server this clock will change. This makes this clock a poor choice
+for timing purposes but good for measuring the wall time.
+
+The second clock defined in the standard is ``std::chrono::steady_clock``.
+This clock ticks at a steady rate and is never adjusted. This makes it excellent
+for timing purposes, however the value in this clock does not correspond to the
+current date and time. Often this clock will be the amount of time your system
+has been on, although it does not have to be. This clock will never be the same
+clock as the system clock as the system clock can change but steady clocks
+cannot.
+
+The third clock defined in the standard is ``std::chrono::high_resolution_clock``.
+This clock is the clock that has the highest resolution out of the clocks in the
+system. It is normally a typedef to either the system clock or the steady clock
+but can be its own independent clock. This is important as when using these
+conversions as the types you get in python for this clock might be different
+depending on the system.
+If it is a typedef of the system clock, python will get datetime objects, but if
+it is a different clock they will be timedelta objects.
+
+Conversions Provided
+--------------------
+
+.. rubric:: C++ to Python
+
+- ``std::chrono::system_clock::time_point`` → ``datetime.datetime``
+ System clock times are converted to python datetime instances. They are
+ in the local timezone, but do not have any timezone information attached
+ to them (they are naive datetime objects).
+
+- ``std::chrono::duration`` → ``datetime.timedelta``
+ Durations are converted to timedeltas, any precision in the duration
+ greater than microseconds is lost by rounding towards zero.
+
+- ``std::chrono::[other_clocks]::time_point`` → ``datetime.timedelta``
+ Any clock time that is not the system clock is converted to a time delta.
+ This timedelta measures the time from the clocks epoch to now.
+
+.. rubric:: Python to C++
+
+- ``datetime.datetime`` → ``std::chrono::system_clock::time_point``
+ Date/time objects are converted into system clock timepoints. Any
+ timezone information is ignored and the type is treated as a naive
+ object.
+
+- ``datetime.timedelta`` → ``std::chrono::duration``
+ Time delta are converted into durations with microsecond precision.
+
+- ``datetime.timedelta`` → ``std::chrono::[other_clocks]::time_point``
+ Time deltas that are converted into clock timepoints are treated as
+ the amount of time from the start of the clocks epoch.
+
+- ``float`` → ``std::chrono::duration``
+ Floats that are passed to C++ as durations be interpreted as a number of
+ seconds. These will be converted to the duration using ``duration_cast``
+ from the float.
+
+- ``float`` → ``std::chrono::[other_clocks]::time_point``
+ Floats that are passed to C++ as time points will be interpreted as the
+ number of seconds from the start of the clocks epoch.
diff --git a/docs/advanced/cast/custom.rst b/docs/advanced/cast/custom.rst
new file mode 100644
index 0000000..50b07db
--- /dev/null
+++ b/docs/advanced/cast/custom.rst
@@ -0,0 +1,79 @@
+Custom type casters
+===================
+
+In very rare cases, applications may require custom type casters that cannot be
+expressed using the abstractions provided by pybind11, thus requiring raw
+Python C API calls. This is fairly advanced usage and should only be pursued by
+experts who are familiar with the intricacies of Python reference counting.
+
+The following snippets demonstrate how this works for a very simple ``inty``
+type that that should be convertible from Python types that provide a
+``__int__(self)`` method.
+
+.. code-block:: cpp
+
+ struct inty { long long_value; };
+
+ void print(inty s) {
+ std::cout << s.long_value << std::endl;
+ }
+
+The following Python snippet demonstrates the intended usage from the Python side:
+
+.. code-block:: python
+
+ class A:
+ def __int__(self):
+ return 123
+
+ from example import print
+ print(A())
+
+To register the necessary conversion routines, it is necessary to add
+a partial overload to the ``pybind11::detail::type_caster<T>`` template.
+Although this is an implementation detail, adding partial overloads to this
+type is explicitly allowed.
+
+.. code-block:: cpp
+
+ namespace pybind11 { namespace detail {
+ template <> struct type_caster<inty> {
+ public:
+ /**
+ * This macro establishes the name 'inty' in
+ * function signatures and declares a local variable
+ * 'value' of type inty
+ */
+ PYBIND11_TYPE_CASTER(inty, _("inty"));
+
+ /**
+ * Conversion part 1 (Python->C++): convert a PyObject into a inty
+ * instance or return false upon failure. The second argument
+ * indicates whether implicit conversions should be applied.
+ */
+ bool load(handle src, bool) {
+ /* Extract PyObject from handle */
+ PyObject *source = src.ptr();
+ /* Try converting into a Python integer value */
+ PyObject *tmp = PyNumber_Long(source);
+ if (!tmp)
+ return false;
+ /* Now try to convert into a C++ int */
+ value.long_value = PyLong_AsLong(tmp);
+ Py_DECREF(tmp);
+ /* Ensure return code was OK (to avoid out-of-range errors etc) */
+ return !(value.long_value == -1 && !PyErr_Occurred());
+ }
+
+ /**
+ * Conversion part 2 (C++ -> Python): convert an inty instance into
+ * a Python object. The second and third arguments are used to
+ * indicate the return value policy and parent object (for
+ * ``return_value_policy::reference_internal``) and are generally
+ * ignored by implicit casters.
+ */
+ static handle cast(inty src, return_value_policy /* policy */, handle /* parent */) {
+ return PyLong_FromLong(src.long_value);
+ }
+ };
+ }} // namespace pybind11::detail
diff --git a/docs/advanced/cast/eigen.rst b/docs/advanced/cast/eigen.rst
new file mode 100644
index 0000000..b83ca9a
--- /dev/null
+++ b/docs/advanced/cast/eigen.rst
@@ -0,0 +1,50 @@
+Eigen
+=====
+
+`Eigen <http://eigen.tuxfamily.org>`_ is C++ header-based library for dense and
+sparse linear algebra. Due to its popularity and widespread adoption, pybind11
+provides transparent conversion support between Eigen and Scientific Python linear
+algebra data types.
+
+Specifically, when including the optional header file :file:`pybind11/eigen.h`,
+pybind11 will automatically and transparently convert
+
+1. Static and dynamic Eigen dense vectors and matrices to instances of
+ ``numpy.ndarray`` (and vice versa).
+
+2. Returned matrix expressions such as blocks (including columns or rows) and
+ diagonals will be converted to ``numpy.ndarray`` of the expression
+ values.
+
+3. Returned matrix-like objects such as Eigen::DiagonalMatrix or
+ Eigen::SelfAdjointView will be converted to ``numpy.ndarray`` containing the
+ expressed value.
+
+4. Eigen sparse vectors and matrices to instances of
+ ``scipy.sparse.csr_matrix``/``scipy.sparse.csc_matrix`` (and vice versa).
+
+This makes it possible to bind most kinds of functions that rely on these types.
+One major caveat are functions that take Eigen matrices *by reference* and modify
+them somehow, in which case the information won't be propagated to the caller.
+
+.. code-block:: cpp
+
+ /* The Python bindings of these functions won't replicate
+ the intended effect of modifying the function arguments */
+ void scale_by_2(Eigen::Vector3f &v) {
+ v *= 2;
+ }
+ void scale_by_2(Eigen::Ref<Eigen::MatrixXd> &v) {
+ v *= 2;
+ }
+
+To see why this is, refer to the section on :ref:`opaque` (although that
+section specifically covers STL data types, the underlying issue is the same).
+The :ref:`numpy` sections discuss an efficient alternative for exposing the
+underlying native Eigen types as opaque objects in a way that still integrates
+with NumPy and SciPy.
+
+.. seealso::
+
+ The file :file:`tests/test_eigen.cpp` contains a complete example that
+ shows how to pass Eigen sparse and dense data types in more detail.
diff --git a/docs/advanced/cast/functional.rst b/docs/advanced/cast/functional.rst
new file mode 100644
index 0000000..5d0a01d
--- /dev/null
+++ b/docs/advanced/cast/functional.rst
@@ -0,0 +1,113 @@
+Functional
+##########
+
+The following features must be enabled by including :file:`pybind11/functional.h`.
+
+
+Callbacks and passing anonymous functions
+=========================================
+
+The C++11 standard brought lambda functions and the generic polymorphic
+function wrapper ``std::function<>`` to the C++ programming language, which
+enable powerful new ways of working with functions. Lambda functions come in
+two flavors: stateless lambda function resemble classic function pointers that
+link to an anonymous piece of code, while stateful lambda functions
+additionally depend on captured variables that are stored in an anonymous
+*lambda closure object*.
+
+Here is a simple example of a C++ function that takes an arbitrary function
+(stateful or stateless) with signature ``int -> int`` as an argument and runs
+it with the value 10.
+
+.. code-block:: cpp
+
+ int func_arg(const std::function<int(int)> &f) {
+ return f(10);
+ }
+
+The example below is more involved: it takes a function of signature ``int -> int``
+and returns another function of the same kind. The return value is a stateful
+lambda function, which stores the value ``f`` in the capture object and adds 1 to
+its return value upon execution.
+
+.. code-block:: cpp
+
+ std::function<int(int)> func_ret(const std::function<int(int)> &f) {
+ return [f](int i) {
+ return f(i) + 1;
+ };
+ }
+
+This example demonstrates using python named parameters in C++ callbacks which
+requires using ``py::cpp_function`` as a wrapper. Usage is similar to defining
+methods of classes:
+
+.. code-block:: cpp
+
+ py::cpp_function func_cpp() {
+ return py::cpp_function([](int i) { return i+1; },
+ py::arg("number"));
+ }
+
+After including the extra header file :file:`pybind11/functional.h`, it is almost
+trivial to generate binding code for all of these functions.
+
+.. code-block:: cpp
+
+ #include <pybind11/functional.h>
+
+ PYBIND11_PLUGIN(example) {
+ py::module m("example", "pybind11 example plugin");
+
+ m.def("func_arg", &func_arg);
+ m.def("func_ret", &func_ret);
+ m.def("func_cpp", &func_cpp);
+
+ return m.ptr();
+ }
+
+The following interactive session shows how to call them from Python.
+
+.. code-block:: pycon
+
+ $ python
+ >>> import example
+ >>> def square(i):
+ ... return i * i
+ ...
+ >>> example.func_arg(square)
+ 100L
+ >>> square_plus_1 = example.func_ret(square)
+ >>> square_plus_1(4)
+ 17L
+ >>> plus_1 = func_cpp()
+ >>> plus_1(number=43)
+ 44L
+
+.. warning::
+
+ Keep in mind that passing a function from C++ to Python (or vice versa)
+ will instantiate a piece of wrapper code that translates function
+ invocations between the two languages. Naturally, this translation
+ increases the computational cost of each function call somewhat. A
+ problematic situation can arise when a function is copied back and forth
+ between Python and C++ many times in a row, in which case the underlying
+ wrappers will accumulate correspondingly. The resulting long sequence of
+ C++ -> Python -> C++ -> ... roundtrips can significantly decrease
+ performance.
+
+ There is one exception: pybind11 detects case where a stateless function
+ (i.e. a function pointer or a lambda function without captured variables)
+ is passed as an argument to another C++ function exposed in Python. In this
+ case, there is no overhead. Pybind11 will extract the underlying C++
+ function pointer from the wrapped function to sidestep a potential C++ ->
+ Python -> C++ roundtrip. This is demonstrated in :file:`tests/test_callbacks.cpp`.
+
+.. note::
+
+ This functionality is very useful when generating bindings for callbacks in
+ C++ libraries (e.g. GUI libraries, asynchronous networking libraries, etc.).
+
+ The file :file:`tests/test_callbacks.cpp` contains a complete example
+ that demonstrates how to work with callbacks and anonymous functions in
+ more detail.
diff --git a/docs/advanced/cast/index.rst b/docs/advanced/cast/index.rst
new file mode 100644
index 0000000..cce3a47
--- /dev/null
+++ b/docs/advanced/cast/index.rst
@@ -0,0 +1,79 @@
+Casting data types
+##################
+
+.. toctree::
+ :maxdepth: 1
+
+ stl
+ functional
+ chrono
+ eigen
+ custom
+
+The following basic data types are supported out of the box (some may require
+an additional extension header to be included). To pass other data structures
+as arguments and return values, refer to the section on binding :ref:`classes`.
+
++---------------------------------+--------------------------+-------------------------------+
+| Data type | Description | Header file |
++=================================+==========================+===============================+
+| ``int8_t``, ``uint8_t`` | 8-bit integers | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``int16_t``, ``uint16_t`` | 16-bit integers | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``int32_t``, ``uint32_t`` | 32-bit integers | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``int64_t``, ``uint64_t`` | 64-bit integers | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``ssize_t``, ``size_t`` | Platform-dependent size | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``float``, ``double`` | Floating point types | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``bool`` | Two-state Boolean type | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``char`` | Character literal | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``wchar_t`` | Wide character literal | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``const char *`` | UTF-8 string literal | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``const wchar_t *`` | Wide string literal | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::string`` | STL dynamic UTF-8 string | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::wstring`` | STL dynamic wide string | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::pair<T1, T2>`` | Pair of two custom types | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::tuple<...>`` | Arbitrary tuple of types | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::reference_wrapper<...>`` | Reference type wrapper | :file:`pybind11/pybind11.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::complex<T>`` | Complex numbers | :file:`pybind11/complex.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::array<T, Size>`` | STL static array | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::vector<T>`` | STL dynamic array | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::list<T>`` | STL linked list | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::map<T1, T2>`` | STL ordered map | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::unordered_map<T1, T2>`` | STL unordered map | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::set<T>`` | STL ordered set | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::unordered_set<T>`` | STL unordered set | :file:`pybind11/stl.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::function<...>`` | STL polymorphic function | :file:`pybind11/functional.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::chrono::duration<...>`` | STL time duration | :file:`pybind11/chrono.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``std::chrono::time_point<...>``| STL date/time | :file:`pybind11/chrono.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``Eigen::Matrix<...>`` | Eigen: dense matrix | :file:`pybind11/eigen.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``Eigen::Map<...>`` | Eigen: mapped memory | :file:`pybind11/eigen.h` |
++---------------------------------+--------------------------+-------------------------------+
+| ``Eigen::SparseMatrix<...>`` | Eigen: sparse matrix | :file:`pybind11/eigen.h` |
++---------------------------------+--------------------------+-------------------------------+
diff --git a/docs/advanced/cast/stl.rst b/docs/advanced/cast/stl.rst
new file mode 100644
index 0000000..bbd2373
--- /dev/null
+++ b/docs/advanced/cast/stl.rst
@@ -0,0 +1,154 @@
+STL containers
+##############
+
+Automatic conversion
+====================
+
+When including the additional header file :file:`pybind11/stl.h`, conversions
+between ``std::vector<>``, ``std::list<>``, ``std::set<>``, and ``std::map<>``
+and the Python ``list``, ``set`` and ``dict`` data structures are automatically
+enabled. The types ``std::pair<>`` and ``std::tuple<>`` are already supported
+out of the box with just the core :file:`pybind11/pybind11.h` header.
+
+The major downside of these implicit conversions is that containers must be
+converted (i.e. copied) on every Python->C++ and C++->Python transition, which
+can have implications on the program semantics and performance. Please read the
+next sections for more details and alternative approaches that avoid this.
+
+.. note::
+
+ Arbitrary nesting of any of these types is possible.
+
+.. seealso::
+
+ The file :file:`tests/test_python_types.cpp` contains a complete
+ example that demonstrates how to pass STL data types in more detail.
+
+.. _opaque:
+
+Making opaque types
+===================
+
+pybind11 heavily relies on a template matching mechanism to convert parameters
+and return values that are constructed from STL data types such as vectors,
+linked lists, hash tables, etc. This even works in a recursive manner, for
+instance to deal with lists of hash maps of pairs of elementary and custom
+types, etc.
+
+However, a fundamental limitation of this approach is that internal conversions
+between Python and C++ types involve a copy operation that prevents
+pass-by-reference semantics. What does this mean?
+
+Suppose we bind the following function
+
+.. code-block:: cpp
+
+ void append_1(std::vector<int> &v) {
+ v.push_back(1);
+ }
+
+and call it from Python, the following happens:
+
+.. code-block:: pycon
+
+ >>> v = [5, 6]
+ >>> append_1(v)
+ >>> print(v)
+ [5, 6]
+
+As you can see, when passing STL data structures by reference, modifications
+are not propagated back the Python side. A similar situation arises when
+exposing STL data structures using the ``def_readwrite`` or ``def_readonly``
+functions:
+
+.. code-block:: cpp
+
+ /* ... definition ... */
+
+ class MyClass {
+ std::vector<int> contents;
+ };
+
+ /* ... binding code ... */
+
+ py::class_<MyClass>(m, "MyClass")
+ .def(py::init<>)
+ .def_readwrite("contents", &MyClass::contents);
+
+In this case, properties can be read and written in their entirety. However, an
+``append`` operation involving such a list type has no effect:
+
+.. code-block:: pycon
+
+ >>> m = MyClass()
+ >>> m.contents = [5, 6]
+ >>> print(m.contents)
+ [5, 6]
+ >>> m.contents.append(7)
+ >>> print(m.contents)
+ [5, 6]
+
+Finally, the involved copy operations can be costly when dealing with very
+large lists. To deal with all of the above situations, pybind11 provides a
+macro named ``PYBIND11_MAKE_OPAQUE(T)`` that disables the template-based
+conversion machinery of types, thus rendering them *opaque*. The contents of
+opaque objects are never inspected or extracted, hence they *can* be passed by
+reference. For instance, to turn ``std::vector<int>`` into an opaque type, add
+the declaration
+
+.. code-block:: cpp
+
+ PYBIND11_MAKE_OPAQUE(std::vector<int>);
+
+before any binding code (e.g. invocations to ``class_::def()``, etc.). This
+macro must be specified at the top level (and outside of any namespaces), since
+it instantiates a partial template overload. If your binding code consists of
+multiple compilation units, it must be present in every file preceding any
+usage of ``std::vector<int>``. Opaque types must also have a corresponding
+``class_`` declaration to associate them with a name in Python, and to define a
+set of available operations, e.g.:
+
+.. code-block:: cpp
+
+ py::class_<std::vector<int>>(m, "IntVector")
+ .def(py::init<>())
+ .def("clear", &std::vector<int>::clear)
+ .def("pop_back", &std::vector<int>::pop_back)
+ .def("__len__", [](const std::vector<int> &v) { return v.size(); })
+ .def("__iter__", [](std::vector<int> &v) {
+ return py::make_iterator(v.begin(), v.end());
+ }, py::keep_alive<0, 1>()) /* Keep vector alive while iterator is used */
+ // ....
+
+The ability to expose STL containers as native Python objects is a fairly
+common request, hence pybind11 also provides an optional header file named
+:file:`pybind11/stl_bind.h` that does exactly this. The mapped containers try
+to match the behavior of their native Python counterparts as much as possible.
+
+The following example showcases usage of :file:`pybind11/stl_bind.h`:
+
+.. code-block:: cpp
+
+ // Don't forget this
+ #include <pybind11/stl_bind.h>
+
+ PYBIND11_MAKE_OPAQUE(std::vector<int>);
+ PYBIND11_MAKE_OPAQUE(std::map<std::string, double>);
+
+ // ...
+
+ // later in binding code:
+ py::bind_vector<std::vector<int>>(m, "VectorInt");
+ py::bind_map<std::map<std::string, double>>(m, "MapStringDouble");
+
+Please take a look at the :ref:`macro_notes` before using the
+``PYBIND11_MAKE_OPAQUE`` macro.
+
+.. seealso::
+
+ The file :file:`tests/test_opaque_types.cpp` contains a complete
+ example that demonstrates how to create and expose opaque types using
+ pybind11 in more detail.
+
+ The file :file:`tests/test_stl_binders.cpp` shows how to use the
+ convenience STL container wrappers.