stl_bind.h revision 12391:ceeca8b41e4b
1/* 2 pybind11/std_bind.h: Binding generators for STL data types 3 4 Copyright (c) 2016 Sergey Lyskov and Wenzel Jakob 5 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*/ 9 10#pragma once 11 12#include "detail/common.h" 13#include "operators.h" 14 15#include <algorithm> 16#include <sstream> 17 18NAMESPACE_BEGIN(PYBIND11_NAMESPACE) 19NAMESPACE_BEGIN(detail) 20 21/* SFINAE helper class used by 'is_comparable */ 22template <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(...); 29 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}; 35 36/* Default: is_comparable -> std::false_type */ 37template <typename T, typename SFINAE = void> 38struct is_comparable : std::false_type { }; 39 40/* For non-map data structures, check whether operator== can be instantiated */ 41template <typename T> 42struct is_comparable< 43 T, enable_if_t<container_traits<T>::is_element && 44 container_traits<T>::is_comparable>> 45 : std::true_type { }; 46 47/* For a vector/map data structure, recursively check the value type (which is std::pair for maps) */ 48template <typename T> 49struct 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}; 53 54/* For pairs, recursively check the two data types */ 55template <typename T> 56struct 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}; 61 62/* Fallback functions */ 63template <typename, typename, typename... Args> void vector_if_copy_constructible(const Args &...) { } 64template <typename, typename, typename... Args> void vector_if_equal_operator(const Args &...) { } 65template <typename, typename, typename... Args> void vector_if_insertion_operator(const Args &...) { } 66template <typename, typename, typename... Args> void vector_modifiers(const Args &...) { } 67 68template<typename Vector, typename Class_> 69void vector_if_copy_constructible(enable_if_t<is_copy_constructible<Vector>::value, Class_> &cl) { 70 cl.def(init<const Vector &>(), "Copy constructor"); 71} 72 73template<typename Vector, typename Class_> 74void vector_if_equal_operator(enable_if_t<is_comparable<Vector>::value, Class_> &cl) { 75 using T = typename Vector::value_type; 76 77 cl.def(self == self); 78 cl.def(self != self); 79 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 ); 87 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 ); 99 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} 108 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.) 112template <typename Vector, typename Class_> 113void 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; 117 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"); 122 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 })); 130 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 ); 138 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 ); 148 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 ); 159 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 ); 171 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 ); 179 180 /// Slicing protocol 181 cl.def("__getitem__", 182 [](const Vector &v, slice slice) -> Vector * { 183 size_t start, stop, step, slicelength; 184 185 if (!slice.compute(v.size(), &start, &stop, &step, &slicelength)) 186 throw error_already_set(); 187 188 Vector *seq = new Vector(); 189 seq->reserve((size_t) slicelength); 190 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 ); 200 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(); 206 207 if (slicelength != value.size()) 208 throw std::runtime_error("Left and right hand size of slice assignment have different sizes!"); 209 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 ); 217 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 ); 226 227 cl.def("__delitem__", 228 [](Vector &v, slice slice) { 229 size_t start, stop, step, slicelength; 230 231 if (!slice.compute(v.size(), &start, &stop, &step, &slicelength)) 232 throw error_already_set(); 233 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 ); 245 246} 247 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. 250template <typename Vector> using vector_needs_copy = negation< 251 std::is_same<decltype(std::declval<Vector>()[typename Vector::size_type()]), typename Vector::value_type &>>; 252 253// The usual case: access and iterate by reference 254template <typename Vector, typename Class_> 255void 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; 259 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 ); 268 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} 278 279// The case for special objects, like std::vector<bool>, that have to be returned-by-copy: 280template <typename Vector, typename Class_> 281void 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 ); 292 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} 302 303template <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; 306 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} 322 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 325template <typename Vector, typename = void> 326struct vector_has_data_and_format : std::false_type {}; 327template <typename Vector> 328struct 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 {}; 329 330// Add the buffer interface to a vector 331template <typename Vector, typename Class_, typename... Args> 332enable_if_t<detail::any_of<std::is_same<Args, buffer_protocol>...>::value> 333vector_buffer(Class_& cl) { 334 using T = typename Vector::value_type; 335 336 static_assert(vector_has_data_and_format<Vector>::value, "There is not an appropriate format descriptor for this vector"); 337 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(); 340 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 }); 344 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() + ")"); 351 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 })); 361 362 return; 363} 364 365template <typename Vector, typename Class_, typename... Args> 366enable_if_t<!detail::any_of<std::is_same<Args, buffer_protocol>...>::value> vector_buffer(Class_&) {} 367 368NAMESPACE_END(detail) 369 370// 371// std::vector 372// 373template <typename Vector, typename holder_type = std::unique_ptr<Vector>, typename... Args> 374class_<Vector, holder_type> bind_vector(handle scope, std::string const &name, Args&&... args) { 375 using Class_ = class_<Vector, holder_type>; 376 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; 382 383 Class_ cl(scope, name.c_str(), pybind11::module_local(local), std::forward<Args>(args)...); 384 385 // Declare the buffer interface if a buffer_protocol() is passed in 386 detail::vector_buffer<Vector, Class_, Args...>(cl); 387 388 cl.def(init<>()); 389 390 // Register copy constructor (if possible) 391 detail::vector_if_copy_constructible<Vector, Class_>(cl); 392 393 // Register comparison-related operators and functions (if possible) 394 detail::vector_if_equal_operator<Vector, Class_>(cl); 395 396 // Register stream insertion operator (if possible) 397 detail::vector_if_insertion_operator<Vector, Class_>(cl, name); 398 399 // Modifiers require copyable vector value type 400 detail::vector_modifiers<Vector, Class_>(cl); 401 402 // Accessor and iterator; return by value if copyable, otherwise we return by ref + keep-alive 403 detail::vector_accessor<Vector, Class_>(cl); 404 405 cl.def("__bool__", 406 [](const Vector &v) -> bool { 407 return !v.empty(); 408 }, 409 "Check whether the list is nonempty" 410 ); 411 412 cl.def("__len__", &Vector::size); 413 414 415 416 417#if 0 418 // C++ style functions deprecated, leaving it here as an example 419 cl.def(init<size_type>()); 420 421 cl.def("resize", 422 (void (Vector::*) (size_type count)) & Vector::resize, 423 "changes the number of elements stored"); 424 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``"); 431 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"); 436 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"); 441 442 cl.def("clear", &Vector::clear, "clears the contents"); 443 cl.def("swap", &Vector::swap, "swaps the contents"); 444 445 cl.def("front", [](Vector &v) { 446 if (v.size()) return v.front(); 447 else throw index_error(); 448 }, "access the first element"); 449 450 cl.def("back", [](Vector &v) { 451 if (v.size()) return v.back(); 452 else throw index_error(); 453 }, "access the last element "); 454 455#endif 456 457 return cl; 458} 459 460 461 462// 463// std::map, std::unordered_map 464// 465 466NAMESPACE_BEGIN(detail) 467 468/* Fallback functions */ 469template <typename, typename, typename... Args> void map_if_insertion_operator(const Args &...) { } 470template <typename, typename, typename... Args> void map_assignment(const Args &...) { } 471 472// Map assignment when copy-assignable: just copy the value 473template <typename Map, typename Class_> 474void 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; 477 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} 486 487// Not copy-assignable, but still copy-constructible: we can update the value by erasing and reinserting 488template<typename Map, typename Class_> 489void 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; 495 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} 508 509 510template <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()) { 512 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} 530 531 532NAMESPACE_END(detail) 533 534template <typename Map, typename holder_type = std::unique_ptr<Map>, typename... Args> 535class_<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>; 539 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 } 549 550 Class_ cl(scope, name.c_str(), pybind11::module_local(local), std::forward<Args>(args)...); 551 552 cl.def(init<>()); 553 554 // Register stream insertion operator (if possible) 555 detail::map_if_insertion_operator<Map, Class_>(cl, name); 556 557 cl.def("__bool__", 558 [](const Map &m) -> bool { return !m.empty(); }, 559 "Check whether the map is nonempty" 560 ); 561 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 ); 566 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 ); 571 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 ); 581 582 // Assignment provided only if the type is copyable 583 detail::map_assignment<Map, Class_>(cl); 584 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 return m.erase(it); 591 } 592 ); 593 594 cl.def("__len__", &Map::size); 595 596 return cl; 597} 598 599NAMESPACE_END(PYBIND11_NAMESPACE) 600