feedc0de/boost_bind
1
0
Fork 0
forked from boostorg/bind
Code Pull Requests Activity

Import of BoostBook documentation for any, array, bind, function, ref, and

Browse Source 
signals libraries.


[SVN r17866]
This commit is contained in:
Douglas Gregor
2003-03-12 23:27:25 +00:00
parent c9db3c51ea
commit 81c8af90ec
1 changed files with 222 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
doc/ref.xml Normal file
View File

@@ -0,0 +1,222 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<library name="Ref" dirname="ref" id="ref" last-revision="$Date$">
<libraryinfo>
<author>
<firstname>Jaakko</firstname>
<surname>J&auml;rvi</surname>
</author>
<author>
<firstname>Peter</firstname>
<surname>Dimov</surname>
</author>
<author>
<firstname>Douglas</firstname>
<surname>Gregor</surname>
</author>
<author>
<firstname>Dave</firstname>
<surname>Abrahams</surname>
</author>
<copyright>
<year>1999</year>
<year>2000</year>
<holder>Jaakko J&auml;rvi</holder>
</copyright>
<copyright>
<year>2001</year>
<year>2002</year>
<holder>Peter Dimov</holder>
</copyright>
<copyright>
<year>2002</year>
<holder>David Abrahams</holder>
</copyright>
<legalnotice>
<para>Permission to copy, use, modify, sell and distribute this
software is granted provided this copyright notice appears in
all copies. This software is provided "as is" without express
or implied warranty, and with no claim as to its suitability for
any purpose.
</para>
</legalnotice>
<librarypurpose>A utility library for passing references to generic functions</librarypurpose>
<librarycategory name="category:higher-order"/>
</libraryinfo>
<title>Boost.Ref</title>
<section id="ref.intro">
<title>Introduction</title>
<using-namespace name="boost"/>
<para>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
<code><classname>boost::reference_wrapper&lt;T&gt;</classname></code>,
the two functions
<code><functionname>boost::ref</functionname></code> and
<code><functionname>boost::cref</functionname></code> that return
instances of <code>boost::reference_wrapper&lt;T&gt;</code>, and the
two traits classes
<code><classname>boost::is_reference_wrapper&lt;T&gt;</classname></code>
and
<code><classname>boost::unwrap_reference&lt;T&gt;</classname></code>.</para>
<para>The purpose of
<code>boost::reference_wrapper&lt;T&gt;</code> 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.</para>
<para>To support this usage,
<code>boost::reference_wrapper&lt;T&gt;</code> provides an implicit
conversion to <code>T&amp;</code>. This usually allows the function
templates to work on references unmodified.</para>
<para><code>boost::reference_wrapper&lt;T&gt;</code> is
both CopyConstructible and Assignable (ordinary references are not
Assignable).</para>
<para>The expression <code>boost::ref(x)</code>
returns a
<code>boost::reference_wrapper&lt;X&gt;(x)</code> where X
is the type of x. Similarly,
<code>boost::cref(x)</code> returns a
<code>boost::reference_wrapper&lt;X const&gt;(x)</code>.</para>
<para>The expression
<code>boost::is_reference_wrapper&lt;T&gt;::value</code>
is true if T is a <code>reference_wrapper</code>, and
false otherwise.</para>
<para>The type-expression
<code>boost::unwrap_reference&lt;T&gt;::type</code> is T::type if T
is a <code>reference_wrapper</code>, T otherwise.</para>
</section>
<library-reference>
<header name="boost/ref.hpp">
<namespace name="boost">
<class name="reference_wrapper">
<template>
<template-type-parameter name="T"/>
</template>
<purpose>
Contains a reference to an object of type
<computeroutput>T</computeroutput>.
</purpose>
<para>
<computeroutput><classname>reference_wrapper</classname></computeroutput>
is primarily used to "feed" references to function templates
(algorithms) that take their parameter by value. It provides
an implicit conversion to
<computeroutput>T&amp;</computeroutput>, which usually allows
the function templates to work on references unmodified.
</para>
<typedef type="T" name="type"/>
<constructor>
<parameter name="t">
<paramtype>T&amp;</paramtype>
</parameter>
<effects><para>Constructs a
<computeroutput><classname>reference_wrapper</classname></computeroutput>
object that stores a reference to
<computeroutput>t</computeroutput>.</para></effects>
<throws><para>Does not throw.</para></throws>
</constructor>
<member-function-group name="access">
<method name="conversion-operator" return-type="T&amp;" cv="const">
<returns><para>The stored reference.</para></returns>
<throws><para>Does not throw.</para></throws>
</method>
<method name="get" return-type="T&amp;" cv="const">
<returns><para>The stored reference.</para></returns>
<throws><para>Does not throw.</para></throws>
</method>
<method name="get_pointer" return-type="T*" cv="const">
<returns><para>A pointer to the object referenced by the stored reference.</para></returns>
<throws><para>Does not throw.</para></throws>
</method>
</member-function-group>
<free-function-group name="constructors">
<function name="ref" return-type="reference_wrapper&lt;T&gt;">
<parameter name="t">
<paramtype>T&amp;</paramtype>
</parameter>
<returns><para><computeroutput><classname>reference_wrapper</classname>&lt;T&gt;(t)</computeroutput></para></returns>
<throws><para>Does not throw.</para></throws>
</function>
<function name="cref" return-type="reference_wrapper&lt;T const&gt;">
<parameter name="t">
<paramtype>T const&amp;</paramtype>
</parameter>
<returns><para><computeroutput><classname>reference_wrapper</classname>&lt;T const&gt;(t)</computeroutput></para></returns>
<throws><para>Does not throw.</para></throws>
</function>
</free-function-group>
</class>
<class name="is_reference_wrapper">
<template>
<template-type-parameter name="T"/>
</template>
<purpose>Determine if a type <computeroutput>T</computeroutput> is an instantiation of <computeroutput><classname>reference_wrapper</classname></computeroutput>.</purpose>
<para>The <computeroutput>value</computeroutput> static constant will be <computeroutput>true</computeroutput> iff the type <computeroutput>T</computeroutput> is a specialization of <computeroutput><classname>reference_wrapper</classname></computeroutput>.</para>
<static-constant type="bool" name="value" value="unspecified"/>
</class>
<class name="unwrap_reference">
<template>
<template-type-parameter name="T"/>
</template>
<purpose>Find the type in a <computeroutput><classname>reference_wrapper</classname></computeroutput>.</purpose>
<para>The typedef <computeroutput>type</computeroutput> is <computeroutput>T::type</computeroutput> if <computeroutput>T</computeroutput> is a <computeroutput><classname>reference_wrapper</classname></computeroutput>, <computeroutput>T</computeroutput> otherwise.</para>
<typedef type="unspecified" name="T"/>
</class>
</namespace>
</header>
</library-reference>
<section id="ref.ack">
<title>Acknowledgements</title>
<using-namespace name="boost"/>
<para><functionname>ref</functionname> and <functionname>cref</functionname>
were originally part of the <libraryname>Tuple</libraryname> library
by Jaakko J&auml;rvi. They were "promoted to boost:: status" by
Peter Dimov because they are generally useful. Douglas Gregor and
Dave Abrahams contributed
<classname>is_reference_wrapper</classname> and
<classname>unwrap_reference</classname>.</para>
</section>
</library>