Jaakko
Järvi
Peter
Dimov
Douglas
Gregor
Dave
Abrahams
1999
2000
Jaakko Järvi
2001
2002
Peter Dimov
2002
David Abrahams

Subject to the Boost Software License, Version 1.0. See accompanying file `LICENSE_1_0.txt` or copy at http://www.boost.org/LICENSE_1_0.txt.

A utility library for passing references to generic functions

# Boost.Ref

# Introduction

The Ref library is a small library that is useful for passing references to function templates (algorithms) that would usually take copies of their arguments. It defines the class template ``boost::reference_wrapper<T>``, two functions `boost::ref` and `boost::cref` that return instances of `boost::reference_wrapper<T>`, a function `boost::unwrap_ref` that unwraps a `boost::reference_wrapper<T>` or returns a reference to any other type of object, and the two traits classes ``boost::is_reference_wrapper<T>`` and ``boost::unwrap_reference<T>``.

The purpose of `boost::reference_wrapper<T>` is to contain a reference to an object of type T. It is primarily used to "feed" references to function templates (algorithms) that take their parameter by value.

To support this usage, `boost::reference_wrapper<T>` provides an implicit conversion to `T&`. This usually allows the function templates to work on references unmodified.

`boost::reference_wrapper<T>` is both CopyConstructible and Assignable (ordinary references are not Assignable).

The expression `boost::ref(x)` returns a `boost::reference_wrapper<X>(x)` where X is the type of x. Similarly, `boost::cref(x)` returns a `boost::reference_wrapper<X const>(x)`.

The expression `boost::unwrap_ref(x)` returns a `boost::unwrap_reference<X>::type&` where X is the type of x.

The expression `boost::is_reference_wrapper<T>::value` is true if T is a `reference_wrapper`, and false otherwise.

The type-expression `boost::unwrap_reference<T>::type` is T::type if T is a `reference_wrapper`, T otherwise.

Contains a reference to an object of type `T`.

``reference_wrapper`` is primarily used to "feed" references to function templates (algorithms) that take their parameter by value. It provides an implicit conversion to `T&`, which usually allows the function templates to work on references unmodified.

T
T&

Constructs a ``reference_wrapper`` object that stores a reference to `t`.

Does not throw.

T&

The stored reference.

Does not throw.

T&

The stored reference.

Does not throw.

T*

A pointer to the object referenced by the stored reference.

Does not throw.

reference_wrapper<T> `T&`

``reference_wrapper`<T>(t)`

Does not throw.

reference_wrapper<T const> `T const&`

``reference_wrapper`<T const>(t)`

Does not throw.

unwrap_reference<T>::type& `T&`

``unwrap_reference`<T>::type&(t)`

Does not throw.

Determine if a type `T` is an instantiation of ``reference_wrapper``.

The `value` static constant will be `true` iff the type `T` is a specialization of ``reference_wrapper``.

bool unspecified
Find the type in a ``reference_wrapper``.

The typedef `type` is `T::type` if `T` is a ``reference_wrapper``, `T` otherwise.

unspecified

# Acknowledgements

ref and cref were originally part of the Tuple library by Jaakko Järvi. They were "promoted to boost:: status" by Peter Dimov because they are generally useful. Douglas Gregor and Dave Abrahams contributed `is_reference_wrapper` and `unwrap_reference`. Frank Mori Hess and Ronald Garcia contributed boost::unwrap_ref