Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

ref

Introduction
Reference
Acknowledgements

Authors

  • Jaakko Järvi
  • Peter Dimov
  • Douglas Gregor
  • Dave Abrahams
  • Frank Mori Hess
  • Ronald Garcia

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.

Reference

namespace boost {
  template<typename T> struct is_reference_wrapper;

  template<typename T> class reference_wrapper;

  template<typename T> struct unwrap_reference;
  template<typename T> reference_wrapper< T > const ref(T &);
  template<typename T> reference_wrapper< T const > const cref(T const &);
  template<typename T> void ref(T const &&);
  template<typename T> void cref(T const &&);
  template<typename T> unwrap_reference< T >::type & unwrap_ref(T &);
}

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.


PrevUpHomeNext