[libc++] Implement P0798R8 (Monadic operations for std::optional)

[philnik]

Summary

Implement P0798R8

[Mordante]

Thanks for working on this! The paper looks really interesting.
I want to do a proper review later. I just noticed the modification to version while looking at my e-mail.

libcxx/include/version

368

This won't work. I just mentioned the proper way to do this in D113013.

[philnik]

Updated Status and added feature-test macro

[ldionne]

libcxx/include/optional

602

We generally don't qualify types in namespace std. So just false_type would be consistent with what we do everywhere. This applies throughout the patch.

1028

Everywhere (for consistency).

1045

Note that this qualification of _VSTD::move is good because it protects against ADL. My comment above about qualifications do not apply to cases that prevent ADL from being triggered.

1068

The paper says:

Mandates: U is a non-array object type other than in_place_t or nullopt_t.

Here we're checking that it's not an array, it's not in_place_t, and it's not nullopt_t. But we are not checking that it's an object type. For instance, if __result_type ends up being a function type or void, we won't trigger any static_assert. I'm pretty sure it's going to fail in some other way, but I still think we should check for it explicitly.

1074

This isn't what the paper is expressing. The full wording of the paper is:

Let U be remove_cv_t<invoke_result_t<F, decltype(value())>>.

Mandates: U is a non-array object type other than in_place_t or nullopt_t. The declaration U u(invoke(std::forward<F>(f), value())); is well-formed for some invented variable u. [Note: is_move_constructible_v<U> can be false. -- end note]

Returns: If *this does not contain a value, optional<U>(); otherwise, an optional<U> object whose contained value is initialized as if direct-non-list-initializing an object of type U with invoke(std::forward<F>(f), value()).

What they mean in the Returns: section is that the object inside the optional should be direct-non-list-initialized as-if one had used U u(invoke(std::forward<F>(f), value())); exactly. Combined with the note that U doesn't have to be move-constructible, I am fairly convinced they are telling us to allow move-elision, like what I did in D107932. At the end of the day, I suspect this will have to look something like

optional<__result_type>(__construct_from_invoke_tag{}, _VSTD::forward<_Func>(__f), value());

where there's a special optional constructor that looks like

template<class _Fp, class ..._Args>
constexpr explicit optional(__construct_from_invoke_tag, _Fp&& __f, _Args&& ...__args) 
  : __value_(_VSTD::invoke(_VSTD::forward<_Fp>(__f), _VSTD::forward<_Args>(__args)...)))
{ }

This is of course going to be more complicated due to inheritance and stuff, but you get the idea. Here, at least, we allow move elision to occur.

Also, please add tests for all the methods that have this Note: where __result_type is not move-constructible. Those should fail with your current implementation and they should start working once you implement something like what I just laid out.

libcxx/test/std/utilities/optional/optional.monadic/or_else.pass.cpp

1

Please add tests for SFINAE friendliness when the Constraints: are not met.

[• Quuxplusone]

Looks pretty good to me so far!

libcxx/include/optional

605

I suggest __is_std_optional for consistency with __is_std_{span,array}. I also think there's no need for the __is_optional_v variable template (again for consistency).

(Or, if you absolutely want the variable template for efficiency — which you shouldn't — then I'd say to get rid of the struct template and just specialize the variable template directly.)

1034

Style nit: The Standard calls this U, and I think we should call it _Up. __lower_snake_case looks too much like a local variable to me (and is also verboser than needed). (Alternatively, _Rp; but I think it makes sense to follow the Standard's U.)

1095

Here decltype(std::move(value())) is just _Tp&& (and ditto throughout, with cvref-qualification differences). IMO the shorter _Tp&& form should be used for clarity.
Also, I'm like 95% sure that invoke_result_t<_Func, _Tp&&> is just invoke_result_t<_Func, _Tp> (because it all boils down to declval stuff in the end, and declval can't distinguish xvalues from prvalues).

libcxx/test/std/utilities/optional/optional.monadic/and_then.pass.cpp

1

For each of the new methods, I'd like to see one simple test case each sanity-checking that

• f is not gratuitously copied (it might not even be copyable)
• f's operator() is called with the correct constness and ref-qualification (e.g. operator()(int) & vs operator()(int) const&&)
• The argument to f is passed with the correct value category (e.g. operator()(int&) const vs operator()(int&&) const)
• The argument to f (that is, value()) is not gratuitously copied (it might not even be copyable)

32

static_cast<const std::optional<int>&>(opt) could be std::as_const(opt). However, that still doesn't help with the const&& cast, so maybe you just want to introduce a const version right at the top of the function?

std::optional<int> o;
const std::optional<int>& co = o;
auto never_called = [](int) { assert(false); return std::optional<long>(); };
o.and_then(never_called);
co.and_then(never_called);
std::move(o).and_then(never_called);
std::move(co).and_then(never_called);

