Google Git
Sign in
apache / stdcxx / a835fdec38b5683ecb373b571d3302381b5613da / . / doc / stdlibref / functionobjects.html
blob: 931bd2aafc3cb4ab61b67db46dee879ea20ca953 [file] [log] [blame]
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed
with this work for additional information regarding copyright
ownership. The ASF licenses this file to you under the Apache
License, Version 2.0 (the License); you may not use this file
except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied. See the License for the specific language governing
permissions and limitations under the License.
Copyright 1999-2007 Rogue Wave Software, Inc.
-->
<HTML>
<HEAD>
<TITLE>Function Objects</TITLE>
<LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
<BODY BGCOLOR=#FFFFFF>
<A HREF="fstream-h.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="functional-h.html"><IMG SRC="images/bnext.gif" WIDTH=25 HEIGHT=21 ALT="Next file" BORDER=O></A><DIV CLASS="DOCUMENTNAME"><B>Apache C++ Standard Library Reference Guide</B></DIV>
<H2>Function Objects</H2>
<P><B>Library:</B>&nbsp;&nbsp;<A HREF="2-4.html">General utilities</A></P><UL>
<LI><A HREF="#sec1">Local Index</A></LI>
<LI><A HREF="#sec2">Summary</A></LI>
<LI><A HREF="#sec3">Synopsis</A></LI>
<LI><A HREF="#sec4">Description</A></LI>
<LI><A HREF="#sec5">Interface</A></LI>
<LI><A HREF="#sec6">Example</A></LI>
<LI><A HREF="#sec7">See Also</A></LI>
<LI><A HREF="#sec8">Standards Conformance</A></LI>
</UL>
<A NAME="sec1"><H3>Local Index</H3></A>
No Entries
<A NAME="sec2"><H3>Summary</H3></A>
<P>Objects with an <SAMP>operator()</SAMP> defined. They are used as arguments to templatized algorithms, in place of pointers to functions.</P>
<A NAME="sec3"><H3>Synopsis</H3></A>
<PRE>#include &lt;functional&gt;
</PRE>
<A NAME="sec4"><H3>Description</H3></A>
<P>Function objects are objects with an <SAMP>operator()</SAMP> defined. They are important for the effective use of the standard library's generic algorithms, because the interface for each algorithmic template can accept either an object with an <SAMP>operator()</SAMP> defined, or a pointer to a function. The C++ Standard Library includes both a standard set of function objects, and a pair of classes that you can use as the base for creating your own function objects.</P>
<P>Function objects that take one argument are called <I>unary function objects</I>. Unary function objects must include the typedefs <SAMP>argument_type</SAMP> and <SAMP>result_type</SAMP>. Similarly, function objects that take two arguments are called <I>binary function objects</I> and, as such, must include the typedefs <SAMP>first_argument_type</SAMP>, <SAMP>second_argument_type</SAMP>, and <SAMP>result_type</SAMP>. </P>
<P>The classes <B><I><A HREF="unary-function.html">unary_function</A></I></B> and <B><I><A HREF="binary-function.html">binary_function</A></I></B> make the task of creating templatized function objects easier. The necessary typedefs for a unary or binary function object are included by inheriting from the appropriate function object class.</P>
<P>The function objects in the C++ Standard Library are listed below, together with a brief description of their operation. This Reference Guide also includes an alphabetic entry for each function.</P>
<H4><A NAME="Table&nbsp;19">Table&nbsp;19: C++ Standard Library function objects and their operations</A></H4>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="3">
<tr><td valign=top><B>Name </B>
</td>
<td valign=top><B>Operation</B>
</td>
</tr>
<tr><td valign=top colspan=2 rowspan=1><P CLASS="TABLE"><SAMP>arithmetic functions</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>plus</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>addition x + y</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>minus</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>subtraction x - y</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>multiplies</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>multiplication x * y</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>divides</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>division x / y</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>modulus</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>remainder x % y</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>negate</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>negation - x</SAMP></P>
</td>
</tr>
<tr><td valign=top colspan=2 rowspan=1><P CLASS="TABLE"><SAMP>comparison functions</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>equal_to</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>equality test x == y</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>not_equal_to</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>inequality test x != y</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>greater</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>greater comparison x &gt; y</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>less</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>less-than comparison x &lt; y</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>greater_equal</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>greater than or equal comparison x &gt;= y</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>less_equal</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>less than or equal comparison x &lt;= y</SAMP></P>
</td>
</tr>
<tr><td valign=top colspan=2 rowspan=1><P CLASS="TABLE"><SAMP>logical functions</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>logical_and</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>logical conjunction x &amp;&amp; y</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>logical_or</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>logical disjunction x || y</SAMP></P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>logical_not</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE"><SAMP>logical negation ! x</SAMP></P>
</td>
</tr>
</TABLE>
<A NAME="sec5"><H3>Interface</H3></A>
<UL><PRE>namespace std {
template &lt;class Arg, class Result&gt;
struct unary_function{
typedef Arg argument_type;
typedef Result result_type;
};
template &lt;class Arg1, class Arg2, class Result&gt;
struct binary_function{
typedef Arg1 first_argument_type;
typedef Arg2 second_argument_type;
typedef Result result_type;
};
// Arithmetic Operations
template&lt;class T&gt;
struct plus : binary_function&lt;T, T, T&gt; {
T operator() (const T&amp;, const T&amp;) const;
};
template &lt;class T&gt;
struct minus : binary_function&lt;T, T, T&gt; {
T operator() (const T&amp;, const T&amp;) const;
};
template &lt;class T&gt;
struct multiplies : binary_function&lt;T, T, T&gt; {
T operator() (const T&amp;, const T&amp;) const;
};
template &lt;class T&gt;
struct divides : binary_function&lt;T, T, T&gt; {
T operator() (const T&amp;, const T&amp;) const;
};
template &lt;class T&gt;
struct modulus : binary_function&lt;T, T, T&gt; {
T operator() (const T&amp;, const T&amp;) const;
};
template &lt;class T&gt;
struct negate : unary_function&lt;T, T&gt; {
T operator() (const T&amp;) const;
};
// Comparisons
template &lt;class T&gt;
struct equal_to : binary_function&lt;T, T, bool&gt; {
bool operator() (const T&amp;, const T&amp;) const;
};
template &lt;class T&gt;
struct not_equal_to : binary_function&lt;T, T, bool&gt; {
bool operator() (const T&amp;, const T&amp;) const;
};
template &lt;class T&gt;
struct greater : binary_function&lt;T, T, bool&gt; {
bool operator() (const T&amp;, const T&amp;) const;
};
template &lt;class T&gt;
struct less : binary_function&lt;T, T, bool&gt; {
bool operator() (const T&amp;, const T&amp;) const;
};
template &lt;class T&gt;
struct greater_equal : binary_function&lt;T, T, bool&gt; {
bool operator() (const T&amp;, const T&amp;) const;
};
template &lt;class T&gt;
struct less_equal : binary_function&lt;T, T, bool&gt; {
bool operator() (const T&amp;, const T&amp;) const;
};
// Logical Comparisons
template &lt;class T&gt;
struct logical_and : binary_function&lt;T, T, bool&gt; {
bool operator() (const T&amp;, const T&amp;) const;
};
template &lt;class T&gt;
struct logical_or : binary_function&lt;T, T, bool&gt; {
bool operator() (const T&amp;, const T&amp;) const;
};
template &lt;class T&gt;
struct logical_not : unary_function&lt;T, T, bool&gt; {
bool operator() (const T&amp;, const T&amp;) const;
};
}
</PRE></UL>
<A NAME="sec6"><H3>Example</H3></A>
<UL><PRE>//
// funct_ob.cpp
//
#include &lt;algorithm&gt;
#include &lt;deque&gt;
#include &lt;functional&gt;
#include &lt;iostream&gt;
#include &lt;vector&gt;
// Create a new function object from unary_function.
template &lt;class Arg, class Result&gt;
struct factorial: public std::unary_function&lt;Arg, Result&gt;
{
Result operator() (const Arg &amp;arg) {
Result a = 1;
for (Arg i = 2; i &lt;= arg; i++)
a *= i;
return a;
}
};
int main ()
{
// Typedefs for convenience.
typedef std::deque&lt;int, std::allocator&lt;int&gt; &gt; deque;
typedef std::vector&lt;long, std::allocator&lt;long&gt; &gt; vector;
// Initialize a deque with an array of integers.
deque::value_type arr[] = { 1, 2, 3, 4, 5, 6, 7 };
deque d (arr, arr + sizeof arr / sizeof *arr);
// Create an empty vector to store the factorials.
vector v;
// Transform the numbers in the deque to their
// factorials and store in the vector.
std::transform(d.begin(), d.end(),
std::back_inserter(v),
factorial&lt;deque::value_type,
vector::value_type&gt;());
// Create an iterator to output deque elements.
std::ostream_iterator&lt;deque::value_type, char,
std::char_traits&lt;char&gt; &gt; outd(std::cout, " ");
// Print the results.
std::cout &lt;&lt; "The following numbers: \n ";
std::copy(d.begin(), d.end(), outd);
// Create an iterator to output vector elements.
std::ostream_iterator&lt;vector::value_type, char,
std::char_traits&lt;char&gt; &gt; outv(std::cout, " ");
std::cout &lt;&lt; std::endl;
std::cout &lt;&lt; "\nHave the factorials: \n ";
std::copy (v.begin(), v.end(), outv);
std::cout &lt;&lt; std::endl;
return 0;
}
Program Output:
</PRE></UL>
<UL><PRE>The following numbers:
1 2 3 4 5 6 7
Have the factorials:
1 2 6 24 120 720 5040
</PRE></UL>
<A NAME="sec7"><H3>See Also</H3></A>
<P><B><I><A HREF="binary-function.html">binary_function</A></I></B>, <B><I><A HREF="unary-function.html">unary_function</A></I></B></P>
<A NAME="sec8"><H3>Standards Conformance</H3></A>
<P><I>ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 20.3</I></P>
<BR>
<HR>
<A HREF="fstream-h.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="functional-h.html"><IMG SRC="images/bnext.gif" WIDTH=20 HEIGHT=21 ALT="Next file" BORDER=O></A>
<!-- Google Analytics tracking code -->
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-1775151-1";
urchinTracker();
</script>
<!-- end of Google Analytics tracking code -->
</BODY>
</HTML>