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

 <HTML>
 <HEAD>
 <TITLE>A Recap of Manipulators</TITLE>
 <LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
 <BODY BGCOLOR=#FFFFFF>
 <A HREF="33.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-2.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.1 A Recap of Manipulators</H2>
 <A NAME="idx798"><!></A>
 <P>We showed examples of manipulators in <A HREF="28-3.html">Section&nbsp;28.3</A>. There we learned that:</P>
 <UL>
 <LI><P CLASS="LIST">Manipulators are objects that can be inserted into or extracted from a stream.</P></LI>
 <LI><P CLASS="LIST">Such insertions and extractions have specific desirable side effects.</P></LI>
 </UL>
 <P>As a recap, here is a typical example of two manipulators:</P>

 <UL><PRE>
 std::cout &lt;&lt; std::setw(10) &lt;&lt; 10.55 &lt;&lt; std::endl;
 </PRE></UL>
 <P>The inserted objects <SAMP>std::setw(10)</SAMP> and <SAMP>std::endl</SAMP> are the manipulators. As its only side effect, the manipulator <SAMP>setw(10)</SAMP> sets the stream's field width to <SAMP>10</SAMP>. Similarly, the manipulator <SAMP>std::endl</SAMP> inserts the end of line character and flushes the output. </P>
 <A NAME="idx799"><!></A>
 <P>As we mentioned previously, extensibility is a major advantage of iostreams. We've seen in the previous <A HREF="32-3.html">Section&nbsp;32.3</A> how you can implement inserters and extractors for user-defined types that behave like the built-in input and output operations. Additionally, you can add user-defined manipulators that fit seamlessly into the iostreams framework. In this section, we show how to do this.</P>
 <A NAME="idx800"><!></A>
 <P>First of all, to be extracted or inserted, a manipulator must be an object of a type that we call <SAMP>manipT</SAMP>, for which overloaded versions of the shift operators exist. (Associated with the manipulator type <SAMP>manipT,</SAMP> there is usually a function called <SAMP>f</SAMP><SAMP><SUB>manipT</SUB></SAMP><SAMP>()</SAMP>that we explain in detail later.) Here's the pattern for the manipulator extractor:</P>

 <UL><PRE>
 template &lt;class charT, class Traits&gt;
 std::basic istream&lt;charT,Traits&gt;&amp;
 operator&gt;&gt;(std::basic istream&lt;charT,Traits&gt;&amp; istr,
            const manipT&amp; manip)
 {   return f<SUB>manipT</SUB>(istr, ...);   }
 </PRE></UL>
 <A NAME="idx801"><!></A>
 <P>With this extractor defined, you can extract a manipulator <SAMP>Manip</SAMP>, which is an object of type <SAMP>manipT</SAMP>, by simply saying:</P>

 <UL><PRE>
 std::cin &gt;&gt; Manip;
 </PRE></UL>
 <P>This results in a call to the <SAMP>operator&gt;&gt;()</SAMP> sketched out above. The manipulator inserter is analogous.</P>
 <P>A manipulator's side effect is often created by calling an associated function <SAMP>f</SAMP><SAMP><SUB>manipT</SUB></SAMP><SAMP>()</SAMP> that takes a stream and returns the stream. There are several ways to associate the manipulator type <SAMP>manipT</SAMP> to the function <SAMP>f</SAMP><SAMP><SUB>manipT</SUB></SAMP><SAMP>()</SAMP>, which we explore in the following sections. The iostream framework does not specify a way to implement manipulators, but there is a simple way to write your own manipulators. We explain this technique along with other useful approaches.</P>
 <P>It turns out that there is a major difference between manipulators with parameters like <SAMP>std::width(10)</SAMP> and manipulators without parameters like <SAMP>std::endl</SAMP>. Let's start with the simpler case of manipulators without parameters.</P>

 <BR>
 <HR>
 <A HREF="33.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-2.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>A Recap of Manipulators</TITLE>
	<LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
	<BODY BGCOLOR=#FFFFFF>
	<A HREF="33.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-2.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.1 A Recap of Manipulators</H2>
	<A NAME="idx798"><!></A>
	<P>We showed examples of manipulators in <A HREF="28-3.html">Section 28.3</A>. There we learned that:</P>
	<UL>
	<LI><P CLASS="LIST">Manipulators are objects that can be inserted into or extracted from a stream.</P></LI>
	<LI><P CLASS="LIST">Such insertions and extractions have specific desirable side effects.</P></LI>
	</UL>
	<P>As a recap, here is a typical example of two manipulators:</P>

	<UL><PRE>
	std::cout << std::setw(10) << 10.55 << std::endl;
	</PRE></UL>
	<P>The inserted objects <SAMP>std::setw(10)</SAMP> and <SAMP>std::endl</SAMP> are the manipulators. As its only side effect, the manipulator <SAMP>setw(10)</SAMP> sets the stream's field width to <SAMP>10</SAMP>. Similarly, the manipulator <SAMP>std::endl</SAMP> inserts the end of line character and flushes the output. </P>
	<A NAME="idx799"><!></A>
	<P>As we mentioned previously, extensibility is a major advantage of iostreams. We've seen in the previous <A HREF="32-3.html">Section 32.3</A> how you can implement inserters and extractors for user-defined types that behave like the built-in input and output operations. Additionally, you can add user-defined manipulators that fit seamlessly into the iostreams framework. In this section, we show how to do this.</P>
	<A NAME="idx800"><!></A>
	<P>First of all, to be extracted or inserted, a manipulator must be an object of a type that we call <SAMP>manipT</SAMP>, for which overloaded versions of the shift operators exist. (Associated with the manipulator type <SAMP>manipT,</SAMP> there is usually a function called <SAMP>f</SAMP><SAMP><SUB>manipT</SUB></SAMP><SAMP>()</SAMP>that we explain in detail later.) Here's the pattern for the manipulator extractor:</P>

	<UL><PRE>
	template <class charT, class Traits>
	std::basic istream<charT,Traits>&
	operator>>(std::basic istream<charT,Traits>& istr,
	const manipT& manip)
	{ return f<SUB>manipT</SUB>(istr, ...); }
	</PRE></UL>
	<A NAME="idx801"><!></A>
	<P>With this extractor defined, you can extract a manipulator <SAMP>Manip</SAMP>, which is an object of type <SAMP>manipT</SAMP>, by simply saying:</P>

	<UL><PRE>
	std::cin >> Manip;
	</PRE></UL>
	<P>This results in a call to the <SAMP>operator>>()</SAMP> sketched out above. The manipulator inserter is analogous.</P>
	<P>A manipulator's side effect is often created by calling an associated function <SAMP>f</SAMP><SAMP><SUB>manipT</SUB></SAMP><SAMP>()</SAMP> that takes a stream and returns the stream. There are several ways to associate the manipulator type <SAMP>manipT</SAMP> to the function <SAMP>f</SAMP><SAMP><SUB>manipT</SUB></SAMP><SAMP>()</SAMP>, which we explore in the following sections. The iostream framework does not specify a way to implement manipulators, but there is a simple way to write your own manipulators. We explain this technique along with other useful approaches.</P>
	<P>It turns out that there is a major difference between manipulators with parameters like <SAMP>std::width(10)</SAMP> and manipulators without parameters like <SAMP>std::endl</SAMP>. Let's start with the simpler case of manipulators without parameters.</P>

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