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

 <!--
     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>How the Standard Iostreams Work</TITLE>
 <LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
 <BODY BGCOLOR=#FFFFFF>
 <A HREF="27-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="27-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>27.2 How the Standard Iostreams Work</H2>
 <A NAME="idx620"><!></A>
 <P>The main purpose of the standard iostreams is to serve as a tool for input and output of data. Generally, input and output are the transfer of data between a program and any kind of external device, as illustrated in <A HREF="27-2.html#Figure&nbsp;17">Figure&nbsp;17</A>:</P>
 <A NAME="idx621"><!></A>
 <H4><A NAME="Figure&nbsp;17">Figure&nbsp;17: Data transfer supported by iostreams</A></H4>

 <P><IMG SRC="images/iofig1.gif" WIDTH=587 HEIGHT=300></P>
 <P>The internal representation of such data is meant to be convenient for data processing in a program. On the other hand, the external representation can vary quite a bit: it might be a display in human-readable form, or a portable data exchange format. The intent of a representation, such as conserving space for storage, can also influence the representation.</P>
 <A NAME="idx622"><!></A>
 <P><I>T</I><I>ext I/O</I> involves the external representation of a sequence of characters; every other case involves <I>binary I/O</I>. Traditionally, iostreams are used for text processing. Such text processing through iostreams involves two processes: <I>formatting</I> and <I>code conversion</I>.</P>
 <A NAME="idx623"><!></A>
 <P><I>Formatting</I> is the transformation from a byte sequence representing internal data into a human-readable character sequence; for example, from a floating point number, or an integer value held in a variable, into a sequence of digits. <A HREF="27-2.html#Figure&nbsp;18">Figure&nbsp;18</A> illustrates the formatting process:</P>
 <A NAME="idx624"><!></A>
 <H4><A NAME="Figure&nbsp;18">Figure&nbsp;18: Formatting program data</A></H4>

 <P><IMG SRC="images/iofig2.gif" WIDTH=680 HEIGHT=129></P>
 <A NAME="idx625"><!></A>
 <P><I>Code conversion</I> is the process of translating one character representation into another; for example, from wide characters held internally to a sequence of multibyte characters for external use. Wide characters are all the same size, and thus are convenient for internal data processing. Multibyte characters have different sizes and are stored more compactly. They are typically used for data transfer, or for storage on external devices such as files. <A HREF="27-2.html#Figure&nbsp;19">Figure&nbsp;19</A> illustrates the conversion process:</P>
 <A NAME="idx626"><!></A>
 <H4><A NAME="Figure&nbsp;19">Figure&nbsp;19: Code conversion between multibyte and wide characters</A></H4>

 <P><IMG SRC="images/iofig3.gif" WIDTH=548 HEIGHT=302></P>
 <A NAME="2721"><H3>27.2.1 The Iostream Layers</H3></A>
 <A NAME="idx627"><!></A>
 <P>The iostreams facility has two layers: one that handles formatting, and another that handles code conversion and transport of characters to and from the external device. The layers communicate through a buffer, as illustrated in <A HREF="27-2.html#Figure&nbsp;20">Figure&nbsp;20</A>:</P>
 <A NAME="idx628"><!></A>
 <H4><A NAME="Figure&nbsp;20">Figure&nbsp;20: The iostreams layers</A></H4>

 <P><IMG SRC="images/iofig4.gif" WIDTH=639 HEIGHT=98></P>
 <P>In the next sections we'll look at the function of each layer in more detail.</P>
 <A NAME="2721-1"><H4>27.2.1.1 The Formatting Layer</H4></A>
 <A NAME="idx629"><!></A>
 <P>In the formatting layer, the transformation between a program's internal data representation and a readable representation as a character sequence takes place. This formatting and parsing may involve, among other things:</P>
 <UL>
 <LI><P CLASS="LIST">Precision and notation of floating point numbers</P></LI>
 <LI><P CLASS="LIST">Hexadecimal, octal, or decimal representation of integers</P></LI>
 <LI><P CLASS="LIST">Skipping of white space in the input</P></LI>
 <LI><P CLASS="LIST">Field width for output</P></LI>
 <LI><P CLASS="LIST">Adapting of number formatting to local conventions</P></LI>
 </UL>
 <A NAME="2721-2"><H4>27.2.1.2 The Transport Layer</H4></A>
 <A NAME="idx630"><!></A>
 <P>The transport layer is responsible for producing and consuming characters. It encapsulates knowledge about the properties of a specific external device. Among other things, this involves:</P>
 <UL>
 <LI><P CLASS="LIST">Block-wise output to files through system calls</P></LI>
 <LI><P CLASS="LIST">Code conversion to multibyte encodings</P></LI>
 <P CLASS="LIST">To reduce the number of accesses to the external device, a buffer is used. For output, the formatting layer sends sequences of characters to the transport layer, which stores them in a <I>stream buffer</I>. The actual transport to the external device happens only when the buffer is full or explicitly flushed. For input, the transport layer reads from the external device and fills the buffer. The formatting layer receives characters from the buffer. When the buffer is empty, the transport layer is responsible for refilling it.</P>
 </UL>
 <A NAME="2721-3"><H4>27.2.1.3 Locales</H4></A>
 <A NAME="idx631"><!></A>
 <P>Both the formatting and the transport layers use the stream's locale. The formatting layer delegates the handling of numeric entities to the locale's numeric facets. The transport layer uses the locale's code conversion facet for character-wise transformation between the buffer content and characters transported to and from the external device. <A HREF="27-2.html#Figure&nbsp;21">Figure&nbsp;21</A> shows how locales are used with iostreams:</P>
 <A NAME="idx632"><!></A>
 <H4><A NAME="Figure&nbsp;21">Figure&nbsp;21: Use of locales in iostreams</A></H4>

 <P><IMG SRC="images/iofig5.gif" WIDTH=689 HEIGHT=206></P>
 <A NAME="2722"><H3>27.2.2 File and In-Memory I/O</H3></A>
 <P>Iostreams support two kinds of I/O: file I/O and in-memory I/O.</P>
 <A NAME="idx633"><!></A>
 <P><I>File I/O</I> involves the transfer of data to and from an external device. The device need not necessarily be a file in the usual sense of the word. It could just as well be a communication channel, or another construct that conforms to the file abstraction.</P>
 <A NAME="idx634"><!></A>
 <P>In contrast, <I>in-memory I/O</I> involves no external device. Thus code conversion and transport are not necessary; only formatting is performed. The result of such formatting is maintained in memory, and can be retrieved in the form of a character string.</P>

 <BR>
 <HR>
 <A HREF="27-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="27-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>
	<!--
	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>How the Standard Iostreams Work</TITLE>
	<LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
	<BODY BGCOLOR=#FFFFFF>
	<A HREF="27-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="27-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>27.2 How the Standard Iostreams Work</H2>
	<A NAME="idx620"><!></A>
	<P>The main purpose of the standard iostreams is to serve as a tool for input and output of data. Generally, input and output are the transfer of data between a program and any kind of external device, as illustrated in <A HREF="27-2.html#Figure 17">Figure 17</A>:</P>
	<A NAME="idx621"><!></A>
	<H4><A NAME="Figure 17">Figure 17: Data transfer supported by iostreams</A></H4>

	<P><IMG SRC="images/iofig1.gif" WIDTH=587 HEIGHT=300></P>
	<P>The internal representation of such data is meant to be convenient for data processing in a program. On the other hand, the external representation can vary quite a bit: it might be a display in human-readable form, or a portable data exchange format. The intent of a representation, such as conserving space for storage, can also influence the representation.</P>
	<A NAME="idx622"><!></A>
	<P><I>T</I><I>ext I/O</I> involves the external representation of a sequence of characters; every other case involves <I>binary I/O</I>. Traditionally, iostreams are used for text processing. Such text processing through iostreams involves two processes: <I>formatting</I> and <I>code conversion</I>.</P>
	<A NAME="idx623"><!></A>
	<P><I>Formatting</I> is the transformation from a byte sequence representing internal data into a human-readable character sequence; for example, from a floating point number, or an integer value held in a variable, into a sequence of digits. <A HREF="27-2.html#Figure 18">Figure 18</A> illustrates the formatting process:</P>
	<A NAME="idx624"><!></A>
	<H4><A NAME="Figure 18">Figure 18: Formatting program data</A></H4>

	<P><IMG SRC="images/iofig2.gif" WIDTH=680 HEIGHT=129></P>
	<A NAME="idx625"><!></A>
	<P><I>Code conversion</I> is the process of translating one character representation into another; for example, from wide characters held internally to a sequence of multibyte characters for external use. Wide characters are all the same size, and thus are convenient for internal data processing. Multibyte characters have different sizes and are stored more compactly. They are typically used for data transfer, or for storage on external devices such as files. <A HREF="27-2.html#Figure 19">Figure 19</A> illustrates the conversion process:</P>
	<A NAME="idx626"><!></A>
	<H4><A NAME="Figure 19">Figure 19: Code conversion between multibyte and wide characters</A></H4>

	<P><IMG SRC="images/iofig3.gif" WIDTH=548 HEIGHT=302></P>
	<A NAME="2721"><H3>27.2.1 The Iostream Layers</H3></A>
	<A NAME="idx627"><!></A>
	<P>The iostreams facility has two layers: one that handles formatting, and another that handles code conversion and transport of characters to and from the external device. The layers communicate through a buffer, as illustrated in <A HREF="27-2.html#Figure 20">Figure 20</A>:</P>
	<A NAME="idx628"><!></A>
	<H4><A NAME="Figure 20">Figure 20: The iostreams layers</A></H4>

	<P><IMG SRC="images/iofig4.gif" WIDTH=639 HEIGHT=98></P>
	<P>In the next sections we'll look at the function of each layer in more detail.</P>
	<A NAME="2721-1"><H4>27.2.1.1 The Formatting Layer</H4></A>
	<A NAME="idx629"><!></A>
	<P>In the formatting layer, the transformation between a program's internal data representation and a readable representation as a character sequence takes place. This formatting and parsing may involve, among other things:</P>
	<UL>
	<LI><P CLASS="LIST">Precision and notation of floating point numbers</P></LI>
	<LI><P CLASS="LIST">Hexadecimal, octal, or decimal representation of integers</P></LI>
	<LI><P CLASS="LIST">Skipping of white space in the input</P></LI>
	<LI><P CLASS="LIST">Field width for output</P></LI>
	<LI><P CLASS="LIST">Adapting of number formatting to local conventions</P></LI>
	</UL>
	<A NAME="2721-2"><H4>27.2.1.2 The Transport Layer</H4></A>
	<A NAME="idx630"><!></A>
	<P>The transport layer is responsible for producing and consuming characters. It encapsulates knowledge about the properties of a specific external device. Among other things, this involves:</P>
	<UL>
	<LI><P CLASS="LIST">Block-wise output to files through system calls</P></LI>
	<LI><P CLASS="LIST">Code conversion to multibyte encodings</P></LI>
	<P CLASS="LIST">To reduce the number of accesses to the external device, a buffer is used. For output, the formatting layer sends sequences of characters to the transport layer, which stores them in a <I>stream buffer</I>. The actual transport to the external device happens only when the buffer is full or explicitly flushed. For input, the transport layer reads from the external device and fills the buffer. The formatting layer receives characters from the buffer. When the buffer is empty, the transport layer is responsible for refilling it.</P>
	</UL>
	<A NAME="2721-3"><H4>27.2.1.3 Locales</H4></A>
	<A NAME="idx631"><!></A>
	<P>Both the formatting and the transport layers use the stream's locale. The formatting layer delegates the handling of numeric entities to the locale's numeric facets. The transport layer uses the locale's code conversion facet for character-wise transformation between the buffer content and characters transported to and from the external device. <A HREF="27-2.html#Figure 21">Figure 21</A> shows how locales are used with iostreams:</P>
	<A NAME="idx632"><!></A>
	<H4><A NAME="Figure 21">Figure 21: Use of locales in iostreams</A></H4>

	<P><IMG SRC="images/iofig5.gif" WIDTH=689 HEIGHT=206></P>
	<A NAME="2722"><H3>27.2.2 File and In-Memory I/O</H3></A>
	<P>Iostreams support two kinds of I/O: file I/O and in-memory I/O.</P>
	<A NAME="idx633"><!></A>
	<P><I>File I/O</I> involves the transfer of data to and from an external device. The device need not necessarily be a file in the usual sense of the word. It could just as well be a communication channel, or another construct that conforms to the file abstraction.</P>
	<A NAME="idx634"><!></A>
	<P>In contrast, <I>in-memory I/O</I> involves no external device. Thus code conversion and transport are not necessary; only formatting is performed. The result of such formatting is maintained in memory, and can be retrieved in the form of a character string.</P>

	<BR>
	<HR>
	<A HREF="27-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="27-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>