1/*
2 pybind11/stl.h: Transparent conversion for STL data types
3
4 Copyright (c) 2016 Wenzel Jakob <[email protected]>
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 "pybind11.h"
13#include "detail/common.h"
14
15#include <deque>
16#include <list>
17#include <map>
18#include <ostream>
19#include <set>
20#include <unordered_map>
21#include <unordered_set>
22#include <valarray>
23
24// See `detail/common.h` for implementation of these guards.
25#if defined(PYBIND11_HAS_OPTIONAL)
26# include <optional>
27#elif defined(PYBIND11_HAS_EXP_OPTIONAL)
28# include <experimental/optional>
29#endif
30
31#if defined(PYBIND11_HAS_VARIANT)
32# include <variant>
33#endif
34
35PYBIND11_NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
36PYBIND11_NAMESPACE_BEGIN(detail)
37
38/// Extracts an const lvalue reference or rvalue reference for U based on the type of T (e.g. for
39/// forwarding a container element). Typically used indirect via forwarded_type(), below.
40template <typename T, typename U>
41using forwarded_type = conditional_t<std::is_lvalue_reference<T>::value,
42 remove_reference_t<U> &,
43 remove_reference_t<U> &&>;
44
45/// Forwards a value U as rvalue or lvalue according to whether T is rvalue or lvalue; typically
46/// used for forwarding a container's elements.
47template <typename T, typename U>
48constexpr forwarded_type<T, U> forward_like(U &&u) {
49 return std::forward<detail::forwarded_type<T, U>>(std::forward<U>(u));
50}
51
52// Checks if a container has a STL style reserve method.
53// This will only return true for a `reserve()` with a `void` return.
54template <typename C>
55using has_reserve_method = std::is_same<decltype(std::declval<C>().reserve(0)), void>;
56
57template <typename Type, typename Key>
58struct set_caster {
59 using type = Type;
60 using key_conv = make_caster<Key>;
61
62private:
63 template <typename T = Type, enable_if_t<has_reserve_method<T>::value, int> = 0>
64 void reserve_maybe(const anyset &s, Type *) {
65 value.reserve(s.size());
66 }
67 void reserve_maybe(const anyset &, void *) {}
68
69public:
70 bool load(handle src, bool convert) {
71 if (!isinstance<anyset>(src)) {
72 return false;
73 }
74 auto s = reinterpret_borrow<anyset>(src);
75 value.clear();
76 reserve_maybe(s, &value);
77 for (auto entry : s) {
78 key_conv conv;
79 if (!conv.load(entry, convert)) {
80 return false;
81 }
82 value.insert(cast_op<Key &&>(std::move(conv)));
83 }
84 return true;
85 }
86
87 template <typename T>
88 static handle cast(T &&src, return_value_policy policy, handle parent) {
89 if (!std::is_lvalue_reference<T>::value) {
90 policy = return_value_policy_override<Key>::policy(policy);
91 }
92 pybind11::set s;
93 for (auto &&value : src) {
94 auto value_ = reinterpret_steal<object>(
95 key_conv::cast(detail::forward_like<T>(value), policy, parent));
96 if (!value_ || !s.add(std::move(value_))) {
97 return handle();
98 }
99 }
100 return s.release();
101 }
102
103 PYBIND11_TYPE_CASTER(type, const_name("Set[") + key_conv::name + const_name("]"));
104};
105
106template <typename Type, typename Key, typename Value>
107struct map_caster {
108 using key_conv = make_caster<Key>;
109 using value_conv = make_caster<Value>;
110
111private:
112 template <typename T = Type, enable_if_t<has_reserve_method<T>::value, int> = 0>
113 void reserve_maybe(const dict &d, Type *) {
114 value.reserve(d.size());
115 }
116 void reserve_maybe(const dict &, void *) {}
117
118public:
119 bool load(handle src, bool convert) {
120 if (!isinstance<dict>(src)) {
121 return false;
122 }
123 auto d = reinterpret_borrow<dict>(src);
124 value.clear();
125 reserve_maybe(d, &value);
126 for (auto it : d) {
127 key_conv kconv;
128 value_conv vconv;
129 if (!kconv.load(it.first.ptr(), convert) || !vconv.load(it.second.ptr(), convert)) {
130 return false;
131 }
132 value.emplace(cast_op<Key &&>(std::move(kconv)), cast_op<Value &&>(std::move(vconv)));
133 }
134 return true;
135 }
136
137 template <typename T>
138 static handle cast(T &&src, return_value_policy policy, handle parent) {
139 dict d;
140 return_value_policy policy_key = policy;
141 return_value_policy policy_value = policy;
142 if (!std::is_lvalue_reference<T>::value) {
143 policy_key = return_value_policy_override<Key>::policy(policy_key);
144 policy_value = return_value_policy_override<Value>::policy(policy_value);
145 }
146 for (auto &&kv : src) {
147 auto key = reinterpret_steal<object>(
148 key_conv::cast(detail::forward_like<T>(kv.first), policy_key, parent));
149 auto value = reinterpret_steal<object>(
150 value_conv::cast(detail::forward_like<T>(kv.second), policy_value, parent));
151 if (!key || !value) {
152 return handle();
153 }
154 d[std::move(key)] = std::move(value);
155 }
156 return d.release();
157 }
158
159 PYBIND11_TYPE_CASTER(Type,
160 const_name("Dict[") + key_conv::name + const_name(", ") + value_conv::name
161 + const_name("]"));
162};
163
164template <typename Type, typename Value>
165struct list_caster {
166 using value_conv = make_caster<Value>;
167
168 bool load(handle src, bool convert) {
169 if (!isinstance<sequence>(src) || isinstance<bytes>(src) || isinstance<str>(src)) {
170 return false;
171 }
172 auto s = reinterpret_borrow<sequence>(src);
173 value.clear();
174 reserve_maybe(s, &value);
175 for (auto it : s) {
176 value_conv conv;
177 if (!conv.load(it, convert)) {
178 return false;
179 }
180 value.push_back(cast_op<Value &&>(std::move(conv)));
181 }
182 return true;
183 }
184
185private:
186 template <typename T = Type, enable_if_t<has_reserve_method<T>::value, int> = 0>
187 void reserve_maybe(const sequence &s, Type *) {
188 value.reserve(s.size());
189 }
190 void reserve_maybe(const sequence &, void *) {}
191
192public:
193 template <typename T>
194 static handle cast(T &&src, return_value_policy policy, handle parent) {
195 if (!std::is_lvalue_reference<T>::value) {
196 policy = return_value_policy_override<Value>::policy(policy);
197 }
198 list l(src.size());
199 ssize_t index = 0;
200 for (auto &&value : src) {
201 auto value_ = reinterpret_steal<object>(
202 value_conv::cast(detail::forward_like<T>(value), policy, parent));
203 if (!value_) {
204 return handle();
205 }
206 PyList_SET_ITEM(l.ptr(), index++, value_.release().ptr()); // steals a reference
207 }
208 return l.release();
209 }
210
211 PYBIND11_TYPE_CASTER(Type, const_name("List[") + value_conv::name + const_name("]"));
212};
213
214template <typename Type, typename Alloc>
215struct type_caster<std::vector<Type, Alloc>> : list_caster<std::vector<Type, Alloc>, Type> {};
216
217template <typename Type, typename Alloc>
218struct type_caster<std::deque<Type, Alloc>> : list_caster<std::deque<Type, Alloc>, Type> {};
219
220template <typename Type, typename Alloc>
221struct type_caster<std::list<Type, Alloc>> : list_caster<std::list<Type, Alloc>, Type> {};
222
223template <typename ArrayType, typename Value, bool Resizable, size_t Size = 0>
224struct array_caster {
225 using value_conv = make_caster<Value>;
226
227private:
228 template <bool R = Resizable>
229 bool require_size(enable_if_t<R, size_t> size) {
230 if (value.size() != size) {
231 value.resize(size);
232 }
233 return true;
234 }
235 template <bool R = Resizable>
236 bool require_size(enable_if_t<!R, size_t> size) {
237 return size == Size;
238 }
239
240public:
241 bool load(handle src, bool convert) {
242 if (!isinstance<sequence>(src)) {
243 return false;
244 }
245 auto l = reinterpret_borrow<sequence>(src);
246 if (!require_size(l.size())) {
247 return false;
248 }
249 size_t ctr = 0;
250 for (auto it : l) {
251 value_conv conv;
252 if (!conv.load(it, convert)) {
253 return false;
254 }
255 value[ctr++] = cast_op<Value &&>(std::move(conv));
256 }
257 return true;
258 }
259
260 template <typename T>
261 static handle cast(T &&src, return_value_policy policy, handle parent) {
262 list l(src.size());
263 ssize_t index = 0;
264 for (auto &&value : src) {
265 auto value_ = reinterpret_steal<object>(
266 value_conv::cast(detail::forward_like<T>(value), policy, parent));
267 if (!value_) {
268 return handle();
269 }
270 PyList_SET_ITEM(l.ptr(), index++, value_.release().ptr()); // steals a reference
271 }
272 return l.release();
273 }
274
275 PYBIND11_TYPE_CASTER(ArrayType,
276 const_name("List[") + value_conv::name
277 + const_name<Resizable>(const_name(""),
278 const_name("[") + const_name<Size>()
279 + const_name("]"))
280 + const_name("]"));
281};
282
283template <typename Type, size_t Size>
284struct type_caster<std::array<Type, Size>>
285 : array_caster<std::array<Type, Size>, Type, false, Size> {};
286
287template <typename Type>
288struct type_caster<std::valarray<Type>> : array_caster<std::valarray<Type>, Type, true> {};
289
290template <typename Key, typename Compare, typename Alloc>
291struct type_caster<std::set<Key, Compare, Alloc>>
292 : set_caster<std::set<Key, Compare, Alloc>, Key> {};
293
294template <typename Key, typename Hash, typename Equal, typename Alloc>
295struct type_caster<std::unordered_set<Key, Hash, Equal, Alloc>>
296 : set_caster<std::unordered_set<Key, Hash, Equal, Alloc>, Key> {};
297
298template <typename Key, typename Value, typename Compare, typename Alloc>
299struct type_caster<std::map<Key, Value, Compare, Alloc>>
300 : map_caster<std::map<Key, Value, Compare, Alloc>, Key, Value> {};
301
302template <typename Key, typename Value, typename Hash, typename Equal, typename Alloc>
303struct type_caster<std::unordered_map<Key, Value, Hash, Equal, Alloc>>
304 : map_caster<std::unordered_map<Key, Value, Hash, Equal, Alloc>, Key, Value> {};
305
306// This type caster is intended to be used for std::optional and std::experimental::optional
307template <typename Type, typename Value = typename Type::value_type>
308struct optional_caster {
309 using value_conv = make_caster<Value>;
310
311 template <typename T>
312 static handle cast(T &&src, return_value_policy policy, handle parent) {
313 if (!src) {
314 return none().release();
315 }
316 if (!std::is_lvalue_reference<T>::value) {
317 policy = return_value_policy_override<Value>::policy(policy);
318 }
319 return value_conv::cast(*std::forward<T>(src), policy, parent);
320 }
321
322 bool load(handle src, bool convert) {
323 if (!src) {
324 return false;
325 }
326 if (src.is_none()) {
327 return true; // default-constructed value is already empty
328 }
329 value_conv inner_caster;
330 if (!inner_caster.load(src, convert)) {
331 return false;
332 }
333
334 value.emplace(cast_op<Value &&>(std::move(inner_caster)));
335 return true;
336 }
337
338 PYBIND11_TYPE_CASTER(Type, const_name("Optional[") + value_conv::name + const_name("]"));
339};
340
341#if defined(PYBIND11_HAS_OPTIONAL)
342template <typename T>
343struct type_caster<std::optional<T>> : public optional_caster<std::optional<T>> {};
344
345template <>
346struct type_caster<std::nullopt_t> : public void_caster<std::nullopt_t> {};
347#endif
348
349#if defined(PYBIND11_HAS_EXP_OPTIONAL)
350template <typename T>
351struct type_caster<std::experimental::optional<T>>
352 : public optional_caster<std::experimental::optional<T>> {};
353
354template <>
355struct type_caster<std::experimental::nullopt_t>
356 : public void_caster<std::experimental::nullopt_t> {};
357#endif
358
359/// Visit a variant and cast any found type to Python
360struct variant_caster_visitor {
361 return_value_policy policy;
362 handle parent;
363
364 using result_type = handle; // required by boost::variant in C++11
365
366 template <typename T>
367 result_type operator()(T &&src) const {
368 return make_caster<T>::cast(std::forward<T>(src), policy, parent);
369 }
370};
371
372/// Helper class which abstracts away variant's `visit` function. `std::variant` and similar
373/// `namespace::variant` types which provide a `namespace::visit()` function are handled here
374/// automatically using argument-dependent lookup. Users can provide specializations for other
375/// variant-like classes, e.g. `boost::variant` and `boost::apply_visitor`.
376template <template <typename...> class Variant>
377struct visit_helper {
378 template <typename... Args>
379 static auto call(Args &&...args) -> decltype(visit(std::forward<Args>(args)...)) {
380 return visit(std::forward<Args>(args)...);
381 }
382};
383
384/// Generic variant caster
385template <typename Variant>
386struct variant_caster;
387
388template <template <typename...> class V, typename... Ts>
389struct variant_caster<V<Ts...>> {
390 static_assert(sizeof...(Ts) > 0, "Variant must consist of at least one alternative.");
391
392 template <typename U, typename... Us>
393 bool load_alternative(handle src, bool convert, type_list<U, Us...>) {
394 auto caster = make_caster<U>();
395 if (caster.load(src, convert)) {
396 value = cast_op<U>(std::move(caster));
397 return true;
398 }
399 return load_alternative(src, convert, type_list<Us...>{});
400 }
401
402 bool load_alternative(handle, bool, type_list<>) { return false; }
403
404 bool load(handle src, bool convert) {
405 // Do a first pass without conversions to improve constructor resolution.
406 // E.g. `py::int_(1).cast<variant<double, int>>()` needs to fill the `int`
407 // slot of the variant. Without two-pass loading `double` would be filled
408 // because it appears first and a conversion is possible.
409 if (convert && load_alternative(src, false, type_list<Ts...>{})) {
410 return true;
411 }
412 return load_alternative(src, convert, type_list<Ts...>{});
413 }
414
415 template <typename Variant>
416 static handle cast(Variant &&src, return_value_policy policy, handle parent) {
417 return visit_helper<V>::call(variant_caster_visitor{policy, parent},
418 std::forward<Variant>(src));
419 }
420
421 using Type = V<Ts...>;
422 PYBIND11_TYPE_CASTER(Type,
423 const_name("Union[") + detail::concat(make_caster<Ts>::name...)
424 + const_name("]"));
425};
426
427#if defined(PYBIND11_HAS_VARIANT)
428template <typename... Ts>
429struct type_caster<std::variant<Ts...>> : variant_caster<std::variant<Ts...>> {};
430
431template <>
432struct type_caster<std::monostate> : public void_caster<std::monostate> {};
433#endif
434
435PYBIND11_NAMESPACE_END(detail)
436
437inline std::ostream &operator<<(std::ostream &os, const handle &obj) {
438#ifdef PYBIND11_HAS_STRING_VIEW
439 os << str(obj).cast<std::string_view>();
440#else
441 os << (std::string) str(obj);
442#endif
443 return os;
444}
445
446PYBIND11_NAMESPACE_END(PYBIND11_NAMESPACE)
447