# Boost: ref.hpp documentation

# ref.hpp

1.00.0004 (2002-01-27)

## Files

- ref.hpp

## Purpose

The header boost/ref.hpp 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.

## Interface

### Synopsis

    namespace boost
    {
        template<class T> class reference_wrapper;
        template<class T> reference_wrapper<T> ref(T & t);
        template<class T> reference_wrapper<T const> cref(T const & t);
        template<class T> class is_reference_wrapper<T const>;
        template<class T> class unwrap_reference<T const>;
    }

### reference_wrapper

    template<class T> class reference_wrapper
    {
    public:
        typedef T type;

        explicit reference_wrapper(T & t);

        operator T & () const;

        T & get() const;
        T* get_pointer() const;
    };

#### explicit reference_wrapper(T & t)

> Effects: Constructs a reference_wrapper object that stores a reference to t.

> Throws: Nothing.

#### operator T & () const

> Returns: the stored reference.

> Throws: Nothing.

#### T & get() const

> Returns: the stored reference.

> Throws: Nothing.

#### T* get_pointer() const

> Returns: a pointer to the stored object.

> Throws: Nothing.

### ref

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

> Returns: `reference_wrapper<T>(t)`.

> Throws: Nothing.

### cref

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

> Returns: `reference_wrapper<T const>(t)`.

> Throws: Nothing.

### is_reference_wrapper

    template<class T> class is_reference_wrapper<T const>
    {
     public:
        static bool value = unspecified;
    };

Value is true iff `T` is a specialization of `reference_wrapper`.

### unwrap_reference

    template<class T> class unwrap_reference<T const>
    {
     public:
        typedef unspecified type;
    };

`type` is equivalent to `T::type` if `T` is a specialization of `reference_wrapper`. Otherwise `type` is equivalent to `T`.

## Acknowledgements

ref and cref were originally part of the Boost.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`.

Copyright © 2001 by Peter Dimov and Multi Media Ltd. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.