o = 1;
assert(...

[philnik]

Updated tests and implemented transform() correctly

libcxx/test/std/utilities/optional/optional.monadic/or_else.pass.cpp

1

Could you reference something where that is done? I have no idea what you are asking for.

[• Quuxplusone]

libcxx/test/std/utilities/optional/optional.monadic/or_else.pass.cpp

1

Something like libcxx/test/std/utilities/tuple/tuple.tuple/tuple.helper/tuple_size_value_sfinae.pass.cpp. Basically:

#include "MoveOnly.h"

struct NonMovable {
    NonMovable() = default;
    NonMovable(NonMovable&&) = delete;
};

// TODO: rewrite to use 'requires' when _LIBCPP_HAS_NO_CONCEPTS goes away
template<class O, class F>
auto has_or_else(int, O&& o, F&& f)
    -> decltype(static_cast<O&&>(o).or_else(static_cast<F&&>(f)), true)
    { return true; }

template<class O, class F>
bool has_or_else(long, O&& o, F&& f)
    { return false; }

void test_sfinae() {
    std::optional<int> o1;
    std::optional<MoveOnly> o2;
    std::optional<NonMovable> o3;
    assert( has_or_else(0, o1, [&](){ return std::optional<int>(); }));
    assert( has_or_else(0, std::move(o1), [&](){ return std::optional<int>(); }));
    assert(!has_or_else(0, o2, [&](){ return std::optional<MoveOnly>(); }));
    assert( has_or_else(0, std::move(o2), [&](){ return std::optional<MoveOnly>(); }));
    assert(!has_or_else(0, o3, [&](){ return std::optional<NonMovable>(); }));
    assert(!has_or_else(0, std::move(o3), [&](){ return std::optional<NonMovable>(); }));

    assert(!has_or_else(0, o1, [&](int){ return std::optional<int>(); }));
    assert(!has_or_else(0, o1, [&](int){}));
    assert(!has_or_else(0, o1, 42));
}

[tcanens]

libcxx/include/optional

1067

This should be remove_cv_t. Ditto for other instances of transform.

1074

This isn't what the paper is expressing. The full wording of the paper is:

Let U be remove_cv_t<invoke_result_t<F, decltype(value())>>.

Mandates: U is a non-array object type other than in_place_t or nullopt_t. The declaration U u(invoke(std::forward<F>(f), value())); is well-formed for some invented variable u. [Note: is_move_constructible_v<U> can be false. -- end note]

Returns: If *this does not contain a value, optional<U>(); otherwise, an optional<U> object whose contained value is initialized as if direct-non-list-initializing an object of type U with invoke(std::forward<F>(f), value()).

What they mean in the Returns: section is that the object inside the optional should be direct-non-list-initialized as-if one had used U u(invoke(std::forward<F>(f), value())); exactly. Combined with the note that U doesn't have to be move-constructible, I am fairly convinced they are telling us to allow move-elision, like what I did in D107932. At the end of the day, I suspect this will have to look something like

optional<__result_type>(__construct_from_invoke_tag{}, _VSTD::forward<_Func>(__f), value());

where there's a special optional constructor that looks like

template<class _Fp, class ..._Args>
constexpr explicit optional(__construct_from_invoke_tag, _Fp&& __f, _Args&& ...__args) 
  : __value_(_VSTD::invoke(_VSTD::forward<_Fp>(__f), _VSTD::forward<_Args>(__args)...)))
{ }

This is of course going to be more complicated due to inheritance and stuff, but you get the idea. Here, at least, we allow move elision to occur.

Also, please add tests for all the methods that have this Note: where __result_type is not move-constructible. Those should fail with your current implementation and they should start working once you implement something like what I just laid out.

1128

Not just an optional - it needs to be this particular specialization of optional.

libcxx/test/std/utilities/optional/optional.monadic/and_then.pass.cpp

9

For the ones returning auto, I'd suggest a test using a SFINAE-unfriendly generic lambda to verify that they don't try to instantiate its body during overload resolution. See http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0798r8.html#sfinae-friendliness

libcxx/test/std/utilities/optional/optional.monadic/transform.pass.cpp

130

This seems to be missing a test where the transform function actually returns something immovable.

[tcanens]

libcxx/include/optional

1074

I thought I dropped this one... anyway, I wrote this wording and yes, that's the intent.

[philnik]

Added sfinae tests and changed remove_cvfet_t to remove_cv_t

[philnik]

Moved constructor

[philnik]

Rebased

[ldionne]

libcxx/test/std/utilities/optional/optional.monadic/and_then.pass.cpp

87–103

I find this somewhat hard to follow. Instead, I'd have an easier time if things were grouped by the method overload you are testing:

constexpr void test_val_types() {
  // Test & overload
  {
    // Without & qualifier on F's operator()
    {
      std::optional<int> i{};
      i.and_then(LVal{});
    }

    // With & qualifier on F's operator()
    {
      std::optional<int> i{};
      RefQual l{};
      i.and_then(l);
    }
  }

  // Test const& overload
  {
    // Without & qualifier on F's operator()
    {
      std::optional<int> const i{};
      ci.and_then(CLVal{});
    }

    // With & qualifier on F's operator()
    {
        std::optional<int> const i{};
        const CRefQual cl{};
        ci.and_then(cl);
    }
  }

  // etc...
}

This applies everywhere else AFAICT. This is more verbose, however at the end of the day it's way easier to follow and see the pattern in the tests.

Other things that apply to all tests AFAICT:

• We are not testing the return type and return values of the functions.
• We are not testing with a F that returns an empty optional. Above, your LVal & friends always return an engaged optional.
• We are not exhaustively testing with a i that is engaged and non-engaged. Above, you only test with a disengaged optional.

