diff options
Diffstat (limited to 'ext/pybind11/docs/classes.rst')
| -rw-r--r-- | ext/pybind11/docs/classes.rst | 42 |
1 files changed, 37 insertions, 5 deletions
diff --git a/ext/pybind11/docs/classes.rst b/ext/pybind11/docs/classes.rst index ca2477e83..a63f6a196 100644 --- a/ext/pybind11/docs/classes.rst +++ b/ext/pybind11/docs/classes.rst @@ -155,6 +155,9 @@ the setter and getter functions: .def_property("name", &Pet::getName, &Pet::setName) // ... remainder ... +Write only properties can be defined by passing ``nullptr`` as the +input for the read function. + .. seealso:: Similar functions :func:`class_::def_readwrite_static`, @@ -225,8 +228,8 @@ just brings them on par. .. _inheritance: -Inheritance and automatic upcasting -=================================== +Inheritance and automatic downcasting +===================================== Suppose now that the example consists of two data structures with an inheritance relationship: @@ -295,7 +298,7 @@ inheritance relationship. This is reflected in Python: >>> p = example.pet_store() >>> type(p) # `Dog` instance behind `Pet` pointer - Pet # no pointer upcasting for regular non-polymorphic types + Pet # no pointer downcasting for regular non-polymorphic types >>> p.bark() AttributeError: 'Pet' object has no attribute 'bark' @@ -327,11 +330,11 @@ will automatically recognize this: >>> p = example.pet_store2() >>> type(p) - PolymorphicDog # automatically upcast + PolymorphicDog # automatically downcast >>> p.bark() u'woof!' -Given a pointer to a polymorphic base, pybind11 performs automatic upcasting +Given a pointer to a polymorphic base, pybind11 performs automatic downcasting to the actual derived type. Note that this goes beyond the usual situation in C++: we don't just get access to the virtual functions of the base, we get the concrete derived type including functions and attributes that the base type may @@ -419,6 +422,17 @@ on constness, the ``py::const_`` tag should be used: .def("foo_mutable", py::overload_cast<int, float>(&Widget::foo)) .def("foo_const", py::overload_cast<int, float>(&Widget::foo, py::const_)); +If you prefer the ``py::overload_cast`` syntax but have a C++11 compatible compiler only, +you can use ``py::detail::overload_cast_impl`` with an additional set of parentheses: + +.. code-block:: cpp + + template <typename... Args> + using overload_cast_ = pybind11::detail::overload_cast_impl<Args...>; + + py::class_<Pet>(m, "Pet") + .def("set", overload_cast_<int>()(&Pet::set), "Set the pet's age") + .def("set", overload_cast_<const std::string &>()(&Pet::set), "Set the pet's name"); .. [#cpp14] A compiler which supports the ``-std=c++14`` flag or Visual Studio 2015 Update 2 and newer. @@ -485,6 +499,24 @@ The entries defined by the enumeration type are exposed in the ``__members__`` p >>> Pet.Kind.__members__ {'Dog': Kind.Dog, 'Cat': Kind.Cat} +The ``name`` property returns the name of the enum value as a unicode string. + +.. note:: + + It is also possible to use ``str(enum)``, however these accomplish different + goals. The following shows how these two approaches differ. + + .. code-block:: pycon + + >>> p = Pet( "Lucy", Pet.Cat ) + >>> pet_type = p.type + >>> pet_type + Pet.Cat + >>> str(pet_type) + 'Pet.Cat' + >>> pet_type.name + 'Cat' + .. note:: When the special tag ``py::arithmetic()`` is specified to the ``enum_`` |