std::move_if_noexcept(3)

Okay bestie, welcome to the std::move_if_noexcept(3) page from the C++ Standard Libary manual — yep, that's the manual name on the tin, and we're keeping it exactly as it is. 💅

🎀 NAME 🎀

std::move_if_noexcept — std::move_if_noexcept. That's the name, no cap. 💖

✨ Synopsis ✨

Defined in header <utility> 🦋

First overload, with the (since C++11) and (until C++14) annotations:

template< class T >
typename std::conditional<
    !std::is_nothrow_move_constructible<T>::value &&
    std::is_copy_constructible<T>::value,
    const T&,
    T&&
>::type move_if_noexcept( T& x ) noexcept;

(since C++11) (until C++14)

Second overload, now with constexpr and the (since C++14) annotation:

template< class T >
constexpr typename std::conditional<
    !std::is_nothrow_move_constructible<T>::value &&
    std::is_copy_constructible<T>::value,
    const T&,
    T&&
>::type move_if_noexcept( T& x ) noexcept;

(since C++14)

So here's the vibe: std::move_if_noexcept obtains an rvalue reference to its argument if its move constructor does not throw exceptions or if there is no copy constructor (move-only type); otherwise it obtains an lvalue reference to its argument. It's typically used to combine move semantics with the strong exception guarantee. Iconic behavior, honestly. ✨

🫶 Parameters 🫶

• x — the object to be moved or copied. That's the only parameter, bestie. 💖

💖 Return value 💖

It gives you std::move(x) or x, depending on exception guarantees. That's the whole return-value situation. 🫶

⚡ Complexity ⚡

Constant. Literally constant. ⚡

📝 Notes 📝

This is used, for example, by std::vector::resize, which may have to allocate new storage and then move or copy elements from old storage to new storage. If an exception occurs during this operation, std::vector::resize undoes everything it did to this point, which is only possible if std::move_if_noexcept was used to decide whether to use move construction or copy construction (unless copy constructor is not available, in which case move constructor is used either way and the strong exception guarantee may be waived). That's the whole note, and it's lowkey important. 💀

🌈 Example 🌈

// Run this code

#include <iostream>
#include <utility>

struct Bad
{
    Bad() {}
    Bad(Bad&&) // may throw
    {
        std::cout << "Throwing move constructor called\n";
    }
    Bad(const Bad&) // may throw as well
    {
        std::cout << "Throwing copy constructor called\n";
    }
};

struct Good
{
    Good() {}
    Good(Good&&) noexcept // will NOT throw
    {
        std::cout << "Non-throwing move constructor called\n";
    }
    Good(const Good&) noexcept // will NOT throw
    {
        std::cout << "Non-throwing copy constructor called\n";
    }
};

int main()
{
    Good g;
    Bad b;
    [[maybe_unused]] Good g2 = std::move_if_noexcept(g);
    [[maybe_unused]] Bad b2 = std::move_if_noexcept(b);
}

Output:

Non-throwing move constructor called
Throwing copy constructor called

👀 See also 👀

• forward — forwards a function argument (C++11) (function template)
• move — obtains an rvalue reference (C++11) (function template)

---

🌈 Cute little sign-off time: source/version and date are http://cppreference.com, 2024.06.10, and std::move_if_noexcept(3). That's the footer folded into a vibe, bestie — stay noexcept. 🫶