Adding pybind11 v2.2.4 to repo
[tidl/tidl-api.git] / tidl_api / pybind11 / include / pybind11 / stl_bind.h
1 /*
2     pybind11/std_bind.h: Binding generators for STL data types
4     Copyright (c) 2016 Sergey Lyskov and Wenzel Jakob
6     All rights reserved. Use of this source code is governed by a
7     BSD-style license that can be found in the LICENSE file.
8 */
10 #pragma once
12 #include "detail/common.h"
13 #include "operators.h"
15 #include <algorithm>
16 #include <sstream>
18 NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
19 NAMESPACE_BEGIN(detail)
21 /* SFINAE helper class used by 'is_comparable */
22 template <typename T>  struct container_traits {
23     template <typename T2> static std::true_type test_comparable(decltype(std::declval<const T2 &>() == std::declval<const T2 &>())*);
24     template <typename T2> static std::false_type test_comparable(...);
25     template <typename T2> static std::true_type test_value(typename T2::value_type *);
26     template <typename T2> static std::false_type test_value(...);
27     template <typename T2> static std::true_type test_pair(typename T2::first_type *, typename T2::second_type *);
28     template <typename T2> static std::false_type test_pair(...);
30     static constexpr const bool is_comparable = std::is_same<std::true_type, decltype(test_comparable<T>(nullptr))>::value;
31     static constexpr const bool is_pair = std::is_same<std::true_type, decltype(test_pair<T>(nullptr, nullptr))>::value;
32     static constexpr const bool is_vector = std::is_same<std::true_type, decltype(test_value<T>(nullptr))>::value;
33     static constexpr const bool is_element = !is_pair && !is_vector;
34 };
36 /* Default: is_comparable -> std::false_type */
37 template <typename T, typename SFINAE = void>
38 struct is_comparable : std::false_type { };
40 /* For non-map data structures, check whether operator== can be instantiated */
41 template <typename T>
42 struct is_comparable<
43     T, enable_if_t<container_traits<T>::is_element &&
44                    container_traits<T>::is_comparable>>
45     : std::true_type { };
47 /* For a vector/map data structure, recursively check the value type (which is std::pair for maps) */
48 template <typename T>
49 struct is_comparable<T, enable_if_t<container_traits<T>::is_vector>> {
50     static constexpr const bool value =
51         is_comparable<typename T::value_type>::value;
52 };
54 /* For pairs, recursively check the two data types */
55 template <typename T>
56 struct is_comparable<T, enable_if_t<container_traits<T>::is_pair>> {
57     static constexpr const bool value =
58         is_comparable<typename T::first_type>::value &&
59         is_comparable<typename T::second_type>::value;
60 };
62 /* Fallback functions */
63 template <typename, typename, typename... Args> void vector_if_copy_constructible(const Args &...) { }
64 template <typename, typename, typename... Args> void vector_if_equal_operator(const Args &...) { }
65 template <typename, typename, typename... Args> void vector_if_insertion_operator(const Args &...) { }
66 template <typename, typename, typename... Args> void vector_modifiers(const Args &...) { }
68 template<typename Vector, typename Class_>
69 void vector_if_copy_constructible(enable_if_t<is_copy_constructible<Vector>::value, Class_> &cl) {
70     cl.def(init<const Vector &>(), "Copy constructor");
71 }
73 template<typename Vector, typename Class_>
74 void vector_if_equal_operator(enable_if_t<is_comparable<Vector>::value, Class_> &cl) {
75     using T = typename Vector::value_type;
77     cl.def(self == self);
78     cl.def(self != self);
80     cl.def("count",
81         [](const Vector &v, const T &x) {
82             return std::count(v.begin(), v.end(), x);
83         },
84         arg("x"),
85         "Return the number of times ``x`` appears in the list"
86     );
88     cl.def("remove", [](Vector &v, const T &x) {
89             auto p = std::find(v.begin(), v.end(), x);
90             if (p != v.end())
91                 v.erase(p);
92             else
93                 throw value_error();
94         },
95         arg("x"),
96         "Remove the first item from the list whose value is x. "
97         "It is an error if there is no such item."
98     );
100     cl.def("__contains__",
101         [](const Vector &v, const T &x) {
102             return std::find(v.begin(), v.end(), x) != v.end();
103         },
104         arg("x"),
105         "Return true the container contains ``x``"
106     );
109 // Vector modifiers -- requires a copyable vector_type:
110 // (Technically, some of these (pop and __delitem__) don't actually require copyability, but it seems
111 // silly to allow deletion but not insertion, so include them here too.)
112 template <typename Vector, typename Class_>
113 void vector_modifiers(enable_if_t<is_copy_constructible<typename Vector::value_type>::value, Class_> &cl) {
114     using T = typename Vector::value_type;
115     using SizeType = typename Vector::size_type;
116     using DiffType = typename Vector::difference_type;
118     cl.def("append",
119            [](Vector &v, const T &value) { v.push_back(value); },
120            arg("x"),
121            "Add an item to the end of the list");
123     cl.def(init([](iterable it) {
124         auto v = std::unique_ptr<Vector>(new Vector());
125         v->reserve(len(it));
126         for (handle h : it)
127            v->push_back(h.cast<T>());
128         return v.release();
129     }));
131     cl.def("extend",
132        [](Vector &v, const Vector &src) {
133            v.insert(v.end(), src.begin(), src.end());
134        },
135        arg("L"),
136        "Extend the list by appending all the items in the given list"
137     );
139     cl.def("insert",
140         [](Vector &v, SizeType i, const T &x) {
141             if (i > v.size())
142                 throw index_error();
143             v.insert(v.begin() + (DiffType) i, x);
144         },
145         arg("i") , arg("x"),
146         "Insert an item at a given position."
147     );
149     cl.def("pop",
150         [](Vector &v) {
151             if (v.empty())
152                 throw index_error();
153             T t = v.back();
154             v.pop_back();
155             return t;
156         },
157         "Remove and return the last item"
158     );
160     cl.def("pop",
161         [](Vector &v, SizeType i) {
162             if (i >= v.size())
163                 throw index_error();
164             T t = v[i];
165             v.erase(v.begin() + (DiffType) i);
166             return t;
167         },
168         arg("i"),
169         "Remove and return the item at index ``i``"
170     );
172     cl.def("__setitem__",
173         [](Vector &v, SizeType i, const T &t) {
174             if (i >= v.size())
175                 throw index_error();
176             v[i] = t;
177         }
178     );
180     /// Slicing protocol
181     cl.def("__getitem__",
182         [](const Vector &v, slice slice) -> Vector * {
183             size_t start, stop, step, slicelength;
185             if (!slice.compute(v.size(), &start, &stop, &step, &slicelength))
186                 throw error_already_set();
188             Vector *seq = new Vector();
189             seq->reserve((size_t) slicelength);
191             for (size_t i=0; i<slicelength; ++i) {
192                 seq->push_back(v[start]);
193                 start += step;
194             }
195             return seq;
196         },
197         arg("s"),
198         "Retrieve list elements using a slice object"
199     );
201     cl.def("__setitem__",
202         [](Vector &v, slice slice,  const Vector &value) {
203             size_t start, stop, step, slicelength;
204             if (!slice.compute(v.size(), &start, &stop, &step, &slicelength))
205                 throw error_already_set();
207             if (slicelength != value.size())
208                 throw std::runtime_error("Left and right hand size of slice assignment have different sizes!");
210             for (size_t i=0; i<slicelength; ++i) {
211                 v[start] = value[i];
212                 start += step;
213             }
214         },
215         "Assign list elements using a slice object"
216     );
218     cl.def("__delitem__",
219         [](Vector &v, SizeType i) {
220             if (i >= v.size())
221                 throw index_error();
222             v.erase(v.begin() + DiffType(i));
223         },
224         "Delete the list elements at index ``i``"
225     );
227     cl.def("__delitem__",
228         [](Vector &v, slice slice) {
229             size_t start, stop, step, slicelength;
231             if (!slice.compute(v.size(), &start, &stop, &step, &slicelength))
232                 throw error_already_set();
234             if (step == 1 && false) {
235                 v.erase(v.begin() + (DiffType) start, v.begin() + DiffType(start + slicelength));
236             } else {
237                 for (size_t i = 0; i < slicelength; ++i) {
238                     v.erase(v.begin() + DiffType(start));
239                     start += step - 1;
240                 }
241             }
242         },
243         "Delete list elements using a slice object"
244     );
248 // If the type has an operator[] that doesn't return a reference (most notably std::vector<bool>),
249 // we have to access by copying; otherwise we return by reference.
250 template <typename Vector> using vector_needs_copy = negation<
251     std::is_same<decltype(std::declval<Vector>()[typename Vector::size_type()]), typename Vector::value_type &>>;
253 // The usual case: access and iterate by reference
254 template <typename Vector, typename Class_>
255 void vector_accessor(enable_if_t<!vector_needs_copy<Vector>::value, Class_> &cl) {
256     using T = typename Vector::value_type;
257     using SizeType = typename Vector::size_type;
258     using ItType   = typename Vector::iterator;
260     cl.def("__getitem__",
261         [](Vector &v, SizeType i) -> T & {
262             if (i >= v.size())
263                 throw index_error();
264             return v[i];
265         },
266         return_value_policy::reference_internal // ref + keepalive
267     );
269     cl.def("__iter__",
270            [](Vector &v) {
271                return make_iterator<
272                    return_value_policy::reference_internal, ItType, ItType, T&>(
273                    v.begin(), v.end());
274            },
275            keep_alive<0, 1>() /* Essential: keep list alive while iterator exists */
276     );
279 // The case for special objects, like std::vector<bool>, that have to be returned-by-copy:
280 template <typename Vector, typename Class_>
281 void vector_accessor(enable_if_t<vector_needs_copy<Vector>::value, Class_> &cl) {
282     using T = typename Vector::value_type;
283     using SizeType = typename Vector::size_type;
284     using ItType   = typename Vector::iterator;
285     cl.def("__getitem__",
286         [](const Vector &v, SizeType i) -> T {
287             if (i >= v.size())
288                 throw index_error();
289             return v[i];
290         }
291     );
293     cl.def("__iter__",
294            [](Vector &v) {
295                return make_iterator<
296                    return_value_policy::copy, ItType, ItType, T>(
297                    v.begin(), v.end());
298            },
299            keep_alive<0, 1>() /* Essential: keep list alive while iterator exists */
300     );
303 template <typename Vector, typename Class_> auto vector_if_insertion_operator(Class_ &cl, std::string const &name)
304     -> decltype(std::declval<std::ostream&>() << std::declval<typename Vector::value_type>(), void()) {
305     using size_type = typename Vector::size_type;
307     cl.def("__repr__",
308            [name](Vector &v) {
309             std::ostringstream s;
310             s << name << '[';
311             for (size_type i=0; i < v.size(); ++i) {
312                 s << v[i];
313                 if (i != v.size() - 1)
314                     s << ", ";
315             }
316             s << ']';
317             return s.str();
318         },
319         "Return the canonical string representation of this list."
320     );
323 // Provide the buffer interface for vectors if we have data() and we have a format for it
324 // GCC seems to have "void std::vector<bool>::data()" - doing SFINAE on the existence of data() is insufficient, we need to check it returns an appropriate pointer
325 template <typename Vector, typename = void>
326 struct vector_has_data_and_format : std::false_type {};
327 template <typename Vector>
328 struct vector_has_data_and_format<Vector, enable_if_t<std::is_same<decltype(format_descriptor<typename Vector::value_type>::format(), std::declval<Vector>().data()), typename Vector::value_type*>::value>> : std::true_type {};
330 // Add the buffer interface to a vector
331 template <typename Vector, typename Class_, typename... Args>
332 enable_if_t<detail::any_of<std::is_same<Args, buffer_protocol>...>::value>
333 vector_buffer(Class_& cl) {
334     using T = typename Vector::value_type;
336     static_assert(vector_has_data_and_format<Vector>::value, "There is not an appropriate format descriptor for this vector");
338     // numpy.h declares this for arbitrary types, but it may raise an exception and crash hard at runtime if PYBIND11_NUMPY_DTYPE hasn't been called, so check here
339     format_descriptor<T>::format();
341     cl.def_buffer([](Vector& v) -> buffer_info {
342         return buffer_info(v.data(), static_cast<ssize_t>(sizeof(T)), format_descriptor<T>::format(), 1, {v.size()}, {sizeof(T)});
343     });
345     cl.def(init([](buffer buf) {
346         auto info = buf.request();
347         if (info.ndim != 1 || info.strides[0] % static_cast<ssize_t>(sizeof(T)))
348             throw type_error("Only valid 1D buffers can be copied to a vector");
349         if (!detail::compare_buffer_info<T>::compare(info) || (ssize_t) sizeof(T) != info.itemsize)
350             throw type_error("Format mismatch (Python: " + info.format + " C++: " + format_descriptor<T>::format() + ")");
352         auto vec = std::unique_ptr<Vector>(new Vector());
353         vec->reserve((size_t) info.shape[0]);
354         T *p = static_cast<T*>(info.ptr);
355         ssize_t step = info.strides[0] / static_cast<ssize_t>(sizeof(T));
356         T *end = p + info.shape[0] * step;
357         for (; p != end; p += step)
358             vec->push_back(*p);
359         return vec.release();
360     }));
362     return;
365 template <typename Vector, typename Class_, typename... Args>
366 enable_if_t<!detail::any_of<std::is_same<Args, buffer_protocol>...>::value> vector_buffer(Class_&) {}
368 NAMESPACE_END(detail)
370 //
371 // std::vector
372 //
373 template <typename Vector, typename holder_type = std::unique_ptr<Vector>, typename... Args>
374 class_<Vector, holder_type> bind_vector(handle scope, std::string const &name, Args&&... args) {
375     using Class_ = class_<Vector, holder_type>;
377     // If the value_type is unregistered (e.g. a converting type) or is itself registered
378     // module-local then make the vector binding module-local as well:
379     using vtype = typename Vector::value_type;
380     auto vtype_info = detail::get_type_info(typeid(vtype));
381     bool local = !vtype_info || vtype_info->module_local;
383     Class_ cl(scope, name.c_str(), pybind11::module_local(local), std::forward<Args>(args)...);
385     // Declare the buffer interface if a buffer_protocol() is passed in
386     detail::vector_buffer<Vector, Class_, Args...>(cl);
388     cl.def(init<>());
390     // Register copy constructor (if possible)
391     detail::vector_if_copy_constructible<Vector, Class_>(cl);
393     // Register comparison-related operators and functions (if possible)
394     detail::vector_if_equal_operator<Vector, Class_>(cl);
396     // Register stream insertion operator (if possible)
397     detail::vector_if_insertion_operator<Vector, Class_>(cl, name);
399     // Modifiers require copyable vector value type
400     detail::vector_modifiers<Vector, Class_>(cl);
402     // Accessor and iterator; return by value if copyable, otherwise we return by ref + keep-alive
403     detail::vector_accessor<Vector, Class_>(cl);
405     cl.def("__bool__",
406         [](const Vector &v) -> bool {
407             return !v.empty();
408         },
409         "Check whether the list is nonempty"
410     );
412     cl.def("__len__", &Vector::size);
417 #if 0
418     // C++ style functions deprecated, leaving it here as an example
419     cl.def(init<size_type>());
421     cl.def("resize",
422          (void (Vector::*) (size_type count)) & Vector::resize,
423          "changes the number of elements stored");
425     cl.def("erase",
426         [](Vector &v, SizeType i) {
427         if (i >= v.size())
428             throw index_error();
429         v.erase(v.begin() + i);
430     }, "erases element at index ``i``");
432     cl.def("empty",         &Vector::empty,         "checks whether the container is empty");
433     cl.def("size",          &Vector::size,          "returns the number of elements");
434     cl.def("push_back", (void (Vector::*)(const T&)) &Vector::push_back, "adds an element to the end");
435     cl.def("pop_back",                               &Vector::pop_back, "removes the last element");
437     cl.def("max_size",      &Vector::max_size,      "returns the maximum possible number of elements");
438     cl.def("reserve",       &Vector::reserve,       "reserves storage");
439     cl.def("capacity",      &Vector::capacity,      "returns the number of elements that can be held in currently allocated storage");
440     cl.def("shrink_to_fit", &Vector::shrink_to_fit, "reduces memory usage by freeing unused memory");
442     cl.def("clear", &Vector::clear, "clears the contents");
443     cl.def("swap",   &Vector::swap, "swaps the contents");
445     cl.def("front", [](Vector &v) {
446         if (v.size()) return v.front();
447         else throw index_error();
448     }, "access the first element");
450     cl.def("back", [](Vector &v) {
451         if (v.size()) return v.back();
452         else throw index_error();
453     }, "access the last element ");
455 #endif
457     return cl;
462 //
463 // std::map, std::unordered_map
464 //
466 NAMESPACE_BEGIN(detail)
468 /* Fallback functions */
469 template <typename, typename, typename... Args> void map_if_insertion_operator(const Args &...) { }
470 template <typename, typename, typename... Args> void map_assignment(const Args &...) { }
472 // Map assignment when copy-assignable: just copy the value
473 template <typename Map, typename Class_>
474 void map_assignment(enable_if_t<std::is_copy_assignable<typename Map::mapped_type>::value, Class_> &cl) {
475     using KeyType = typename Map::key_type;
476     using MappedType = typename Map::mapped_type;
478     cl.def("__setitem__",
479            [](Map &m, const KeyType &k, const MappedType &v) {
480                auto it = m.find(k);
481                if (it != m.end()) it->second = v;
482                else m.emplace(k, v);
483            }
484     );
487 // Not copy-assignable, but still copy-constructible: we can update the value by erasing and reinserting
488 template<typename Map, typename Class_>
489 void map_assignment(enable_if_t<
490         !std::is_copy_assignable<typename Map::mapped_type>::value &&
491         is_copy_constructible<typename Map::mapped_type>::value,
492         Class_> &cl) {
493     using KeyType = typename Map::key_type;
494     using MappedType = typename Map::mapped_type;
496     cl.def("__setitem__",
497            [](Map &m, const KeyType &k, const MappedType &v) {
498                // We can't use m[k] = v; because value type might not be default constructable
499                auto r = m.emplace(k, v);
500                if (!r.second) {
501                    // value type is not copy assignable so the only way to insert it is to erase it first...
502                    m.erase(r.first);
503                    m.emplace(k, v);
504                }
505            }
506     );
510 template <typename Map, typename Class_> auto map_if_insertion_operator(Class_ &cl, std::string const &name)
511 -> decltype(std::declval<std::ostream&>() << std::declval<typename Map::key_type>() << std::declval<typename Map::mapped_type>(), void()) {
513     cl.def("__repr__",
514            [name](Map &m) {
515             std::ostringstream s;
516             s << name << '{';
517             bool f = false;
518             for (auto const &kv : m) {
519                 if (f)
520                     s << ", ";
521                 s << kv.first << ": " << kv.second;
522                 f = true;
523             }
524             s << '}';
525             return s.str();
526         },
527         "Return the canonical string representation of this map."
528     );
532 NAMESPACE_END(detail)
534 template <typename Map, typename holder_type = std::unique_ptr<Map>, typename... Args>
535 class_<Map, holder_type> bind_map(handle scope, const std::string &name, Args&&... args) {
536     using KeyType = typename Map::key_type;
537     using MappedType = typename Map::mapped_type;
538     using Class_ = class_<Map, holder_type>;
540     // If either type is a non-module-local bound type then make the map binding non-local as well;
541     // otherwise (e.g. both types are either module-local or converting) the map will be
542     // module-local.
543     auto tinfo = detail::get_type_info(typeid(MappedType));
544     bool local = !tinfo || tinfo->module_local;
545     if (local) {
546         tinfo = detail::get_type_info(typeid(KeyType));
547         local = !tinfo || tinfo->module_local;
548     }
550     Class_ cl(scope, name.c_str(), pybind11::module_local(local), std::forward<Args>(args)...);
552     cl.def(init<>());
554     // Register stream insertion operator (if possible)
555     detail::map_if_insertion_operator<Map, Class_>(cl, name);
557     cl.def("__bool__",
558         [](const Map &m) -> bool { return !m.empty(); },
559         "Check whether the map is nonempty"
560     );
562     cl.def("__iter__",
563            [](Map &m) { return make_key_iterator(m.begin(), m.end()); },
564            keep_alive<0, 1>() /* Essential: keep list alive while iterator exists */
565     );
567     cl.def("items",
568            [](Map &m) { return make_iterator(m.begin(), m.end()); },
569            keep_alive<0, 1>() /* Essential: keep list alive while iterator exists */
570     );
572     cl.def("__getitem__",
573         [](Map &m, const KeyType &k) -> MappedType & {
574             auto it = m.find(k);
575             if (it == m.end())
576               throw key_error();
577            return it->second;
578         },
579         return_value_policy::reference_internal // ref + keepalive
580     );
582     // Assignment provided only if the type is copyable
583     detail::map_assignment<Map, Class_>(cl);
585     cl.def("__delitem__",
586            [](Map &m, const KeyType &k) {
587                auto it = m.find(k);
588                if (it == m.end())
589                    throw key_error();
590                m.erase(it);
591            }
592     );
594     cl.def("__len__", &Map::size);
596     return cl;
599 NAMESPACE_END(PYBIND11_NAMESPACE)