105–110

This needs a comment explaining what it's testing. test_sfinae isn't very descriptive, I'm staring at this and it's not immediately obvious to me what you're trying to test SFINAE for.

[philnik]

• rebased
• Updated tests

[ldionne]

Almost LGTM, thanks for working on this!

libcxx/include/optional

135–145

598

I think it is fine to unconditionally define this template. We'll only be using it in C++20, but I don't think it's worth the complexity to add the #if.

1035

The spec says:

Let U be invoke_result_t<F, decltype(std::move(value()))>.
Mandates: remove_cvref_t<U> is a specialization of optional.

I think we should be checking this instead:

static_assert(__is_std_optional<remove_cvref_t<_Up>>::value, ...);

This comment probably applies elsewhere.

libcxx/test/std/utilities/optional/optional.monadic/or_else.pass.cpp

26–33

I believe this would work and be equivalent:

template <class Opt, class F>
concept has_or_else = requires(Opt&& opt, F&& f) {
  { std::forward<Opt>(opt).or_else(std::forward<F>(f)) };
};

[philnik]

• rebased
• Addressed ldionne's comments

[philnik]

• Removed lambdas from unevaluated contexts

[philnik]

@Quuxplusone do you approve?

[• Quuxplusone]

I suspect it may be important to add some tests involving optional<optional<int>> just to make sure we strip (or don't strip) the right number of levels of optional. (This is one of the pernicious cases for CTAD, where the expression std::optional(e) changes meaning depending on the type of e.) However, please don't block this PR over that; just consider whether you agree, and then make a followup PR with some additional tests if you think it's important enough to test. (I'm also willing to believe it's not so important, if that's what you think.)

libcxx/include/optional

254–255

Nit: match {} brace style from lines 244 and 250. (Ditto line 299.)

1036

I wonder if this should say a specialization of std::optional, without the T, for pedantic correctness. This can totally be done post-commit, though, if we want to, rather than holding up this PR waiting for a round-trip to see if @ldionne agrees or whatever. :)

1128

Please make this Result of f() should be the same type as this optional — note the addition of "type." It might not be "the same (object)" in the same sense as operator='s return type must be "the same as this optional." Adding type makes that unambiguous, and it's cheap to do.
Ditto line 1161.

[ldionne]

libcxx/include/optional

1036

Yeah, I agree, let's reword the warning.

[philnik]

• Updated brace style
• Updated error messages

libcxx/docs/FeatureTestMacroTable.rst

.. table:: Current Status
     ``__cpp_lib_to_array``                            ``201907L``
     ------------------------------------------------- -----------------
     ``__cpp_lib_unwrap_ref``                          ``201811L``
     ------------------------------------------------- -----------------
     **C++ 2b**
     -------------------------------------------------------------------
     ``__cpp_lib_is_scoped_enum``                      ``202011L``
     ------------------------------------------------- -----------------
+    ``__cpp_lib_monadic_optional``                    ``202110L``
+    ------------------------------------------------- -----------------
     ``__cpp_lib_stacktrace``                          *unimplemented*
     ------------------------------------------------- -----------------
     ``__cpp_lib_stdatomic_h``                         *unimplemented*
     ------------------------------------------------- -----------------
     ``__cpp_lib_string_contains``                     ``202011L``
     ------------------------------------------------- -----------------
     ``__cpp_lib_to_underlying``                       ``202102L``
     ================================================= =================
 

libcxx/docs/Status/Cxx2bPapers.csv

 "`P1518R2 <https://wg21.link/P1518R2>`__","LWG","Stop overconstraining allocators in container deduction guides","June 2021","|Complete|","13.0"
 "`P1659R3 <https://wg21.link/P1659R3>`__","LWG","starts_with and ends_with","June 2021","",""
 "`P1951R1 <https://wg21.link/P1951R1>`__","LWG","Default Arguments for pair Forwarding Constructor","June 2021","|Complete|","14.0"
 "`P1989R2 <https://wg21.link/P1989R2>`__","LWG","Range constructor for std::string_view","June 2021","",""
 "`P2136R3 <https://wg21.link/P2136R3>`__","LWG","invoke_r","June 2021","",""
 "`P2166R1 <https://wg21.link/P2166R1>`__","LWG","A Proposal to Prohibit std::basic_string and std::basic_string_view construction from nullptr","June 2021","|Complete|","13.0"
 "","","","","",""
 "`P0288R9 <https://wg21.link/P0288R9>`__","LWG","``any_invocable``","October 2021","",""
