Merge pull request #289 from jagerman/example-renaming

Rename examples files, as per #288

example/example16.cpp → example/example-inheritance.cpp

 /*
-    example/example16.cpp -- automatic upcasting for polymorphic types
+    example/example-inheritance.cpp -- inheritance, automatic upcasting for polymorphic types
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
 
@@ -9,11 +9,59 @@
 
 #include "example.h"
 
+class Pet {
+public:
+    Pet(const std::string &name, const std::string &species)
+        : m_name(name), m_species(species) {}
+    std::string name() const { return m_name; }
+    std::string species() const { return m_species; }
+private:
+    std::string m_name;
+    std::string m_species;
+};
+
+class Dog : public Pet {
+public:
+    Dog(const std::string &name) : Pet(name, "dog") {}
+    void bark() const { std::cout << "Woof!" << std::endl; }
+};
+
+class Rabbit : public Pet {
+public:
+    Rabbit(const std::string &name) : Pet(name, "parrot") {}
+};
+
+void pet_print(const Pet &pet) {
+    std::cout << pet.name() + " is a " + pet.species() << std::endl;
+}
+
+void dog_bark(const Dog &dog) {
+    dog.bark();
+}
+
+
 struct BaseClass { virtual ~BaseClass() {} };
 struct DerivedClass1 : BaseClass { };
 struct DerivedClass2 : BaseClass { };
 
-void init_ex16(py::module &m) {
+void init_ex_inheritance(py::module &m) {
+    py::class_<Pet> pet_class(m, "Pet");
+    pet_class
+        .def(py::init<std::string, std::string>())
+        .def("name", &Pet::name)
+        .def("species", &Pet::species);
+
+    /* One way of declaring a subclass relationship: reference parent's class_ object */
+    py::class_<Dog>(m, "Dog", pet_class)
+        .def(py::init<std::string>());
+
+    /* Another way of declaring a subclass relationship: reference parent's C++ type */
+    py::class_<Rabbit>(m, "Rabbit", py::base<Pet>())
+        .def(py::init<std::string>());
+
+    m.def("pet_print", pet_print);
+    m.def("dog_bark", dog_bark);
+
     py::class_<BaseClass>(m, "BaseClass").def(py::init<>());
     py::class_<DerivedClass1>(m, "DerivedClass1").def(py::init<>());
     py::class_<DerivedClass2>(m, "DerivedClass2").def(py::init<>());

