Separate optional and variant support from other STL containers (#1207)

CMakeLists.txt

@@ -64,6 +64,7 @@ set(PYBIND11_HEADERS
   include/pybind11/pytypes.h
   include/pybind11/stl.h
   include/pybind11/stl_bind.h
+  include/pybind11/utility.h
 )
 string(REPLACE "include/" "${CMAKE_CURRENT_SOURCE_DIR}/include/"
        PYBIND11_HEADERS "${PYBIND11_HEADERS}")

docs/advanced/cast/overview.rst

@@ -143,11 +143,11 @@ as arguments and return values, refer to the section on binding :ref:`classes`.
 +------------------------------------+---------------------------+-------------------------------+
 | ``std::unordered_set<T>``          | STL unordered set         | :file:`pybind11/stl.h`        |
 +------------------------------------+---------------------------+-------------------------------+
-| ``std::optional<T>``               | STL optional type (C++17) | :file:`pybind11/stl.h`        |
+| ``std::optional<T>``               | STL optional type (C++17) | :file:`pybind11/utility.h`    |
 +------------------------------------+---------------------------+-------------------------------+
-| ``std::experimental::optional<T>`` | STL optional type (exp.)  | :file:`pybind11/stl.h`        |
+| ``std::experimental::optional<T>`` | STL optional type (exp.)  | :file:`pybind11/utility.h`    |
 +------------------------------------+---------------------------+-------------------------------+
-| ``std::variant<...>``              | Type-safe union (C++17)   | :file:`pybind11/stl.h`        |
+| ``std::variant<...>``              | Type-safe union (C++17)   | :file:`pybind11/utility.h`    |
 +------------------------------------+---------------------------+-------------------------------+
 | ``std::function<...>``             | STL polymorphic function  | :file:`pybind11/functional.h` |
 +------------------------------------+---------------------------+-------------------------------+

docs/advanced/cast/stl.rst

@@ -31,10 +31,15 @@ next sections for more details and alternative approaches that avoid this.
 C++17 library containers
 ========================
 
-The :file:`pybind11/stl.h` header also includes support for ``std::optional<>``
+The :file:`pybind11/utility.h` header includes support for ``std::optional<>``
 and ``std::variant<>``. These require a C++17 compiler and standard library.
 In C++14 mode, ``std::experimental::optional<>`` is supported if available.
 
+.. note::
+
+    These features are also enabled by the header file :file:`pybind11/stl.h`
+    for backward compatibility.
+
 Various versions of these containers also exist for C++11 (e.g. in Boost).
 pybind11 provides an easy way to specialize the ``type_caster`` for such
 types:

docs/changelog.rst

@@ -21,6 +21,11 @@ v2.3.0 (Not yet released)
 * The ``value()``  method of ``py::enum_`` now accepts an optional docstring
   that will be shown in the documentation of the associated enumeration.
 
+* Added ``pybind11/utility.h``, which enables support for STL utility types
+  (``std::optional`` and ``std::variant``) separately from STL containers.
+  ``pybind11/stl.h`` enables both.
+  `#1207 <https://github.com/pybind/pybind11/issues/1207>`_.
+
 v2.2.1 (September 14, 2017)
 -----------------------------------------------------
 

include/pybind11/pybind11.h

@@ -687,9 +687,9 @@ class cpp_function : public function {
             if (msg.find("std::") != std::string::npos) {
                 msg += "\n\n"
                        "Did you forget to `#include <pybind11/stl.h>`? Or <pybind11/complex.h>,\n"
-                       "<pybind11/functional.h>, <pybind11/chrono.h>, etc. Some automatic\n"
-                       "conversions are optional and require extra headers to be included\n"
-                       "when compiling your pybind11 module.";
+                       "<pybind11/functional.h>, <pybind11/chrono.h>, <pybind11/utility.h>, etc.\n"
+                       "Some automatic conversions are optional and require extra headers to be\n"
+                       "included when compiling your pybind11 module.";
             }
         };
 

include/pybind11/stl.h

@@ -10,6 +10,7 @@
 #pragma once
 
 #include "pybind11.h"
+#include "utility.h"
 #include <set>
 #include <unordered_set>
 #include <map>
@@ -23,29 +24,6 @@
 #pragma warning(disable: 4127) // warning C4127: Conditional expression is constant
 #endif
 
-#ifdef __has_include
-// std::optional (but including it in c++14 mode isn't allowed)
-#  if defined(PYBIND11_CPP17) && __has_include(<optional>)
-#    include <optional>
-#    define PYBIND11_HAS_OPTIONAL 1
-#  endif
-// std::experimental::optional (but not allowed in c++11 mode)
-#  if defined(PYBIND11_CPP14) && __has_include(<experimental/optional>)
-#    include <experimental/optional>
-#    define PYBIND11_HAS_EXP_OPTIONAL 1
-#  endif
-// std::variant
-#  if defined(PYBIND11_CPP17) && __has_include(<variant>)
-#    include <variant>
-#    define PYBIND11_HAS_VARIANT 1
-#  endif
-#elif defined(_MSC_VER) && defined(PYBIND11_CPP17)
-#  include <optional>
-#  include <variant>
-#  define PYBIND11_HAS_OPTIONAL 1
-#  define PYBIND11_HAS_VARIANT 1
-#endif
-
 NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
 NAMESPACE_BEGIN(detail)
 
@@ -243,118 +221,6 @@ template <typename Key, typename Value, typename Compare, typename Alloc> struct
 template <typename Key, typename Value, typename Hash, typename Equal, typename Alloc> struct type_caster<std::unordered_map<Key, Value, Hash, Equal, Alloc>>
   : map_caster<std::unordered_map<Key, Value, Hash, Equal, Alloc>, Key, Value> { };
 
-// This type caster is intended to be used for std::optional and std::experimental::optional
-template<typename T> struct optional_caster {
-    using value_conv = make_caster<typename T::value_type>;
-
-    template <typename T_>
-    static handle cast(T_ &&src, return_value_policy policy, handle parent) {
-        if (!src)
-            return none().inc_ref();
-        return value_conv::cast(*std::forward<T_>(src), policy, parent);
-    }
-
-    bool load(handle src, bool convert) {
-        if (!src) {
-            return false;
-        } else if (src.is_none()) {
-            return true;  // default-constructed value is already empty
-        }
-        value_conv inner_caster;
-        if (!inner_caster.load(src, convert))
-            return false;
-
-        value.emplace(cast_op<typename T::value_type &&>(std::move(inner_caster)));
-        return true;
-    }
-
-    PYBIND11_TYPE_CASTER(T, _("Optional[") + value_conv::name + _("]"));
-};
-
-#if PYBIND11_HAS_OPTIONAL
-template<typename T> struct type_caster<std::optional<T>>
-    : public optional_caster<std::optional<T>> {};
-
-template<> struct type_caster<std::nullopt_t>
-    : public void_caster<std::nullopt_t> {};
-#endif
-
-#if PYBIND11_HAS_EXP_OPTIONAL
-template<typename T> struct type_caster<std::experimental::optional<T>>
-    : public optional_caster<std::experimental::optional<T>> {};
-
-template<> struct type_caster<std::experimental::nullopt_t>
-    : public void_caster<std::experimental::nullopt_t> {};
-#endif
-
-/// Visit a variant and cast any found type to Python
-struct variant_caster_visitor {
-    return_value_policy policy;
-    handle parent;
-
-    using result_type = handle; // required by boost::variant in C++11
-
-    template <typename T>
-    result_type operator()(T &&src) const {
-        return make_caster<T>::cast(std::forward<T>(src), policy, parent);
-    }
-};
-
-/// Helper class which abstracts away variant's `visit` function. `std::variant` and similar
-/// `namespace::variant` types which provide a `namespace::visit()` function are handled here
-/// automatically using argument-dependent lookup. Users can provide specializations for other
-/// variant-like classes, e.g. `boost::variant` and `boost::apply_visitor`.
-template <template<typename...> class Variant>
-struct visit_helper {
-    template <typename... Args>
-    static auto call(Args &&...args) -> decltype(visit(std::forward<Args>(args)...)) {
-        return visit(std::forward<Args>(args)...);
-    }
-};
-
-/// Generic variant caster
-template <typename Variant> struct variant_caster;
-
-template <template<typename...> class V, typename... Ts>
-struct variant_caster<V<Ts...>> {
-    static_assert(sizeof...(Ts) > 0, "Variant must consist of at least one alternative.");
-
-    template <typename U, typename... Us>
-    bool load_alternative(handle src, bool convert, type_list<U, Us...>) {
-        auto caster = make_caster<U>();
-        if (caster.load(src, convert)) {
-            value = cast_op<U>(caster);
-            return true;
-        }
-        return load_alternative(src, convert, type_list<Us...>{});
-    }
-
-    bool load_alternative(handle, bool, type_list<>) { return false; }
-
-    bool load(handle src, bool convert) {
-        // Do a first pass without conversions to improve constructor resolution.
-        // E.g. `py::int_(1).cast<variant<double, int>>()` needs to fill the `int`
-        // slot of the variant. Without two-pass loading `double` would be filled
-        // because it appears first and a conversion is possible.
-        if (convert && load_alternative(src, false, type_list<Ts...>{}))
-            return true;
-        return load_alternative(src, convert, type_list<Ts...>{});
-    }
-
-    template <typename Variant>
-    static handle cast(Variant &&src, return_value_policy policy, handle parent) {
-        return visit_helper<V>::call(variant_caster_visitor{policy, parent},
-                                     std::forward<Variant>(src));
-    }
-
-    using Type = V<Ts...>;
-    PYBIND11_TYPE_CASTER(Type, _("Union[") + detail::concat(make_caster<Ts>::name...) + _("]"));
-};
-
-#if PYBIND11_HAS_VARIANT
-template <typename... Ts>
-struct type_caster<std::variant<Ts...>> : variant_caster<std::variant<Ts...>> { };
-#endif
 NAMESPACE_END(detail)
 
 inline std::ostream &operator<<(std::ostream &os, const handle &obj) {

include/pybind11/utility.h

@@ -0,0 +1,164 @@
+/*
+    pybind11/utility.h: Support for STL utility types (variant, optional)
+
+    Copyright (c) 2016 Wenzel Jakob <[email protected]>
+
+    All rights reserved. Use of this source code is governed by a
+    BSD-style license that can be found in the LICENSE file.
+*/
+
+#pragma once
+
+#include "pybind11.h"
+
+#if defined(_MSC_VER)
+#pragma warning(push)
+#pragma warning(disable: 4127) // warning C4127: Conditional expression is constant
+#endif
+
+#ifdef __has_include
+// std::optional (but including it in c++14 mode isn't allowed)
+#  if defined(PYBIND11_CPP17) && __has_include(<optional>)
+#    include <optional>
+#    define PYBIND11_HAS_OPTIONAL 1
+#  endif
+// std::experimental::optional (but not allowed in c++11 mode)
+#  if defined(PYBIND11_CPP14) && __has_include(<experimental/optional>)
+#    include <experimental/optional>
+#    define PYBIND11_HAS_EXP_OPTIONAL 1
+#  endif
+// std::variant
+#  if defined(PYBIND11_CPP17) && __has_include(<variant>)
+#    include <variant>
+#    define PYBIND11_HAS_VARIANT 1
+#  endif
+#elif defined(_MSC_VER) && defined(PYBIND11_CPP17)
+#  include <optional>
+#  include <variant>
+#  define PYBIND11_HAS_OPTIONAL 1
+#  define PYBIND11_HAS_VARIANT 1
+#endif
+
+NAMESPACE_BEGIN(PYBIND11_NAMESPACE)
+NAMESPACE_BEGIN(detail)
+
+// This type caster is intended to be used for std::optional and std::experimental::optional
+template<typename T> struct optional_caster {
+    using value_conv = make_caster<typename T::value_type>;
+
+    template <typename T_>
+    static handle cast(T_ &&src, return_value_policy policy, handle parent) {
+        if (!src)
+            return none().inc_ref();
+        return value_conv::cast(*std::forward<T_>(src), policy, parent);
+    }
+
+    bool load(handle src, bool convert) {
+        if (!src) {
+            return false;
+        } else if (src.is_none()) {
+            return true;  // default-constructed value is already empty
+        }
+        value_conv inner_caster;
+        if (!inner_caster.load(src, convert))
+            return false;
+
+        value.emplace(cast_op<typename T::value_type &&>(std::move(inner_caster)));
+        return true;
+    }
+
+    PYBIND11_TYPE_CASTER(T, _("Optional[") + value_conv::name + _("]"));
+};
+
+#if PYBIND11_HAS_OPTIONAL
+template<typename T> struct type_caster<std::optional<T>>
+    : public optional_caster<std::optional<T>> {};
+
+template<> struct type_caster<std::nullopt_t>
+    : public void_caster<std::nullopt_t> {};
+#endif
+
+#if PYBIND11_HAS_EXP_OPTIONAL
+template<typename T> struct type_caster<std::experimental::optional<T>>
+    : public optional_caster<std::experimental::optional<T>> {};
+
+template<> struct type_caster<std::experimental::nullopt_t>
+    : public void_caster<std::experimental::nullopt_t> {};
+#endif
+
+/// Visit a variant and cast any found type to Python
+struct variant_caster_visitor {
+    return_value_policy policy;
+    handle parent;
+
+    using result_type = handle; // required by boost::variant in C++11
+
+    template <typename T>
+    result_type operator()(T &&src) const {
+        return make_caster<T>::cast(std::forward<T>(src), policy, parent);
+    }
+};
+
+/// Helper class which abstracts away variant's `visit` function. `std::variant` and similar
+/// `namespace::variant` types which provide a `namespace::visit()` function are handled here
+/// automatically using argument-dependent lookup. Users can provide specializations for other
+/// variant-like classes, e.g. `boost::variant` and `boost::apply_visitor`.
+template <template<typename...> class Variant>
+struct visit_helper {
+    template <typename... Args>
+    static auto call(Args &&...args) -> decltype(visit(std::forward<Args>(args)...)) {
+        return visit(std::forward<Args>(args)...);
+    }
+};
+
+/// Generic variant caster
+template <typename Variant> struct variant_caster;
+
+template <template<typename...> class V, typename... Ts>
+struct variant_caster<V<Ts...>> {
+    static_assert(sizeof...(Ts) > 0, "Variant must consist of at least one alternative.");
+
+    template <typename U, typename... Us>
+    bool load_alternative(handle src, bool convert, type_list<U, Us...>) {
+        auto caster = make_caster<U>();
+        if (caster.load(src, convert)) {
+            value = cast_op<U>(caster);
+            return true;
+        }
+        return load_alternative(src, convert, type_list<Us...>{});
+    }
+
+    bool load_alternative(handle, bool, type_list<>) { return false; }
+
+    bool load(handle src, bool convert) {
+        // Do a first pass without conversions to improve constructor resolution.
+        // E.g. `py::int_(1).cast<variant<double, int>>()` needs to fill the `int`
+        // slot of the variant. Without two-pass loading `double` would be filled
+        // because it appears first and a conversion is possible.
+        if (convert && load_alternative(src, false, type_list<Ts...>{}))
+            return true;
+        return load_alternative(src, convert, type_list<Ts...>{});
+    }
+
+    template <typename Variant>
+    static handle cast(Variant &&src, return_value_policy policy, handle parent) {
+        return visit_helper<V>::call(variant_caster_visitor{policy, parent},
+                                     std::forward<Variant>(src));
+    }
+
+    using Type = V<Ts...>;
+    PYBIND11_TYPE_CASTER(Type, _("Union[") + detail::concat(make_caster<Ts>::name...) + _("]"));
+};
+
+#if PYBIND11_HAS_VARIANT
+template <typename... Ts>
+struct type_caster<std::variant<Ts...>> : variant_caster<std::variant<Ts...>> { };
+#endif
+
+NAMESPACE_END(detail)
+
+NAMESPACE_END(PYBIND11_NAMESPACE)
+
+#if defined(_MSC_VER)
+#pragma warning(pop)
+#endif

setup.py

@@ -37,6 +37,7 @@
         'include/pybind11/pytypes.h',
         'include/pybind11/stl.h',
         'include/pybind11/stl_bind.h',
+        'include/pybind11/utility.h',
     ]