c++boost.gif (8819 bytes)

ref.hpp

 1.00.0004 (2002-01-27)
 

Files

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.