example/example13.cpp → example/example-keep-alive.cpp

 /*
-    example/example13.cpp -- keep_alive modifier (pybind11's version
+    example/example-keep-alive.cpp -- keep_alive modifier (pybind11's version
     of Boost.Python's with_custodian_and_ward / with_custodian_and_ward_postcall)
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
@@ -24,7 +24,7 @@ public:
     Child *returnChild() { return new Child(); }
 };
 
-void init_ex13(py::module &m) {
+void init_ex_keep_alive(py::module &m) {
     py::class_<Parent>(m, "Parent")
         .def(py::init<>())
         .def("addChild", &Parent::addChild)

example/example1.cpp → example/example-methods-and-attributes.cpp

 /*
-    example/example1.cpp -- constructors, deconstructors, attribute access,
+    example/example-methods-and-attributes.cpp -- constructors, deconstructors, attribute access,
     __str__, argument and return value conventions
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
@@ -10,36 +10,36 @@
 
 #include "example.h"
 
-class Example1 {
+class ExampleMandA {
 public:
-    Example1() {
-        cout << "Called Example1 default constructor.." << endl;
+    ExampleMandA() {
+        cout << "Called ExampleMandA default constructor.." << endl;
     }
-    Example1(int value) : value(value) {
-        cout << "Called Example1 constructor with value " << value << ".." << endl;
+    ExampleMandA(int value) : value(value) {
+        cout << "Called ExampleMandA constructor with value " << value << ".." << endl;
     }
-    Example1(const Example1 &e) : value(e.value) {
-        cout << "Called Example1 copy constructor with value " << value << ".." << endl;
+    ExampleMandA(const ExampleMandA &e) : value(e.value) {
+        cout << "Called ExampleMandA copy constructor with value " << value << ".." << endl;
     }
-    Example1(Example1 &&e) : value(e.value) {
-        cout << "Called Example1 move constructor with value " << value << ".." << endl;
+    ExampleMandA(ExampleMandA &&e) : value(e.value) {
+        cout << "Called ExampleMandA move constructor with value " << value << ".." << endl;
         e.value = 0;
     }
-    ~Example1() {
-        cout << "Called Example1 destructor (" << value << ")" << endl;
+    ~ExampleMandA() {
+        cout << "Called ExampleMandA destructor (" << value << ")" << endl;
     }
     std::string toString() {
-        return "Example1[value=" + std::to_string(value) + "]";
+        return "ExampleMandA[value=" + std::to_string(value) + "]";
     }
 
-    void operator=(const Example1 &e) { cout << "Assignment operator" << endl; value = e.value; }
-    void operator=(Example1 &&e) { cout << "Move assignment operator" << endl; value = e.value; e.value = 0;}
+    void operator=(const ExampleMandA &e) { cout << "Assignment operator" << endl; value = e.value; }
+    void operator=(ExampleMandA &&e) { cout << "Move assignment operator" << endl; value = e.value; e.value = 0;}
 
-    void add1(Example1 other) { value += other.value; }           // passing by value
-    void add2(Example1 &other) { value += other.value; }          // passing by reference
-    void add3(const Example1 &other) { value += other.value; }    // passing by const reference
-    void add4(Example1 *other) { value += other->value; }         // passing by pointer
-    void add5(const Example1 *other) { value += other->value; }   // passing by const pointer
+    void add1(ExampleMandA other) { value += other.value; }           // passing by value
+    void add2(ExampleMandA &other) { value += other.value; }          // passing by reference
+    void add3(const ExampleMandA &other) { value += other.value; }    // passing by const reference
+    void add4(ExampleMandA *other) { value += other->value; }         // passing by pointer
+    void add5(const ExampleMandA *other) { value += other->value; }   // passing by const pointer
 
     void add6(int other) { value += other; }                      // passing by value
     void add7(int &other) { value += other; }                     // passing by reference
@@ -47,11 +47,11 @@ public:
     void add9(int *other) { value += *other; }                    // passing by pointer
     void add10(const int *other) { value += *other; }             // passing by const pointer
 
-    Example1 self1() { return *this; }                            // return by value
-    Example1 &self2() { return *this; }                           // return by reference
-    const Example1 &self3() { return *this; }                     // return by const reference
-    Example1 *self4() { return this; }                            // return by pointer
-    const Example1 *self5() { return this; }                      // return by const pointer
+    ExampleMandA self1() { return *this; }                            // return by value
+    ExampleMandA &self2() { return *this; }                           // return by reference
+    const ExampleMandA &self3() { return *this; }                     // return by const reference
+    ExampleMandA *self4() { return this; }                            // return by pointer
+    const ExampleMandA *self5() { return this; }                      // return by const pointer
 
     int internal1() { return value; }                             // return by value
     int &internal2() { return value; }                            // return by reference
@@ -62,31 +62,31 @@ public:
     int value = 0;
 };
 
-void init_ex1(py::module &m) {
-    py::class_<Example1>(m, "Example1")
+void init_ex_methods_and_attributes(py::module &m) {
+    py::class_<ExampleMandA>(m, "ExampleMandA")
         .def(py::init<>())
         .def(py::init<int>())
-        .def(py::init<const Example1&>())
-        .def("add1", &Example1::add1)
-        .def("add2", &Example1::add2)
-        .def("add3", &Example1::add3)
-        .def("add4", &Example1::add4)
-        .def("add5", &Example1::add5)
-        .def("add6", &Example1::add6)
-        .def("add7", &Example1::add7)
-        .def("add8", &Example1::add8)
-        .def("add9", &Example1::add9)
-        .def("add10", &Example1::add10)
-        .def("self1", &Example1::self1)
-        .def("self2", &Example1::self2)
-        .def("self3", &Example1::self3)
-        .def("self4", &Example1::self4)
-        .def("self5", &Example1::self5)
-        .def("internal1", &Example1::internal1)
-        .def("internal2", &Example1::internal2)
-        .def("internal3", &Example1::internal3)
-        .def("internal4", &Example1::internal4)
-        .def("internal5", &Example1::internal5)
-        .def("__str__", &Example1::toString)
-        .def_readwrite("value", &Example1::value);
+        .def(py::init<const ExampleMandA&>())
+        .def("add1", &ExampleMandA::add1)
+        .def("add2", &ExampleMandA::add2)
+        .def("add3", &ExampleMandA::add3)
+        .def("add4", &ExampleMandA::add4)
+        .def("add5", &ExampleMandA::add5)
+        .def("add6", &ExampleMandA::add6)
+        .def("add7", &ExampleMandA::add7)
+        .def("add8", &ExampleMandA::add8)
+        .def("add9", &ExampleMandA::add9)
+        .def("add10", &ExampleMandA::add10)
+        .def("self1", &ExampleMandA::self1)
+        .def("self2", &ExampleMandA::self2)
+        .def("self3", &ExampleMandA::self3)
+        .def("self4", &ExampleMandA::self4)
+        .def("self5", &ExampleMandA::self5)
+        .def("internal1", &ExampleMandA::internal1)
+        .def("internal2", &ExampleMandA::internal2)
+        .def("internal3", &ExampleMandA::internal3)
+        .def("internal4", &ExampleMandA::internal4)
+        .def("internal5", &ExampleMandA::internal5)
+        .def("__str__", &ExampleMandA::toString)
+        .def_readwrite("value", &ExampleMandA::value);
 }

example/example1.py → example/example-methods-and-attributes.py

@@ -3,10 +3,10 @@ from __future__ import print_function
 import sys
 sys.path.append('.')
 
-from example import Example1
+from example import ExampleMandA
 
-instance1 = Example1()
-instance2 = Example1(32)
+instance1 = ExampleMandA()
+instance2 = ExampleMandA(32)
 instance1.add1(instance2)
 instance1.add2(instance2)
 instance1.add3(instance2)

example/example-methods-and-attributes.ref

+Called ExampleMandA default constructor..
+Called ExampleMandA constructor with value 32..
+Called ExampleMandA copy constructor with value 32..
+Called ExampleMandA copy constructor with value 32..
+Called ExampleMandA destructor (32)
+Called ExampleMandA destructor (32)
+Instance 1: ExampleMandA[value=320]
+Instance 2: ExampleMandA[value=32]
+Called ExampleMandA copy constructor with value 320..
+Called ExampleMandA move constructor with value 320..
+Called ExampleMandA destructor (0)
+ExampleMandA[value=320]
+Called ExampleMandA destructor (320)
+ExampleMandA[value=320]
+ExampleMandA[value=320]
+ExampleMandA[value=320]
+ExampleMandA[value=320]
+320
+320
+320
+320
+320
+Instance 1, direct access = 320
+Instance 1: ExampleMandA[value=100]
+Called ExampleMandA destructor (32)
+Called ExampleMandA destructor (100)

example/example9.cpp → example/example-modules.cpp

 /*
-    example/example9.cpp -- nested modules, importing modules, and
+    example/example-modules.cpp -- nested modules, importing modules, and
                             internal references
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
@@ -36,7 +36,7 @@ public:
     A a2{2};
 };
 
-void init_ex9(py::module &m) {
+void init_ex_modules(py::module &m) {
     py::module m_sub = m.def_submodule("submodule");
     m_sub.def("submodule_func", &submodule_func);
 

example/example10.cpp → example/example-numpy-vectorize.cpp

 /*
-    example/example10.cpp -- auto-vectorize functions over NumPy array
+    example/example-numpy-vectorize.cpp -- auto-vectorize functions over NumPy array
     arguments
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
@@ -20,7 +20,7 @@ std::complex<double> my_func3(std::complex<double> c) {
     return c * std::complex<double>(2.f);
 }
 
-void init_ex10(py::module &m) {
+void init_ex_numpy_vectorize(py::module &m) {
     // Vectorize all arguments of a function (though non-vector arguments are also allowed)
     m.def("vectorized_func", py::vectorize(my_func));
 

example/example14.cpp → example/example-opaque-types.cpp

 /*
-    example/example14.cpp -- opaque types, passing void pointers
+    example/example-opaque-types.cpp -- opaque types, passing void pointers
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
 
@@ -21,7 +21,7 @@ public:
 /* IMPORTANT: Disable internal pybind11 translation mechanisms for STL data structures */
 PYBIND11_MAKE_OPAQUE(StringList);
 
