documentation improvements

docs/advanced.rst

@@ -373,10 +373,10 @@ Passing STL data structures
 ===========================
 ===========================
 
 
 When including the additional header file :file:`pybind11/stl.h`, conversions
 When including the additional header file :file:`pybind11/stl.h`, conversions
-between ``std::vector<>``, ``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.
+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.
 
 
 .. note::
 .. note::
 
 
@@ -457,7 +457,7 @@ See below for an example that uses the
 
 
         py::class_<Example>(m, "Example")
         py::class_<Example>(m, "Example")
             .def(py::init<>())
             .def(py::init<>())
-            .def("get_internal", &Example::get_internal, "Return the internal data", py::return_value_policy::reference_internal)
+            .def("get_internal", &Example::get_internal, "Return the internal data", py::return_value_policy::reference_internal);
 
 
         return m.ptr();
         return m.ptr();
     }
     }
@@ -705,23 +705,35 @@ automatically converted into a Python ``Exception``. pybind11 defines multiple
 special exception classes that will map to different types of Python
 special exception classes that will map to different types of Python
 exceptions:
 exceptions:
 
 
-+----------------------------+------------------------------+
-|  C++ exception type        |  Python exception type       |
-+============================+==============================+
-| :class:`std::exception`    | ``Exception``                |
-+----------------------------+------------------------------+
-| :class:`stop_iteration`    | ``StopIteration`` (used to   |
-|                            | implement custom iterators)  |
-+----------------------------+------------------------------+
-| :class:`index_error`       | ``IndexError`` (used to      |
-|                            | indicate out of bounds       |
-|                            | accesses in ``__getitem__``, |
-|                            | ``__setitem__``, etc.)       |
-+----------------------------+------------------------------+
-| :class:`error_already_set` | Indicates that the Python    |
-|                            | exception flag has already   |
-|                            | been initialized.            |
-+----------------------------+------------------------------+
++--------------------------------------+------------------------------+
+|  C++ exception type                  |  Python exception type       |
++======================================+==============================+
+| :class:`std::exception`              | ``RuntimeError``             |
++--------------------------------------+------------------------------+
+| :class:`std::bad_alloc`              | ``MemoryError``              |
++--------------------------------------+------------------------------+
+| :class:`std::domain_error`           | ``ValueError``               |
++--------------------------------------+------------------------------+
+| :class:`std::invalid_argument`       | ``ValueError``               |
++--------------------------------------+------------------------------+
+| :class:`std::length_error`           | ``ValueError``               |
++--------------------------------------+------------------------------+
+| :class:`std::out_of_range`           | ``ValueError``               |
++--------------------------------------+------------------------------+
+| :class:`std::range_error`            | ``ValueError``               |
++--------------------------------------+------------------------------+
+| :class:`pybind11::stop_iteration`    | ``StopIteration`` (used to   |
+|                                      | implement custom iterators)  |
++--------------------------------------+------------------------------+
+| :class:`pybind11::index_error`       | ``IndexError`` (used to      |
+|                                      | indicate out of bounds       |
+|                                      | accesses in ``__getitem__``, |
+|                                      | ``__setitem__``, etc.)       |
++--------------------------------------+------------------------------+
+| :class:`pybind11::error_already_set` | Indicates that the Python    |
+|                                      | exception flag has already   |
+|                                      | been initialized             |
++--------------------------------------+------------------------------+
 
 
 When a Python function invoked from C++ throws an exception, it is converted
 When a Python function invoked from C++ throws an exception, it is converted
 into a C++ exception of type :class:`error_already_set` whose string payload
 into a C++ exception of type :class:`error_already_set` whose string payload
@@ -735,9 +747,9 @@ Buffer protocol
 ===============
 ===============
 
 
 Python supports an extremely general and convenient approach for exchanging
 Python supports an extremely general and convenient approach for exchanging
