std::ref,std::cref(3)

💖 std::ref,std::cref(3) 💖

okay bestie, welcome to the std::ref / std::cref page from the C++ Standard Libary manual. Yes, that's the manual name — we're keeping it exactly, no autocorrect energy here 💅. This whole page is about helper functions, reference wrappers, and template argument deduction doing its main character thing.

🌸 NAME 🌸

std::ref, std::cref — literally std::ref, std::cref. That's the name, bestie; no hidden subtitle. 🎀

🌸 Synopsis 🌸

Defined in header <functional>.

Here's the full overload roster — every signature, every standard-version glow-up, nothing skipped:

(1) ref( T& t )

since C++11, until C++20:

template< class T >
std::reference_wrapper<T> ref( T& t ) noexcept;

since C++20:

template< class T >
constexpr std::reference_wrapper<T> ref( T& t ) noexcept;

(2) ref( std::reference_wrapper<T> t )

since C++11, until C++20:

template< class T >
std::reference_wrapper<T> ref( std::reference_wrapper<T> t ) noexcept;

since C++20:

template< class T >
constexpr std::reference_wrapper<T> ref( std::reference_wrapper<T> t ) noexcept;

(3) ref( const T&& ) = delete;

since C++11:

template< class T >
void ref( const T&& ) = delete;

(4) cref( const T& t )

since C++11, until C++20:

template< class T >
std::reference_wrapper<const T> cref( const T& t ) noexcept;

since C++20:

template< class T >
constexpr std::reference_wrapper<const T> cref( const T& t ) noexcept;

(5) cref( std::reference_wrapper<T> t )

since C++11, until C++20:

template< class T >
std::reference_wrapper<const T> cref( std::reference_wrapper<T> t ) noexcept;

since C++20:

template< class T >
constexpr std::reference_wrapper<const T> cref( std::reference_wrapper<T> t ) noexcept;

(6) cref( const T&& ) = delete;

since C++11:

template< class T >
void cref( const T&& ) = delete;

Function templates ref and cref are helper functions that generate an object of type std::reference_wrapper, using template argument deduction to determine the template argument of the result. That's the whole magic trick. ✨

Also, heads up: T may be an incomplete type. (since C++20)

🎀 Parameters 🎀

• t — lvalue reference to object that needs to be wrapped or an instance of std::reference_wrapper. That's the thing being handed over.

🔥 Return value 🔥

Match the numbers to the overloads above, bestie:

• 1) std::reference_wrapper<T>(t)
• 2) t
• 4) std::reference_wrapper<const T>(t)
• 5) t
• 3,6) rvalue reference wrapper is deleted. Like, literally deleted — not a drill.

🧚 Example 🧚

okay this example is lowkey iconic because it shows std::bind, std::ref, and std::cref all in one group chat:

// Run this code

#include <functional>
#include <iostream>

void f(int& n1, int& n2, const int& n3)
{
    std::cout << "In function: " << n1 << ' ' << n2 << ' ' << n3 << '\n';
    ++n1; // increments the copy of n1 stored in the function object
    ++n2; // increments the main()'s n2
    // ++n3; // compile error
}

int main()
{
    int n1 = 1, n2 = 2, n3 = 3;
    std::function<void()> bound_f = std::bind(f, n1, std::ref(n2), std::cref(n3));
    n1 = 10;
    n2 = 11;
    n3 = 12;
    std::cout << "Before function: " << n1 << ' ' << n2 << ' ' << n3 << '\n';
    bound_f();
    std::cout << "After function: " << n1 << ' ' << n2 << ' ' << n3 << '\n';
}

🎬 Output 🎬

Before function: 10 11 12
In function: 1 11 12
After function: 10 12 12

💀 Defect reports 💀

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

• DR LWG 3146 — Applied to: C++11. Behavior as published: unwrapping overloads sometimes led to error. Correct behavior: made always valid.

🌈 See also 🌈

• reference_wrapper — CopyConstructible and CopyAssignable reference wrapper (C++11) (class template).

---

source/version + date folded into this cute sign-off: http://cppreference.com, 2024.06.10, and the page is std::ref,std::cref(3). bye bestie, go wrap some references responsibly 💖🫶✨