-"`P0798R8 <https://wg21.link/P0798R8>`__","LWG","Monadic operations for ``std::optional``","October 2021","",""
+"`P0798R8 <https://wg21.link/P0798R8>`__","LWG","Monadic operations for ``std::optional``","October 2021","|Complete|","14.0"
 "`P0849R8 <https://wg21.link/P0849R8>`__","LWG","``auto(x)``: ``DECAY_COPY`` in the language","October 2021","",""
 "`P1072R10 <https://wg21.link/P1072R10>`__","LWG","``basic_string::resize_and_overwrite``","October 2021","",""
 "`P1147R1 <https://wg21.link/P1147R1>`__","LWG","Printing ``volatile`` Pointers","October 2021","",""
 "`P1272R4 <https://wg21.link/P1272R4>`__","LWG","Byteswapping for fun&&nuf","October 2021","",""
 "`P1675R2 <https://wg21.link/P1675R2>`__","LWG","``rethrow_exception`` must be allowed to copy","October 2021","",""
 "`P2077R3 <https://wg21.link/P2077R3>`__","LWG","Heterogeneous erasure overloads for associative containers","October 2021","",""
 "`P2251R1 <https://wg21.link/P2251R1>`__","LWG","Require ``span`` & ``basic_string_view`` to be Trivially Copyable","October 2021","|Complete|","14.0"
 "`P2301R1 <https://wg21.link/P2301R1>`__","LWG","Add a ``pmr`` alias for ``std::stacktrace``","October 2021","",""
 "`P2321R2 <https://wg21.link/P2321R2>`__","LWG","``zip``","October 2021","",""
 "`P2340R1 <https://wg21.link/P2340R1>`__","LWG","Clarifying the status of the 'C headers'","October 2021","",""
 "`P2393R1 <https://wg21.link/P2393R1>`__","LWG","Cleaning up ``integer``-class types","October 2021","",""
 "`P2401R0 <https://wg21.link/P2401R0>`__","LWG","Add a conditional ``noexcept`` specification to ``std::exchange``","October 2021","|Complete|","14.0"
 "","","","","",""

libcxx/include/optional

public:
     constexpr bool has_value() const noexcept;
     constexpr T const &value() const &;
     constexpr T &value() &;
     constexpr T &&value() &&;
     constexpr const T &&value() const &&;
     template <class U> constexpr T value_or(U &&) const &;
     template <class U> constexpr T value_or(U &&) &&;
 
+    // [optional.monadic], monadic operations
+    template<class F> constexpr auto and_then(F&& f) &;         // since c++23
+    template<class F> constexpr auto and_then(F&& f) &&;        // since c++23
+    template<class F> constexpr auto and_then(F&& f) const&;    // since c++23
+    template<class F> constexpr auto and_then(F&& f) const&&;   // since c++23
+    template<class F> constexpr auto transform(F&& f) &;        // since c++23
+    template<class F> constexpr auto transform(F&& f) &&;       // since c++23
+    template<class F> constexpr auto transform(F&& f) const&;   // since c++23
+    template<class F> constexpr auto transform(F&& f) const&&;  // since c++23
+    template<class F> constexpr optional or_else(F&& f) &&;     // since c++23
+    template<class F> constexpr optional or_else(F&& f) const&; // since c++23
+
     // 23.6.3.6, modifiers
     void reset() noexcept; // constexpr in C++20
 
   private:
     T *val; // exposition only
   };
 
 template<class T>
   optional(T) -> optional<T>;
 
 } // namespace std
 
 */
 
 #include <__availability>
+#include <__concepts/invocable.h>
 #include <__config>
 #include <__debug>
 #include <__functional_base>
 #include <compare>
 #include <functional>
 #include <initializer_list>
 #include <new>
 #include <stdexcept>
