From 84b855cd09a406abb0653a04b6e2f98cca001e04 Mon Sep 17 00:00:00 2001 From: Glen Fernandes Date: Wed, 4 Jun 2014 21:23:29 -0700 Subject: [PATCH] Add ref documentation and doxygen --- doc/Jamfile.v2 | 14 ++++++ doc/core.qbk | 12 ++++- doc/ref.qbk | 58 ++++++++++++++++++++++++ include/boost/core/ref.hpp | 93 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 176 insertions(+), 1 deletion(-) create mode 100644 doc/ref.qbk diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index c7b2d14..e39b821 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -5,14 +5,28 @@ # Version 1.0. (See accompanying file LICENSE_1_0.txt # or copy at http://boost.org/LICENSE_1_0.txt) +import doxygen ; import quickbook ; +doxygen ref_reference + : + [ glob ../../../boost/core/ref.hpp ] + : + ENABLE_PREPROCESSING=YES + EXPAND_ONLY_PREDEF=YES + EXTRACT_ALL=NO + EXTRACT_PRIVATE=NO + HIDE_UNDOC_MEMBERS=YES + MACRO_EXPANSION=YES + ; + xml core : core.qbk ; boostbook standalone : core : + ref_reference boost.root=http://boost.org/doc/libs/master generate.section.toc.level=1 toc.max.depth=1 diff --git a/doc/core.qbk b/doc/core.qbk index e2fd013..b6e9f4e 100644 --- a/doc/core.qbk +++ b/doc/core.qbk @@ -1,3 +1,12 @@ +[/ + Copyright (c) 2014 Glen Joseph Fernandes + glenfe at live dot com + + Distributed under the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt + or copy at http://boost.org/LICENSE_1_0.txt) +] + [library Boost.Core [quickbook 1.5] [id core] @@ -65,7 +74,7 @@ Currently, the Core library contains: [`boost::null_deleter`] ] [ - [ref] + [[link core.ref ref]] [`boost::ref`] ] [ @@ -89,5 +98,6 @@ Currently, the Core library contains: [include:core no_exceptions_support.qbk] [include:core noncopyable.qbk] [include:core null_deleter.qbk] +[include:core ref.qbk] [include:core scoped_enum.qbk] [include:core swap.qbk] diff --git a/doc/ref.qbk b/doc/ref.qbk new file mode 100644 index 0000000..777991f --- /dev/null +++ b/doc/ref.qbk @@ -0,0 +1,58 @@ +[section:ref Header ] + +[section Introduction] + +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`, two functions +`boost::ref` and `boost::cref` that return instances of +`boost::reference_wrapper`, a function `boost::unwrap_ref` +that unwraps a `boost::reference_wrapper` or returns a +reference to any other type of object, and the two traits +classes `boost::is_reference_wrapper` and +`boost::unwrap_reference`. + +The purpose of `boost::reference_wrapper` 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` provides +an implicit conversion to `T&`. This usually allows the +function templates to work on references unmodified. + +`boost::reference_wrapper` is both CopyConstructible and +Assignable (ordinary references are not Assignable). + +The `expression boost::ref(x)` returns a +`boost::reference_wrapper(x)` where `X` is the type of `x`. +Similarly, `boost::cref(x)` returns a +`boost::reference_wrapper(x)`. + +The expression `boost::unwrap_ref(x)` returns a +`boost::unwrap_reference::type&` where `X` is the type of +`x`. + +The expression `boost::is_reference_wrapper::value` is +`true` if `T` is a `reference_wrapper`, and `false` otherwise. + +The type-expression `boost::unwrap_reference::type` is +`T::type` if `T` is a `reference_wrapper`, `T` otherwise. + +[endsect] + +[xinclude ref_reference.xml] + +[section Acknowledgments] + +`ref` and `cref` were originally part of the Tuple library by +Jaakko J\u00E4rvi. 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`. + +[endsect] + +[endsect] diff --git a/include/boost/core/ref.hpp b/include/boost/core/ref.hpp index e3e6b80..2fd4dc8 100644 --- a/include/boost/core/ref.hpp +++ b/include/boost/core/ref.hpp @@ -18,6 +18,9 @@ // Copyright (C) 2001, 2002 Peter Dimov // Copyright (C) 2002 David Abrahams // +// Copyright (C) 2014 Glen Joseph Fernandes +// glenfe at live dot com +// // Distributed under the Boost Software License, Version 1.0. (See // accompanying file LICENSE_1_0.txt or copy at // http://www.boost.org/LICENSE_1_0.txt) @@ -25,22 +28,60 @@ // See http://www.boost.org/libs/bind/ref.html for documentation. // +/** + @file +*/ + +/** + Boost namespace. +*/ namespace boost { // reference_wrapper +/** + @brief Contains a reference to an object of type `T`. + + `reference_wrapper` is primarily used to "feed" references to + function templates (algorithms) that take their parameter by + value. It provides an implicit conversion to `T&`, which + usually allows the function templates to work on references + unmodified. +*/ template class reference_wrapper { public: + /** + Type `T`. + */ typedef T type; + /** + Constructs a `reference_wrapper` object that stores a + reference to `t`. + + @remark Does not throw. + */ BOOST_FORCEINLINE explicit reference_wrapper(T& t): t_(boost::addressof(t)) {} + /** + @return The stored reference. + @remark Does not throw. + */ BOOST_FORCEINLINE operator T& () const { return *t_; } + /** + @return The stored reference. + @remark Does not throw. + */ BOOST_FORCEINLINE T& get() const { return *t_; } + /** + @return A pointer to the object referenced by the stored + reference. + @remark Does not throw. + */ BOOST_FORCEINLINE T* get_pointer() const { return t_; } private: @@ -50,12 +91,22 @@ private: // ref +/** + @cond +*/ # if defined( __BORLANDC__ ) && BOOST_WORKAROUND( __BORLANDC__, BOOST_TESTED_AT(0x581) ) # define BOOST_REF_CONST # else # define BOOST_REF_CONST const # endif +/** + @endcond +*/ +/** + @return `reference_wrapper(t)` + @remark Does not throw. +*/ template BOOST_FORCEINLINE reference_wrapper BOOST_REF_CONST ref( T & t ) { return reference_wrapper(t); @@ -63,6 +114,10 @@ template BOOST_FORCEINLINE reference_wrapper BOOST_REF_CONST ref( T // cref +/** + @return `reference_wrapper(t)` + @remark Does not throw. +*/ template BOOST_FORCEINLINE reference_wrapper BOOST_REF_CONST cref( T const & t ) { return reference_wrapper(t); @@ -72,11 +127,21 @@ template BOOST_FORCEINLINE reference_wrapper BOOST_REF_CONST c // is_reference_wrapper +/** + @brief Determine if a type `T` is an instantiation of + `reference_wrapper`. + + The value static constant will be true if the type `T` is a + specialization of `reference_wrapper`. +*/ template struct is_reference_wrapper { BOOST_STATIC_CONSTANT( bool, value = false ); }; +/** + @cond +*/ template struct is_reference_wrapper< reference_wrapper > { BOOST_STATIC_CONSTANT( bool, value = true ); @@ -101,13 +166,27 @@ template struct is_reference_wrapper< reference_wrapper const vol #endif // !defined(BOOST_NO_CV_SPECIALIZATIONS) +/** + @endcond +*/ + + // unwrap_reference +/** + @brief Find the type in a `reference_wrapper`. + + The `typedef` type is `T::type` if `T` is a + `reference_wrapper`, `T` otherwise. +*/ template struct unwrap_reference { typedef T type; }; +/** + @cond +*/ template struct unwrap_reference< reference_wrapper > { typedef T type; @@ -132,8 +211,16 @@ template struct unwrap_reference< reference_wrapper const volatil #endif // !defined(BOOST_NO_CV_SPECIALIZATIONS) +/** + @endcond +*/ + // unwrap_ref +/** + @return `unwrap_reference::type&(t)` + @remark Does not throw. +*/ template BOOST_FORCEINLINE typename unwrap_reference::type& unwrap_ref( T & t ) { return t; @@ -141,10 +228,16 @@ template BOOST_FORCEINLINE typename unwrap_reference::type& unwrap_r // get_pointer +/** + @cond +*/ template BOOST_FORCEINLINE T* get_pointer( reference_wrapper const & r ) { return r.get_pointer(); } +/** + @endcond +*/ } // namespace boost