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 );
107 }
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 );
246 }
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 );
277 }
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 );
301 }
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 );
321 }
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;
363 }
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;
458 }
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 );
485 }
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 );
507 }
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 );
529 }
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;
597 }
599 NAMESPACE_END(PYBIND11_NAMESPACE)