struct __optional_destruct_base<_Tp, false>
     constexpr explicit __optional_destruct_base(in_place_t, _Args&&... __args)
         :  __val_(_VSTD::forward<_Args>(__args)...),
            __engaged_(true) {}
 
     _LIBCPP_INLINE_VISIBILITY
     _LIBCPP_CONSTEXPR_AFTER_CXX17 void reset() noexcept
     {
         if (__engaged_)
         {
             __val_.~value_type();
             __engaged_ = false;
         }
     }
 };
 
 template <class _Tp>
 struct __optional_destruct_base<_Tp, true>
 {

 >;
 
 template <class _Tp>
 using __optional_sfinae_assign_base_t = __sfinae_assign_base<
     (is_copy_constructible<_Tp>::value && is_copy_assignable<_Tp>::value),
     (is_move_constructible<_Tp>::value && is_move_assignable<_Tp>::value)
 >;
 
+#if _LIBCPP_STD_VER > 20
+template<class _Tp>
+class optional;
+template <class _Tp>
+struct __is_optional : _VSTD::false_type {};
+template <class _Tp> struct __is_optional<_VSTD::optional<_Tp>> : _VSTD::true_type {};
+template<class _Tp>
+constexpr bool __is_optional_v = __is_optional<_Tp>::value;
+#endif
+
 template <class _Tp>
 class optional
     : private __optional_move_assign_base<_Tp>
     , private __optional_sfinae_ctor_base_t<_Tp>
     , private __optional_sfinae_assign_base_t<_Tp>
 {
     using __base = __optional_move_assign_base<_Tp>;
 public:
constexpr value_type value_or(_Up&& __v) &&
         static_assert(is_move_constructible_v<value_type>,
                       "optional<T>::value_or: T must be move constructible");
         static_assert(is_convertible_v<_Up, value_type>,
                       "optional<T>::value_or: U must be convertible to T");
         return this->has_value() ? _VSTD::move(this->__get()) :
                                   static_cast<value_type>(_VSTD::forward<_Up>(__v));
     }
 
+#if _LIBCPP_STD_VER > 20
+    template<class _Func>
+    _LIBCPP_HIDE_FROM_ABI
+    constexpr auto and_then(_Func&& __f) & {
+      using __result_type = invoke_result_t<_Func, decltype(value())>;
+      static_assert(__is_optional_v<__result_type>,
+                    "Result of f(value()) must be a specialization of std::optional<T>");
+      if (*this)
+        return _VSTD::invoke(_VSTD::forward<_Func>(__f), value());
+      return _VSTD::remove_cvref_t<__result_type> {};
+    }
+
+    template<class _Func>
+    _LIBCPP_HIDE_FROM_ABI
+    constexpr auto and_then(_Func&& __f) const& {
+      using __result_type = invoke_result_t<_Func, decltype(value())>;
+      static_assert(__is_optional_v<__result_type>,
+                    "Result of f(value()) must be a specialization of std::optional<T>");
+      if (*this)
+        return _VSTD::invoke(_VSTD::forward<_Func>(__f), value());
+      return _VSTD::remove_cvref_t<__result_type> {};
+    }
+
+    template<class _Func>
+    _LIBCPP_HIDE_FROM_ABI
+    constexpr auto and_then(_Func&& __f) && {
+      using __result_type = invoke_result_t<_Func, decltype(_VSTD::move(value()))>;
+      static_assert(__is_optional_v<__result_type>,
+                    "Result of f(std::move(value())) must be a specialization of std::optional<T>");
+      if (*this)
+        return _VSTD::invoke(_VSTD::forward<_Func>(__f), _VSTD::move(value()));
+      return remove_cvref_t<__result_type> {};
+    }
+
+    template<class _Func>
+    _LIBCPP_HIDE_FROM_ABI
+    constexpr auto and_then(_Func&& __f) const&& {
+      using __result_type = invoke_result_t<_Func, decltype(_VSTD::move(value()))>;
+      static_assert(__is_optional_v<__result_type>,
+                    "Result of f(std::move(value())) must be a specialization of std::optional<T>");
+      if (*this)
+        return _VSTD::invoke(_VSTD::forward<_Func>(__f), _VSTD::move(value()));
+      return remove_cvref_t<__result_type> {};
+    }
+
+    template<class _Func>
+    _LIBCPP_HIDE_FROM_ABI
+    constexpr auto transform(_Func&& __f) & {
+      using __result_type = remove_cvref_t<invoke_result_t<_Func, decltype(value())>>;
+      static_assert(!is_array_v<__result_type>, "Result of f(value()) should not be an Array");
+      static_assert(!is_same_v<__result_type, in_place_t>,
+                    "Result of f(value()) should not be std::in_place_t");
+      static_assert(!is_same_v<__result_type, nullopt_t>,
+                    "Result of f(value()) should not be std::nullopt_t");
+      if (*this)
+        return optional<__result_type> {_VSTD::invoke(_VSTD::forward<_Func>(__f), value())};
+      return optional<__result_type> {};
+    }
+
+    template<class _Func>
+    _LIBCPP_HIDE_FROM_ABI
+    constexpr auto transform(_Func&& __f) const& {
+      using __result_type = remove_cvref_t<invoke_result_t<_Func, decltype(value())>>;
+      static_assert(!is_array_v<__result_type>, "Result of f(value()) should not be an Array");
+      static_assert(!is_same_v<__result_type, in_place_t>,
+                    "Result of f(value()) should not be std::in_place_t");
+      static_assert(!is_same_v<__result_type, nullopt_t>,
+                    "Result of f(value()) should not be std::nullopt_t");
+      if (*this)
+        return optional<__result_type> {_VSTD::invoke(_VSTD::forward<_Func>(__f), value())};
+      return optional<__result_type> {};
+    }
+
+    template<class _Func>
+    _LIBCPP_HIDE_FROM_ABI
+    constexpr auto transform(_Func&& __f) && {
+      using __result_type = remove_cvref_t<invoke_result_t<_Func, decltype(std::move(value()))>>;
+      static_assert(!is_array_v<__result_type>, "Result of f(std::move(value())) should not be an Array");
+      static_assert(!is_same_v<__result_type, in_place_t>,
+                    "Result of f(std::move(value())) should not be std::in_place_t");
+      static_assert(!is_same_v<__result_type, nullopt_t>,
+                    "Result of f(std::move(value())) should not be std::nullopt_t");
+      if (*this)
+        return optional<__result_type> {_VSTD::invoke(_VSTD::forward<_Func>(__f), _VSTD::move(value()))};
+      return optional<__result_type> {};
+    }
+
+    template<class _Func>
+    _LIBCPP_HIDE_FROM_ABI
+    constexpr auto transform(_Func&& __f) const&& {
+      using __result_type = remove_cvref_t<invoke_result_t<_Func, decltype(std::move(value()))>>;
+      static_assert(!is_array_v<__result_type>, "Result of f(std::move(value())) should not be an Array");
+      static_assert(!is_same_v<__result_type, in_place_t>,
+                    "Result of f(std::move(value())) should not be std::in_place_t");
+      static_assert(!is_same_v<__result_type, nullopt_t>,
+                    "Result of f(std::move(value())) should not be std::nullopt_t");
+      if (*this)
+        return optional<__result_type> {_VSTD::invoke(_VSTD::forward<_Func>(__f), _VSTD::move(value()))};
+      return optional<__result_type> {};
+    }
+
+    template<invocable _Func>
+    _LIBCPP_HIDE_FROM_ABI
+    constexpr optional or_else(_Func&& __f) const& requires is_copy_constructible_v<value_type> {
+      static_assert(is_same_v<remove_cvref_t<invoke_result_t<_Func>>, optional>,
+                    "Result of f() should be an optional");
+      if (*this)
+        return *this;
+      return std::forward<_Func>(__f)();
+    }
+
+    template<invocable _Func>
+    _LIBCPP_HIDE_FROM_ABI
+    constexpr optional or_else(_Func&& __f) && requires is_move_constructible_v<value_type> {
+      static_assert(is_same_v<remove_cvref_t<invoke_result_t<_Func>>, optional>,
+                    "Result of f() should be an optional");
+      if (*this)
+        return std::move(*this);
+      return std::forward<_Func>(__f)();
+    }
+#endif // _LIBCPP_STD_VER > 20
+
     using __base::reset;
 };
 
 #if _LIBCPP_STD_VER >= 17
 template<class T>
     optional(T) -> optional<T>;
 #endif
 

