| <!-- |
| 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& (*)(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> |