-data between plugin libraries. Types can expose a buffer view which provides
-fast direct access to the raw internal representation. Suppose we want to bind
-the following simplistic Matrix class:
+data between plugin libraries. Types can expose a buffer view [#f1]_,
+which provides fast direct access to the raw internal representation. Suppose
+we want to bind the following simplistic Matrix class:
 
 
 .. code-block:: cpp
 .. code-block:: cpp
 
 
@@ -829,12 +841,14 @@ objects (e.g. a NumPy matrix).
     The file :file:`example/example7.cpp` contains a complete example that
     The file :file:`example/example7.cpp` contains a complete example that
     demonstrates using the buffer protocol with pybind11 in more detail.
     demonstrates using the buffer protocol with pybind11 in more detail.
 
 
+.. [#f1] https://docs.python.org/3/c-api/buffer.html
+
 NumPy support
 NumPy support
 =============
 =============
 
 
 By exchanging ``py::buffer`` with ``py::array`` in the above snippet, we can
 By exchanging ``py::buffer`` with ``py::array`` in the above snippet, we can
 restrict the function so that it only accepts NumPy arrays (rather than any
 restrict the function so that it only accepts NumPy arrays (rather than any
-type of Python object satisfying the buffer object protocol).
+type of Python object satisfying the buffer protocol).
 
 
 In many situations, we want to define a function which only accepts a NumPy
 In many situations, we want to define a function which only accepts a NumPy
 array of a certain data type. This is possible via the ``py::array_t<T>``
 array of a certain data type. This is possible via the ``py::array_t<T>``
@@ -846,8 +860,9 @@ dense array of doubles in C-style ordering.
     void f(py::array_t<double> array);
     void f(py::array_t<double> array);
 
 
 When it is invoked with a different type (e.g. an integer), the binding code
 When it is invoked with a different type (e.g. an integer), the binding code
-will attempt to cast the input into a NumPy array of the requested type.
-Note that this feature requires the ``pybind11/numpy.h`` header to be included.
+will attempt to cast the input into a NumPy array of the requested type. Note
+that this feature requires the :file:``pybind11/numpy.h`` header to be
+included.
 
 
 Vectorizing functions
 Vectorizing functions
 =====================
 =====================
@@ -867,7 +882,10 @@ After including the ``pybind11/numpy.h`` header, this is extremely simple:
     m.def("vectorized_func", py::vectorize(my_func));
     m.def("vectorized_func", py::vectorize(my_func));
 
 
 Invoking the function like below causes 4 calls to be made to ``my_func`` with
 Invoking the function like below causes 4 calls to be made to ``my_func`` with
-each of the the array elements. The result is returned as a NumPy array of type
+each of the the array elements. The significant advantage of this compared to
+solutions like ``numpy.vectorize()`` is that the loop over the elements runs
+entirely on the C++ side and can be crunched down into a tight, optimized loop
+by the compiler. The result is returned as a NumPy array of type
 ``numpy.dtype.float64``.
 ``numpy.dtype.float64``.
 
 
 .. code-block:: python
 .. code-block:: python
@@ -1085,8 +1103,6 @@ lookup of the corresponding Python type. However, this also requires invoking
 the ``import`` function once to ensure that the pybind11 binding code of the
 the ``import`` function once to ensure that the pybind11 binding code of the
 module ``basic`` has been executed.
 module ``basic`` has been executed.
 
 
-Naturally, both methods will fail when there are cyclic dependencies.
-
 .. code-block:: cpp
 .. code-block:: cpp
 
 
     py::module::import("basic");
     py::module::import("basic");
@@ -1095,6 +1111,8 @@ Naturally, both methods will fail when there are cyclic dependencies.
         .def(py::init<const std::string &>())
         .def(py::init<const std::string &>())
         .def("bark", &Dog::bark);
         .def("bark", &Dog::bark);
 
 
+Naturally, both methods will fail when there are cyclic dependencies.
+
 Treating STL data structures as opaque objects
 Treating STL data structures as opaque objects
 ==============================================
 ==============================================
 
 
@@ -1104,9 +1122,9 @@ 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
 instance to deal with lists of hash maps of pairs of elementary and custom
 types, etc.
 types, etc.
 
 
-The fundamental limitation of this approach is the internal conversion between
-Python and C++ types involves a copy operation that prevents pass-by-reference
-semantics. What does this mean?
+A fundamental limitation of this approach is that the internal conversion
+between Python and C++ types involves a copy operation that prevents
+pass-by-reference semantics. What does this mean?
 
 
 Suppose we bind the following function
 Suppose we bind the following function