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

Permission to copy, use, modify, sell and distribute this software is granted provided this copyright notice appears in all copies. This software is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.

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>``, the two functions `boost::ref` and `boost::cref` that return instances of `boost::reference_wrapper<T>`, 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::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.

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`.