std::expected::transform(3)

💖 std::expected::transform(3) 💖

okay bestie, welcome to the std::expected::transform(3) page from the C++ Standard Libary (yes, that's how the header spells it, iykyk 😭). This is the C++23 glow-up for transforming an expected value, and it's giving main-character energy fr fr. Let's get into it 💅✨

🌸 NAME 🌸

std::expected::transform — std::expected::transform

✨ Synopsis ✨

template< class F >                        (1) (since C++23)
constexpr auto transform( F&& f ) &;
template< class F >                        (2) (since C++23)
constexpr auto transform( F&& f ) const&;
template< class F >                        (3) (since C++23)
constexpr auto transform( F&& f ) &&;
template< class F >                        (4) (since C++23)
constexpr auto transform( F&& f ) const&&;

okay so here's the vibe: if *this contains an expected value, it invokes f and returns a std::expected object that contains its result. otherwise, it returns a std::expected object that contains a copy of error(). literally that simple, no cap 💖

if T is not (possibly cv-qualified) void, the contained value (obtained from operator*) is passed as an argument to f; otherwise f takes no argument.

1,2) Given type U as:

• std::remove_cv_t<std::invoke_result_t<F>> if T is (possibly cv-qualified) void, or
• std::remove_cv_t<std::invoke_result_t<F, decltype(**this)>> otherwise,

and expression /* invoke-expr */ as:

• std::invoke(std::forward<F>(f)) if T is (possibly cv-qualified) void, or
• std::invoke(std::forward<F>(f), **this) otherwise.

If U is not a valid value type for std::expected, or U u(/* invoke-expr */); is ill-formed when std::is_void_v<U> is false, the program is ill-formed.

The effect is equivalent to:

if (has_value())
{
    if constexpr (std::is_void_v<U>)
    {
        /* invoke-expr */;
        return std::expected<U, E>();
    }
    else
        // the returned std::expected object contains an expected value,
        // which is direct-non-list-initialized with /* invoke-expr */
        return /* an std::expected<U, E> object */;
}
else
    return std::expected<U, E>(std::unexpect, error());

These overloads participate in overload resolution only if std::is_constructible_v<E, decltype(error())> is true.

3,4) Given type U as:

• std::remove_cv_t<std::invoke_result_t<F>> if T is (possibly cv-qualified) void, or
• std::remove_cv_t<std::invoke_result_t<F, decltype(std::move(**this))>> otherwise,

and expression /* invoke-expr */ as:

• std::invoke(std::forward<F>(f)) if T is (possibly cv-qualified) void, or
• std::invoke(std::forward<F>(f), std::move(**this)) otherwise.

If U is not a valid value type for std::expected, or U u(/* invoke-expr */); is ill-formed when std::is_void_v<U> is false, the program is ill-formed.

The effect is equivalent to:

if (has_value())
{
    if constexpr (std::is_void_v<U>)
    {
        /* invoke-expr */;
        return std::expected<U, E>();
    }
    else
        // the returned std::expected object contains an expected value,
        // which is direct-non-list-initialized with /* invoke-expr */
        return /* an std::expected<U, E> object */;
}
else
    return std::expected<U, E>(std::unexpect, std::move(error()));

These overloads participate in overload resolution only if std::is_constructible_v<E, decltype(std::move(error()))> is true.

🎀 Parameters 🎀

• f — a suitable function or Callable object whose call signature returns a non-reference type.

🦋 Return value 🦋

A std::expected object containing either the result of f or an error value, as described above.

💀 Example 💀

This section is incomplete Reason: no example

bestie there is literally no example here 😭 the page says so itself, not me.

🔥 Defect reports 🔥

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• DR LWG 3938 — Applied to: C++23; Behavior as published: transform was ill-formed if T is not (possibly cv-qualified) void and E is not copyable; Correct behavior: made well-formed.

🌈 See also 🌈

• transform_error — returns the expected itself if it contains an expected value; otherwise, returns an expected containing the transformed unexpected value (public member function).

🍓 Category 🍓

• Todo no example

---

mwah 💖 this has been std::expected::transform(3) from the C++ Standard Libary, source http://cppreference.com, page dated 2024.06.10. go transform something bestie 🫶✨