<!--
    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>Manipulators without Parameters</TITLE>
<LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
<BODY BGCOLOR=#FFFFFF>
<A HREF="33-1.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="33-3.html"><IMG SRC="images/bnext.gif" WIDTH=25 HEIGHT=21 ALT="Next file" BORDER=O></A><DIV CLASS="DOCUMENTNAME"><B>Apache C++ Standard Library User's Guide</B></DIV>
<H2>33.2 Manipulators without Parameters</H2>
<A NAME="idx802"><!></A>
<P>Manipulators that do not have any parameters, like <SAMP>endl</SAMP>, are the simplest form of manipulator. The manipulator type <SAMP>manipT</SAMP> is a function pointer type, the manipulator <SAMP>Manip</SAMP> is the function pointer, and the associated function <SAMP>f</SAMP><SAMP><SUB>manipT</SUB></SAMP><SAMP>()</SAMP> is the function pointed to.</P>
<A NAME="idx803"><!></A>
<P>In iostreams, the following function pointer types serve as manipulators:</P>

<UL><PRE>
(1) std::ios_base&amp;        (*)(std::ios_base&amp;)
(2) std::basic_ios&lt;&gt;&amp;     (*)(std::basic_ios&lt;&gt;&amp;)
(3) std::basic_istream&lt;&gt;&amp; (*)(std::basic_istream&lt;&gt;&amp;)
(4) std::basic_ostream&lt;&gt;&amp; (*)(std::basic_ostream&lt;&gt;&amp;)
</PRE></UL>
<P>The signature of a manipulator function is not limited to the examples above. If you have created your own stream types, you will certainly want to use additional signatures as manipulators.</P>
<A NAME="idx804"><!></A>
<P>For the four manipulator types listed above, the stream classes already offer the required overloaded inserters and member functions. For input streams, extractors take the following form:</P>

<UL><PRE>
template&lt;class charT, class traits&gt;
std::basic_istream&lt;charT, traits&gt;&amp;
std::basic_istream&lt;charT, traits&gt;::operator&gt;&gt;
(<I>input_stream_type</I>&amp; (*pf)(<I>input_stream_type</I>&amp;) )
{  return (*pf)(*this); }
</PRE></UL>
<P>where the type of the argument <SAMP>pf</SAMP> is one of types (1) -- (3).</P>
<A NAME="idx805"><!></A>
<P>Similarly, for output streams we have:</P>

<UL><PRE>
template&lt;class charT, class traits&gt;
std::basic_ostream&lt;charT, traits&gt;&amp;
std::basic_ostream&lt;charT, traits&gt;::operator&lt;&lt;
(<I>output_stream_type</I>&amp; (*pf)(<I>output_stream_type</I>&amp;))
{  return (*pf)(*this);  }
</PRE></UL>
<P>where the type of the argument <SAMP>pf</SAMP> is one of the types (1), (2), or (4).</P>
<A NAME="3321"><H3>33.2.1 Examples of Manipulators without Parameters</H3></A>
<A NAME="idx806"><!></A>
<P>Let's look at the manipulator <SAMP>endl</SAMP> as an example of a manipulator without parameters. The manipulator <SAMP>endl</SAMP>, which can be applied solely to output streams, is a pointer to the following function of type (4):</P>

<UL><PRE>
template&lt;class charT, class traits&gt;
std::basic_ostream&lt;charT, traits&gt;&amp;
std::endl(std::basic_ostream&lt;charT, traits&gt;&amp; os)
{
  return os.put(os.widen('\n')).flush();
}
</PRE></UL>
<P>Hence an expression like: </P>

<UL><PRE>
std::cout &lt;&lt; std::endl; 
</PRE></UL>
<P>results in a call to the inserter:</P>

<UL><PRE>
std::ostream&amp; std::ostream::operator&lt;&lt;(std::ostream&amp;
   (*pf)(std::ostream&amp;))
</PRE></UL>
<P>with<SAMP> std::endl</SAMP> as the actual argument for <SAMP>pf</SAMP>. In other words, <SAMP>std::cout &lt;&lt; std::endl;</SAMP> is equivalent to <SAMP>std::cout.operator&lt;&lt;(std::endl)</SAMP>. That is, inserting <SAMP>endl </SAMP>into a stream is really inserting the address of the template specialization <SAMP>std::endl&lt;char, std::char_traits&lt;char&gt; &gt;</SAMP> into the stream object <SAMP>std::cout</SAMP>. Inserting <SAMP>endl</SAMP> into the standard wide character stream object <SAMP>std::wcout</SAMP> inserts the address of the specialization of the same template on <SAMP>wchar_t</SAMP>, or <SAMP>std::endl&lt;wchar_t, std::char_traits&lt;wchar_t&gt; &gt;</SAMP>. Thanks to template argument deduction one need not bother to specify the actual template arguments.</P>
<A NAME="idx807"><!></A>
<P>Here is another manipulator, <SAMP>std::boolalpha</SAMP>, that can be applied to input <I>and</I> output streams. The manipulator <SAMP>boolalpha</SAMP> is a pointer to a function of type (1), since all it needs to access is the state encapsulated in the <SAMP>ios_base</SAMP> part of the stream object:</P>

<UL><PRE>
std::ios_base&amp; boolalpha(std::ios_base&amp; strm)
{
  strm.setf(std::ios_base::boolalpha);
 
  return strm;
}
</PRE></UL>
<A NAME="idx808"><!></A>
<BLOCKQUOTE><HR><B>
NOTE --  Every function that takes a reference to an <SAMP>ios_base</SAMP>, a <SAMP>basic_ios</SAMP>, a <SAMP>basic_ostream</SAMP>, or a <SAMP>basic_istream</SAMP>, and returns a reference to the same stream, can be used as a parameter-less manipulator.
</B><HR></BLOCKQUOTE>
<A NAME="3322"><H3>33.2.2 A Remark on the Manipulator endl</H3></A>
<A NAME="idx809"><!></A>
<P>The manipulator<SAMP> std::endl</SAMP> is often used for inserting the end-of-line character into a stream. However, <SAMP>endl</SAMP> does additionally flush the output stream, as you can see from the implementation of <SAMP>endl</SAMP> shown above. Flushing a stream, a relatively time-consuming operation that decreases performance, is unnecessary in most common situations. In the standard example:</P>

<UL><PRE>
std::cout &lt;&lt; "Hello world" &lt;&lt; std::endl;
</PRE></UL>
<P>flushing is not necessary because the standard output stream <SAMP>cout</SAMP> is flushed automatically during program termination. Since no flush is required, the intent is probably to insert the end-of-line character. If you consider typing <SAMP>'\n'</SAMP> more trouble than typing <SAMP>endl</SAMP>, you can easily add a simple manipulator <SAMP>nl</SAMP> that inserts the end-of-line character, but refrains from flushing the stream.</P>

<BR>
<HR>
<A HREF="33-1.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="33-3.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>