ceph/src/boost/libs/core/doc/ref.qbk

   1 [/
   2  /  Copyright (c) 2001, 2002, 2006 Peter Dimov
   3  /  Copyright (c) 2002 David Abrahams
   4  /  Copyright (c) 2002 Aleksey Gurtovoy
   5  /  Copyright (c) 2003, 2004 Douglas Gregor
   6  /  Copyright (c) 2009 Ronald Garcia
   7  /  Copyright (c) 2014 Glen Joseph Fernandes
   8  /
   9  / Distributed under the Boost Software License, Version 1.0. (See
  10  / accompanying file LICENSE_1_0.txt or copy at
  11  / http://www.boost.org/LICENSE_1_0.txt)
  12  /]
  13
  14 [section:ref ref]
  15
  16 [simplesect Authors]
  17
  18 * Jaakko J\u00E4rvi
  19 * Peter Dimov
  20 * Douglas Gregor
  21 * Dave Abrahams
  22 * Frank Mori Hess
  23 * Ronald Garcia
  24
  25 [endsimplesect]
  26
  27 [section Introduction]
  28
  29 The Ref library is a small library that is useful for passing
  30 references to function templates (algorithms) that would
  31 usually take copies of their arguments. It defines the class
  32 template `boost::reference_wrapper<T>`, two functions
  33 `boost::ref` and `boost::cref` that return instances of
  34 `boost::reference_wrapper<T>`, a function `boost::unwrap_ref`
  35 that unwraps a `boost::reference_wrapper<T>` or returns a
  36 reference to any other type of object, and the two traits
  37 classes `boost::is_reference_wrapper<T>` and
  38 `boost::unwrap_reference<T>`.
  39
  40 The purpose of `boost::reference_wrapper<T>` is to contain a
  41 reference to an object of type `T`. It is primarily used to
  42 "feed" references to function templates (algorithms) that take
  43 their parameter by value.
  44
  45 To support this usage, `boost::reference_wrapper<T>` provides
  46 an implicit conversion to `T&`. This usually allows the
  47 function templates to work on references unmodified.
  48
  49 `boost::reference_wrapper<T>` is both CopyConstructible and
  50 Assignable (ordinary references are not Assignable).
  51
  52 The `expression boost::ref(x)` returns a
  53 `boost::reference_wrapper<X>(x)` where `X` is the type of `x`.
  54 Similarly, `boost::cref(x)` returns a
  55 `boost::reference_wrapper<X const>(x)`.
  56
  57 The expression `boost::unwrap_ref(x)` returns a
  58 `boost::unwrap_reference<X>::type&` where `X` is the type of
  59 `x`.
  60
  61 The expression `boost::is_reference_wrapper<T>::value` is
  62 `true` if `T` is a `reference_wrapper`, and `false` otherwise.
  63
  64 The type-expression `boost::unwrap_reference<T>::type` is
  65 `T::type` if `T` is a `reference_wrapper`, `T` otherwise.
  66
  67 [endsect]
  68
  69 [xinclude ref_reference.xml]
  70
  71 [section Acknowledgments]
  72
  73 `ref` and `cref` were originally part of the Tuple library by
  74 Jaakko J\u00E4rvi. They were "promoted to `boost::` status" by
  75 Peter Dimov because they are generally useful. Douglas Gregor
  76 and Dave Abrahams contributed `is_reference_wrapper` and
  77 `unwrap_reference`. Frank Mori Hess and Ronald Garcia
  78 contributed `boost::unwrap_ref`.
  79
  80 [endsect]
  81
  82 [endsect]