-void init_ex14(py::module &m) {
+void init_ex_opaque_types(py::module &m) {
     py::class_<StringList>(m, "StringList")
         .def(py::init<>())
         .def("pop_back", &StringList::pop_back)

example/example14.py → example/example-opaque-types.py

@@ -8,7 +8,7 @@ from example import ClassWithSTLVecProperty
 from example import return_void_ptr, print_void_ptr
 from example import return_null_str, print_null_str
 from example import return_unique_ptr
-from example import Example1
+from example import ExampleMandA
 
 #####
 
@@ -33,7 +33,7 @@ print_opaque_list(cvp.stringList)
 #####
 
 print_void_ptr(return_void_ptr())
-print_void_ptr(Example1())  # Should also work for other C++ types
+print_void_ptr(ExampleMandA())  # Should also work for other C++ types
 
 try:
     print_void_ptr([1, 2, 3])  # This should not work

example/example14.ref → example/example-opaque-types.ref

@@ -6,9 +6,9 @@ Opaque list: [Element 1]
 Opaque list: []
 Opaque list: [Element 1, Element 3]
 Got void ptr : 0x1234
-Called Example1 default constructor..
+Called ExampleMandA default constructor..
 Got void ptr : 0x7f9ba0f3c430
-Called Example1 destructor (0)
+Called ExampleMandA destructor (0)
 Caught expected exception: Incompatible function arguments. The following argument types are supported:
     1. (capsule) -> NoneType
     Invoked with: [1, 2, 3]

example/example3.cpp → example/example-operator-overloading.cpp

 /*
-    example/example3.cpp -- operator overloading
+    example/example-operator-overloading.cpp -- operator overloading
 
     Copyright (c) 2016 Wenzel Jakob <wenzel.jakob@epfl.ch>
 
@@ -52,7 +52,7 @@ private:
 };
 
 
-void init_ex3(py::module &m) {
+void init_ex_operator_overloading(py::module &m) {
     py::class_<Vector2>(m, "Vector2")
         .def(py::init<float, float>())
         .def(py::self + py::self)