libcxx/include/version

 __cpp_lib_logical_traits                                201510L <type_traits>
 __cpp_lib_make_from_tuple                               201606L <tuple>
 __cpp_lib_make_reverse_iterator                         201402L <iterator>
 __cpp_lib_make_unique                                   201304L <memory>
 __cpp_lib_map_try_emplace                               201411L <map>
 __cpp_lib_math_constants                                201907L <numbers>
 __cpp_lib_math_special_functions                        201603L <cmath>
 __cpp_lib_memory_resource                               201603L <memory_resource>
+__cpp_lib_monadic_optional                              202110L <optional>
 __cpp_lib_node_extract                                  201606L <map> <set> <unordered_map>
                                                                 <unordered_set>
 __cpp_lib_nonmember_container_access                    201411L <array> <deque> <forward_list>
                                                                 <iterator> <list> <map>
                                                                 <regex> <set> <string>
                                                                 <unordered_map> <unordered_set> <vector>
 __cpp_lib_not_fn                                        201603L <functional>
 __cpp_lib_null_iterators                                201304L <iterator>

 // # define __cpp_lib_three_way_comparison                 201907L
 # define __cpp_lib_to_address                           201711L
 # define __cpp_lib_to_array                             201907L
 # define __cpp_lib_unwrap_ref                           201811L
 #endif
 
 #if _LIBCPP_STD_VER > 20
 # define __cpp_lib_is_scoped_enum                       202011L
+# define __cpp_lib_monadic_optional                     202110L
 // # define __cpp_lib_stacktrace                           202011L
 // # define __cpp_lib_stdatomic_h                          202011L
 # define __cpp_lib_string_contains                      202011L
 # define __cpp_lib_to_underlying                        202102L
 #endif
 
 // clang-format on
 
 #endif // _LIBCPP_VERSIONH

libcxx/test/std/language.support/support.limits/support.limits.general/optional.version.pass.cpp

 // and should not be edited manually.
 //
 // clang-format off
 
 // <optional>
 
 // Test the feature test macros defined by <optional>
 
-/*  Constant              Value
-    __cpp_lib_optional    201606L [C++17]
+/*  Constant                      Value
+    __cpp_lib_monadic_optional    202110L [C++2b]
+    __cpp_lib_optional            201606L [C++17]
 */
 
 #include <optional>
 #include "test_macros.h"
 
 #if TEST_STD_VER < 14
 
+# ifdef __cpp_lib_monadic_optional
+#   error "__cpp_lib_monadic_optional should not be defined before c++2b"
+# endif
+
 # ifdef __cpp_lib_optional
 #   error "__cpp_lib_optional should not be defined before c++17"
 # endif
 
 #elif TEST_STD_VER == 14
 
+# ifdef __cpp_lib_monadic_optional
+#   error "__cpp_lib_monadic_optional should not be defined before c++2b"
+# endif
+
 # ifdef __cpp_lib_optional
 #   error "__cpp_lib_optional should not be defined before c++17"
 # endif
 
 #elif TEST_STD_VER == 17
 
+# ifdef __cpp_lib_monadic_optional
+#   error "__cpp_lib_monadic_optional should not be defined before c++2b"
+# endif
+
 # ifndef __cpp_lib_optional
 #   error "__cpp_lib_optional should be defined in c++17"
 # endif
 # if __cpp_lib_optional != 201606L
 #   error "__cpp_lib_optional should have the value 201606L in c++17"
 # endif
 
 #elif TEST_STD_VER == 20
 
+# ifdef __cpp_lib_monadic_optional
+#   error "__cpp_lib_monadic_optional should not be defined before c++2b"
+# endif
+
 # ifndef __cpp_lib_optional
 #   error "__cpp_lib_optional should be defined in c++20"
 # endif
 # if __cpp_lib_optional != 201606L
 #   error "__cpp_lib_optional should have the value 201606L in c++20"
 # endif
 
 #elif TEST_STD_VER > 20
 
+# ifndef __cpp_lib_monadic_optional
+#   error "__cpp_lib_monadic_optional should be defined in c++2b"
+# endif
+# if __cpp_lib_monadic_optional != 202110L
+#   error "__cpp_lib_monadic_optional should have the value 202110L in c++2b"
+# endif
+
 # ifndef __cpp_lib_optional
 #   error "__cpp_lib_optional should be defined in c++2b"
 # endif
 # if __cpp_lib_optional != 201606L
 #   error "__cpp_lib_optional should have the value 201606L in c++2b"
 # endif
 
 #endif // TEST_STD_VER > 20
 
 int main(int, char**) { return 0; }

