Rename to py::prepend and add docs mention

Author: henryiii

docs/changelog.rst

@@ -14,6 +14,8 @@ v2.3.0 (Not yet released)
   precomputed at compile time (this was previously only available in C++14 mode
   for non-MSVC compilers).
   `#934 <https://github.com/pybind/pybind11/pull/934>`_.
+* Added ``py::prepend()``, allowing a function to be placed at the beginning of the
+  overload chain `#1131 <https://github.com/pybind/pybind11/pull/1131>`_.
 
 v2.2.1 (September 14, 2017)
 -----------------------------------------------------

docs/classes.rst

@@ -364,7 +364,9 @@ Attempting to bind ``Pet::set`` will cause an error since the compiler does not
 know which method the user intended to select. We can disambiguate by casting
 them to function pointers. Binding multiple functions to the same Python name
 automatically creates a chain of function overloads that will be tried in
-sequence.
+the order they were defined. If the ``py::prepend()`` tag is added to the
+definition, the function will be placed at the begining of the overload sequence
+instead.
 
 .. code-block:: cpp
 

include/pybind11/attr.h

@@ -71,7 +71,7 @@ struct module_local { const bool value; constexpr module_local(bool v = true) :
 struct arithmetic { };
 
 /// Annotation to mark a function as top for the overload chain
-struct priority_overload { };
+struct prepend { };
 
 /** \rst
     A call policy which places one or more guard variables (``Ts...``) around the function call.
@@ -138,7 +138,7 @@ struct function_record {
     function_record()
         : is_constructor(false), is_new_style_constructor(false), is_stateless(false),
           is_operator(false), has_args(false), has_kwargs(false), is_method(false),
-          is_priority_overload(false) { }
+          is_prepended(false) { }
 
     /// Function name
     char *name = nullptr; /* why no C++ strings? They generate heavier code.. */
@@ -185,8 +185,8 @@ struct function_record {
     /// True if this is a method
     bool is_method : 1;
 
-    /// True if this function takes priority when defined in overload resolution
-    bool is_priority_overload : 1;
+    /// True if this function is to be inserted at the beginning of the overload resolution chain
+    bool is_prepended : 1;
 
     /// Number of arguments (including py::args and/or py::kwargs, if present)
     std::uint16_t nargs;
@@ -434,9 +434,9 @@ struct process_attribute<module_local> : process_attribute_default<module_local>
     static void init(const module_local &l, type_record *r) { r->module_local = l.value; }
 };
 
-/// Process an 'priority_overload' attribute, putting this at the top of the overload chain
-template <> struct process_attribute<priority_overload> : process_attribute_default<priority_overload> {
-    static void init(const priority_overload &, function_record *r) { r->is_priority_overload = true; }
+/// Process an 'prepend' attribute, putting this at the top of the overload chain
+template <> struct process_attribute<prepend> : process_attribute_default<prepend> {
+    static void init(const prepend &, function_record *r) { r->is_prepended = true; }
 };
 
 /// Process an 'arithmetic' attribute for enums (does nothing here)

include/pybind11/pybind11.h

@@ -341,7 +341,7 @@ class cpp_function : public function {
                     #endif
                 );
 
-            if (rec->is_priority_overload) {
+            if (rec->is_prepended) {
                 // Beginning of chain
                 chain_start = rec;
                 rec->next = chain;

tests/test_methods_and_attributes.cpp

@@ -335,8 +335,8 @@ TEST_SUBMODULE(methods_and_attributes, m) {
     py::class_<OverloadOrder>(m, "OverloadOrder")
         .def(py::init([](std::string) { return new OverloadOrder{1};}))
         .def(py::init([](std::string) { return new OverloadOrder{2};}))
-        .def(py::init([](int) { return new OverloadOrder{1};}))
-        .def(py::init([](int) { return new OverloadOrder{2};}), py::priority_overload())
+        .def(py::init([](int) { return new OverloadOrder{3};}))
+        .def(py::init([](int) { return new OverloadOrder{4};}), py::prepend())
         .def_readonly("value", &OverloadOrder::value);
 
 #if !defined(PYPY_VERSION)

tests/test_methods_and_attributes.py

@@ -477,8 +477,10 @@ def test_custom_caster_destruction():
 
 
 def test_overload_order_normal():
+    'Check to see if the normal overload order (first defined) works'
     assert m.OverloadOrder("this").value == 1
 
 
 def test_overload_order_priority():
-    assert m.OverloadOrder(0).value == 2
+    'Check to see if the prepend overload order works'
+    assert m.OverloadOrder(0).value == 4