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