libcxx/test/std/language.support/support.limits/support.limits.general/version.version.pass.cpp

/*  Constant                                       Value
     __cpp_lib_logical_traits                       201510L [C++17]
     __cpp_lib_make_from_tuple                      201606L [C++17]
     __cpp_lib_make_reverse_iterator                201402L [C++14]
     __cpp_lib_make_unique                          201304L [C++14]
     __cpp_lib_map_try_emplace                      201411L [C++17]
     __cpp_lib_math_constants                       201907L [C++20]
     __cpp_lib_math_special_functions               201603L [C++17]
     __cpp_lib_memory_resource                      201603L [C++17]
+    __cpp_lib_monadic_optional                     202110L [C++2b]
     __cpp_lib_node_extract                         201606L [C++17]
     __cpp_lib_nonmember_container_access           201411L [C++17]
     __cpp_lib_not_fn                               201603L [C++17]
     __cpp_lib_null_iterators                       201304L [C++14]
     __cpp_lib_optional                             201606L [C++17]
     __cpp_lib_parallel_algorithm                   201603L [C++17]
     __cpp_lib_polymorphic_allocator                201902L [C++20]
     __cpp_lib_quoted_string_io                     201304L [C++14]

 # ifdef __cpp_lib_math_special_functions
 #   error "__cpp_lib_math_special_functions should not be defined before c++17"
 # endif
 
 # ifdef __cpp_lib_memory_resource
 #   error "__cpp_lib_memory_resource should not be defined before c++17"
 # endif
 
+# ifdef __cpp_lib_monadic_optional
+#   error "__cpp_lib_monadic_optional should not be defined before c++2b"
+# endif
+
 # ifdef __cpp_lib_node_extract
 #   error "__cpp_lib_node_extract should not be defined before c++17"
 # endif
 
 # ifdef __cpp_lib_nonmember_container_access
 #   error "__cpp_lib_nonmember_container_access should not be defined before c++17"
 # endif
 

 # ifdef __cpp_lib_math_special_functions
 #   error "__cpp_lib_math_special_functions should not be defined before c++17"
 # endif
 
 # ifdef __cpp_lib_memory_resource
 #   error "__cpp_lib_memory_resource should not be defined before c++17"
 # endif
 
+# ifdef __cpp_lib_monadic_optional
+#   error "__cpp_lib_monadic_optional should not be defined before c++2b"
+# endif
+
 # ifdef __cpp_lib_node_extract
 #   error "__cpp_lib_node_extract should not be defined before c++17"
 # endif
 
 # ifdef __cpp_lib_nonmember_container_access
 #   error "__cpp_lib_nonmember_container_access should not be defined before c++17"
 # endif
 

 #     error "__cpp_lib_memory_resource should have the value 201603L in c++17"
 #   endif
 # else // _LIBCPP_VERSION
 #   ifdef __cpp_lib_memory_resource
 #     error "__cpp_lib_memory_resource should not be defined because it is unimplemented in libc++!"
 #   endif
 # endif
 
+# ifdef __cpp_lib_monadic_optional
+#   error "__cpp_lib_monadic_optional should not be defined before c++2b"
+# endif
+
 # ifndef __cpp_lib_node_extract
 #   error "__cpp_lib_node_extract should be defined in c++17"
 # endif
 # if __cpp_lib_node_extract != 201606L
 #   error "__cpp_lib_node_extract should have the value 201606L in c++17"
 # endif
 
 # ifndef __cpp_lib_nonmember_container_access

 #     error "__cpp_lib_memory_resource should have the value 201603L in c++20"
 #   endif
 # else // _LIBCPP_VERSION
 #   ifdef __cpp_lib_memory_resource
 #     error "__cpp_lib_memory_resource should not be defined because it is unimplemented in libc++!"
 #   endif
 # endif
 
+# ifdef __cpp_lib_monadic_optional
+#   error "__cpp_lib_monadic_optional should not be defined before c++2b"
+# endif
+
 # ifndef __cpp_lib_node_extract
 #   error "__cpp_lib_node_extract should be defined in c++20"
 # endif
 # if __cpp_lib_node_extract != 201606L
 #   error "__cpp_lib_node_extract should have the value 201606L in c++20"
 # endif
 
 # ifndef __cpp_lib_nonmember_container_access

 #     error "__cpp_lib_memory_resource should have the value 201603L in c++2b"
 #   endif
 # else // _LIBCPP_VERSION
 #   ifdef __cpp_lib_memory_resource
 #     error "__cpp_lib_memory_resource should not be defined because it is unimplemented in libc++!"
 #   endif
 # endif
 
+# ifndef __cpp_lib_monadic_optional
+#   error "__cpp_lib_monadic_optional should be defined in c++2b"
+# endif
+# if __cpp_lib_monadic_optional != 202110L
+#   error "__cpp_lib_monadic_optional should have the value 202110L in c++2b"
+# endif
+
 # ifndef __cpp_lib_node_extract
 #   error "__cpp_lib_node_extract should be defined in c++2b"
 # endif
 # if __cpp_lib_node_extract != 201606L
 #   error "__cpp_lib_node_extract should have the value 201606L in c++2b"
 # endif
 
 # ifndef __cpp_lib_nonmember_container_access

libcxx/test/std/utilities/optional/optional.monadic/and_then.pass.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++03, c++11, c++14, c++17, c++20
+// <optional>
+
+// template<class F> constexpr auto and_then(F&&) &;
+// template<class F> constexpr auto and_then(F&&) &&;
+// template<class F> constexpr auto and_then(F&&) const&;
+// template<class F> constexpr auto and_then(F&&) const&&;
+
+#include <cassert>
+#include <optional>
+
+constexpr bool test() {
+  std::optional<int> opt{};
+  opt.and_then([](int) {
+    assert(false);
+    return std::optional<int>{};
+  });
+
+  std::move(opt).and_then([](int) {
+    assert(false);
+    return std::optional<int>{};
+  });
+
+  static_cast<const std::optional<int>&>(opt).and_then([](int) {
+    assert(false);
+    return std::optional<int>{};
+  });
+
+  static_cast<const std::optional<int>&&>(opt).and_then([](int) {
+    assert(false);
+    return std::optional<int>{};
+  });
+
+  opt = 1;
+  assert(*opt.and_then([](int i) { return std::optional{i + 1}; }) == 2);
+  assert(*std::move(opt).and_then([](int i) { return std::optional{i + 1}; }) == 2);
+  assert(*static_cast<const std::optional<int>&>(opt).and_then([](int i) { return std::optional{i + 1}; }) == 2);
+  assert(*static_cast<const std::optional<int>&&>(opt).and_then([](int i) { return std::optional{i + 1}; }) == 2);
+
+  return true;
+}
+
+int main(int, char**) {
+  test();
+  static_assert(test());
+}

libcxx/test/std/utilities/optional/optional.monadic/or_else.pass.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++03, c++11, c++14, c++17, c++20
+// <optional>
+
+// template<class F> constexpr optional or_else(F&&) &&;
+// template<class F> constexpr optional or_else(F&&) const&;
+
+#include "MoveOnly.h"
+
+#include <cassert>
+#include <optional>
+
+constexpr bool test() {
+  {
+    std::optional<int> opt;
+    assert(opt.or_else([] { return std::optional<int>{0}; }) == 0);
+    opt = 1;
+    opt.or_else([] {
+      assert(false);
+      return std::optional<int>{};
+    });
+  }
+  {
+    std::optional<MoveOnly> opt;
+    opt = std::move(opt).or_else([] { return std::optional<MoveOnly>{MoveOnly{}}; });
+    std::move(opt).or_else([] {
+      assert(false);
+      return std::optional<MoveOnly>{};
+    });
+  }
+
+  return true;
+}
+
+int main(int, char**) {
+  test();
+  static_assert(test());
+}

libcxx/test/std/utilities/optional/optional.monadic/transform.pass.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++03, c++11, c++14, c++17, c++20
+// <optional>
+
+// template<class F> constexpr auto transform(F&&) &;
+// template<class F> constexpr auto transform(F&&) &&;
+// template<class F> constexpr auto transform(F&&) const&;
+// template<class F> constexpr auto transform(F&&) const&&;
+
+#include <cassert>
+#include <optional>
+
+constexpr bool test() {
+  std::optional<int> opt;
+
+  opt.transform([](int) {
+    assert(false);
+    return 0;
+  });
+
+  std::move(opt).transform([](int) {
+    assert(false);
+    return 0;
+  });
+
+  static_cast<const std::optional<int>&>(opt).transform([](int) {
+    assert(false);
+    return 0;
+  });
+
+  static_cast<const std::optional<int>&&>(opt).transform([](int) {
+    assert(false);
+    return 0;
+  });
+
+  opt = 1;
+
+  assert(opt.transform([](int i) { return i + 1; }) == 2);
+  assert(std::move(opt).transform([](int i) { return i + 1; }) == 2);
+  assert(static_cast<const std::optional<int>&>(opt).transform([](int i) { return i + 1; }) == 2);
+  assert(static_cast<const std::optional<int>&&>(opt).transform([](int i) { return i + 1; }) == 2);
+
+  return true;
+}
+
+int main(int, char**) {
+  test();
+  static_assert(test());
+}

libcxx/utils/generate_feature_test_macro_components.py

feature_test_macros = [ add_version_header(x) for x in [
     "headers": ["cmath"],
     "unimplemented": True,
   }, {
     "name": "__cpp_lib_memory_resource",
     "values": { "c++17": 201603 },
     "headers": ["memory_resource"],
     "unimplemented": True,
   }, {
+    "name": "__cpp_lib_monadic_optional",
+    "values": { "c++2b": 202110 },
+    "headers": ["optional"],
+  }, {
     "name": "__cpp_lib_node_extract",
     "values": { "c++17": 201606 },
     "headers": ["map", "set", "unordered_map", "unordered_set"],
   }, {
     "name": "__cpp_lib_nonmember_container_access",
     "values": { "c++17": 201411 },
     "headers": ["array", "deque", "forward_list", "iterator", "list", "map", "regex", "set", "string", "unordered_map", "unordered_set", "vector"],
   }, {