| Brian Silverman | 407d3cd | 2018-08-04 17:48:52 -0700 | [diff] [blame^] | 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] |