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