doc/stdlibug/33-2.html - stdcxx - Git at Google

 <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>
	<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& (*)(std::ios_base&)
	(2) std::basic_ios<>& (*)(std::basic_ios<>&)
	(3) std::basic_istream<>& (*)(std::basic_istream<>&)
	(4) std::basic_ostream<>& (*)(std::basic_ostream<>&)
	</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<class charT, class traits>
	std::basic_istream<charT, traits>&
	std::basic_istream<charT, traits>::operator>>
	(<I>input_stream_type</I>& (*pf)(<I>input_stream_type</I>&) )
	{ 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<class charT, class traits>
	std::basic_ostream<charT, traits>&
	std::basic_ostream<charT, traits>::operator<<
	(<I>output_stream_type</I>& (*pf)(<I>output_stream_type</I>&))
	{ 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<class charT, class traits>
	std::basic_ostream<charT, traits>&
	std::endl(std::basic_ostream<charT, traits>& os)
	{
	return os.put(os.widen('\n')).flush();
	}
	</PRE></UL>
	<P>Hence an expression like: </P>

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

	<UL><PRE>
	std::ostream& std::ostream::operator<<(std::ostream&
	(*pf)(std::ostream&))
	</PRE></UL>
	<P>with<SAMP> std::endl</SAMP> as the actual argument for <SAMP>pf</SAMP>. In other words, <SAMP>std::cout << std::endl;</SAMP> is equivalent to <SAMP>std::cout.operator<<(std::endl)</SAMP>. That is, inserting <SAMP>endl </SAMP>into a stream is really inserting the address of the template specialization <SAMP>std::endl<char, std::char_traits<char> ></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<wchar_t, std::char_traits<wchar_t> ></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& boolalpha(std::ios_base& 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 << "Hello world" << 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>