<!--
    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>basic_stringbuf</TITLE>
<LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
<BODY BGCOLOR=#FFFFFF>
<A HREF="basic-string.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="basic-stringstream.html"><IMG SRC="images/bnext.gif" WIDTH=25 HEIGHT=21 ALT="Next file" BORDER=O></A><DIV CLASS="DOCUMENTNAME"><B>Apache C++ Standard Library Reference Guide</B></DIV>
<H2>basic_stringbuf</H2>
<P><B>Library:</B>&nbsp;&nbsp;<A HREF="2-11.html">Input/output</A></P>

<PRE><HR><B><I>basic_stringbuf</I></B> <IMG SRC="images/inherits.gif"> <B><I><A HREF="basic-streambuf.html">basic_streambuf</A></I></B><HR></PRE>

<UL>
<LI><A HREF="#sec1">Local Index</A></LI>
<LI><A HREF="#sec2">Summary</A></LI>
<LI><A HREF="#sec3">Synopsis</A></LI>
<LI><A HREF="#sec4">Description</A></LI>
<LI><A HREF="#sec5">Interface</A></LI>
<LI><A HREF="#sec6">Member Types</A></LI>
<LI><A HREF="#sec7">Nonmember Types</A></LI>
<LI><A HREF="#sec8">Constructors</A></LI>
<LI><A HREF="#sec9">Member Functions</A></LI>
<LI><A HREF="#sec10">Example</A></LI>
<LI><A HREF="#sec11">See Also</A></LI>
<LI><A HREF="#sec12">Standards Conformance</A></LI>
</UL>
<A NAME="sec1"><H3>Local Index</H3></A>
<H4>Members</H4>
<UL><TABLE CELLPADDING=3>
<TR><TD VALIGN=top>
<A HREF="#idx398">basic_stringbuf()</A><BR>
<A HREF="#idx391">char_type</A><BR>
<A HREF="#idx392">ios_type</A><BR>
<A HREF="#idx393">off_type</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx400">overflow()</A><BR>
<A HREF="#idx401">pbackfail()</A><BR>
<A HREF="#idx394">pos_type</A><BR>
<A HREF="#idx402">seekoff()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx403">seekpos()</A><BR>
<A HREF="#idx404">setbuf()</A><BR>
<A HREF="#idx405">str()</A><BR>
<A HREF="#idx395">traits_type</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx407">underflow()</A><BR>
<A HREF="#idx408">xsputn()</A><BR>
</TD></TR>
</TABLE></UL>
<H4>Non-Members</H4>
<UL><TABLE CELLPADDING=3>
<TR><TD VALIGN=top>
<A HREF="#idx396">stringbuf</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx397">wstringbuf</A><BR>
</TD>
<TD VALIGN=top></TD></TR>
</TABLE></UL>

<A NAME="sec2"><H3>Summary</H3></A>
<P>Class that associates the input or output sequence with a sequence of arbitrary characters</P>
<A NAME="sec3"><H3>Synopsis</H3></A>

<PRE>#include &lt;sstream&gt; 

namespace std {
  template&lt;class charT, class traits = char_traits&lt;charT&gt;,
           class Allocator = allocator&lt;charT&gt; &gt;
  class basic_stringbuf;
}
</PRE>
<A NAME="sec4"><H3>Description</H3></A>
<P>The class <B><I>basic_stringbuf</I></B> is derived from <B><I><A HREF="basic-streambuf.html">basic_streambuf</A></I></B>. Its purpose is to associate the input or output sequence with a sequence of arbitrary characters. The sequence can be initialized from, or made available as, an object of class <B><I><A HREF="basic-string.html">basic_string</A></I></B>. Each object of type <B><I>basic_stringbuf</I></B> controls two character sequences:</P>
<UL>
<LI><P CLASS="LIST">a character input sequence</P></LI>
<LI><P CLASS="LIST">a character output sequence</P></LI>
</UL>
<P>See <B><I><A HREF="basic-streambuf.html">basic_streambuf</A></I></B> for more information.</P>
<P>The two sequences are related to each other, but are manipulated separately. This allows you to read and write characters at different positions in objects of type <B><I>basic_stringbuf</I></B> without any conflict (as opposed to the <B><I><A HREF="basic-filebuf.html">basic_filebuf</A></I></B> objects, in which a joint file position is maintained).</P>
<A NAME="sec5"><H3>Interface</H3></A>

<UL><PRE>namespace std {
 
  template&lt;class charT, class traits = char_traits&lt;charT&gt;,
           class allocator&lt;charT&gt; &gt;
  class basic_stringbuf 
  : public basic_streambuf&lt;charT, traits&gt; 
  {
    public:

     typedef charT                        char_type;
     typedef typename traits::int_type    int_type;
     typedef typename traits::pos_type    pos_type;
     typedef typename traits::off_type    off_type;

     explicit basic_stringbuf(ios_base::openmode =
                                (ios_base::in | ios_base::out));
     
   explicit basic_stringbuf(const basic_string&lt;char_type,
                            traits_type, Allocator&gt;&amp;,
                            ios_base::openmode = 
                            ios_base::in | ios_base::out);     
   basic_string&lt;char_type, traits_type, Allocator&gt; str() const;    
   void str(const basic_string&lt;char_type, traits_type, Allocator&gt;&amp;);

   protected:

   virtual int_type underflow();
   virtual int_type pbackfail(int_type = traits::eof());
   virtual int_type overflow(int_type = traits::eof());
   virtual basic_streambuf&lt;char_type, traits_type&gt;* 
   setbuf(char_type*,streamsize); 
   virtual pos_type seekoff(off_type, ios_base::seekdir,  
             ios_base::openmode = ios_base::in | ios_base::out);
   virtual pos_type seekpos(pos_type, 
             ios_base::openmode = ios_base::in | ios_base::out);
   virtual streamsize xsputn(const char_type*, streamsize); 
  };
}
</PRE></UL>
<A NAME="sec6"><H3>Member Types</H3></A>

<A NAME="idx391"></A><PRE><B>char_type</B></PRE>
<UL>
<P>The type <SAMP>char_type</SAMP> is a synonym for the template parameter <SAMP>charT</SAMP>.</P>
</UL>


<A NAME="idx392"></A><PRE><B>ios_type</B></PRE>
<UL>
<P>The type <SAMP>ios_type</SAMP> is an instantiation of class <B><I><A HREF="basic-ios.html">basic_ios</A></I></B> on type <SAMP>charT</SAMP>.</P>
</UL>


<A NAME="idx393"></A><PRE><B>off_type</B></PRE>
<UL>
<P>The type <SAMP>off_type</SAMP> is a synonym of type <SAMP>traits::off_type</SAMP>.</P>
</UL>


<A NAME="idx394"></A><PRE><B>pos_type</B></PRE>
<UL>
<P>The type <SAMP>pos_type</SAMP> is a synonym of type <SAMP>traits::pos_type</SAMP>.</P>
</UL>


<A NAME="idx395"></A><PRE><B>traits_type</B></PRE>
<UL>
<P>The type <SAMP>traits_type</SAMP> is a synonym for the template parameter <SAMP>traits</SAMP>.</P>
</UL>

<A NAME="sec7"><H3>Nonmember Types</H3></A>

<A NAME="idx396"></A><PRE><B>stringbuf</B> </PRE>
<UL>
<P>The type <SAMP>stringbuf</SAMP> is a specialization of class template <SAMP>basic_stringbuf</SAMP> on type <SAMP>char</SAMP>:</P>
<P><SAMP>typedef basic_stringbuf&lt;char&gt; stringbuf;</SAMP></P>
</UL>


<A NAME="idx397"></A><PRE><B>wstringbuf</B></PRE>
<UL>
<P>The type <SAMP>wstringbuf</SAMP> is a specialization of class template  <SAMP>basic_stringbuf</SAMP> on type <SAMP>wchar_t</SAMP>:</P>
<P><SAMP>typedef basic_stringbuf&lt;wchar_t&gt; wstringbuf;</SAMP></P>
</UL>

<A NAME="sec8"><H3>Constructors</H3></A>

<A NAME="idx398"></A><PRE>explicit <B>basic_stringbuf</B>(ios_base::openmode which =
                ios_base::in | ios_base::out); </PRE>
<UL>
<P>Constructs an object of class <B><I>basic_stringbuf</I></B>, initializing the base class with <SAMP>basic_streambuf()</SAMP>, and initializing the open mode with <SAMP>which</SAMP>.</P>
</UL>


<A NAME="idx399"></A><PRE>explicit <B>basic_stringbuf</B>(const string_type&amp; str,
                ios_base::openmode which =
                ios_base::in | ios_base::out); </PRE>
<UL>
<P>Constructs an object of class <B><I>basic_stringbuf</I></B>, initializing the base class with <SAMP>basic_streambuf()</SAMP>, and initializing the open mode with <SAMP>which</SAMP>. The string object <SAMP>str</SAMP> is copied to the underlying buffer. </P>
</UL>

<UL>
<LI><P CLASS="LIST">If the opening mode is <SAMP>in</SAMP>, initializes the input sequence to point to the first character of the buffer. </P></LI>
<LI><P CLASS="LIST">If the opening mode is <SAMP>out</SAMP>, initializes the output sequence to point to the first character of the buffer. </P></LI>
<LI><P CLASS="LIST">If the opening mode is <SAMP>out&nbsp;|&nbsp;app</SAMP>, initializes the output sequence to point to the last character of the buffer. </P></LI>
</UL>
<A NAME="sec9"><H3>Member Functions</H3></A>

<A NAME="idx400"></A><PRE>int_type 
<B>overflow</B>(int_type c = traits_type::eof()); </PRE>
<UL>
<P>If the output sequence has a <SAMP>put</SAMP> position available, and <SAMP>c</SAMP> is not <SAMP>traits_type::eof()</SAMP>, this function writes <SAMP>c</SAMP> into it. If there is no position available, the function increases the size of the buffer by allocating more memory and then writes <SAMP>c</SAMP> at the new current <SAMP>put</SAMP> position. If the operation fails, the function returns <SAMP>traits_type::eof()</SAMP>. Otherwise, it returns <SAMP>traits_type::not_eof(c)</SAMP>.</P>
</UL>


<A NAME="idx401"></A><PRE>int_type 
<B>pbackfail</B>(int_type c = traits_type::eof()); </PRE>
<UL>
<P>Puts back the character designated by <SAMP>c</SAMP> into the input sequence. If <SAMP>traits_type::eq_int_type(c,traits_type::eof())</SAMP> returns <SAMP>true</SAMP>, the function moves the input sequence one position backward. If the operation fails, the function returns <SAMP>traits_type::eof()</SAMP>. Otherwise, it returns <SAMP>traits_type::not_eof(c)</SAMP>.</P>
</UL>


<A NAME="idx402"></A><PRE>pos_type 
<B>seekoff</B>(off_type off, ios_base::seekdir way,
        ios_base::openmode which = 
        ios_base::in | ios_base::out); </PRE>
<UL>
<P>If the open mode is <SAMP>in | out</SAMP>, this function alters the stream position of both the input and the output sequences. If the open mode is <SAMP>in</SAMP>, it alters the stream position of only the input sequence, and if it is <SAMP>out</SAMP>, it alters the stream position of only the output sequence. The new position is calculated by combining the two parameters, <SAMP>off</SAMP> (displacement) and <SAMP>way</SAMP> (reference point). If the current position of the sequence is invalid before repositioning, the operation fails and the return value is <SAMP>pos_type(off_type(-1))</SAMP>. Otherwise, the function returns the current new position.</P>
</UL>


<A NAME="idx403"></A><PRE>pos_type 
<B>seekpos</B>(pos_type sp,ios_base::openmode which = 
        ios_base::in | ios_base::out); </PRE>
<UL>
<P>If the open mode is <SAMP>in | out</SAMP>, the function alters the stream position of both the input and the output sequences. If the open mode is <SAMP>in</SAMP>, it alters the stream position of the input sequence only, and if the open mode is <SAMP>out</SAMP>, it alters the stream position of the output sequence only. If the current position of the sequence is invalid before repositioning, the operation fails and the return value is <SAMP>pos_type(off_type(-1))</SAMP>. Otherwise, the function returns the current new position.</P>
</UL>


<A NAME="idx404"></A><PRE>basic_streambuf&lt;charT,traits&gt;* 
<B>setbuf</B>(char_type* s, streamsize n); </PRE>
<UL>
<P>A stringbuf maintains an underlying character array for storing buffered characters. This function gives you a way to resize or replace that buffer, with certain restrictions.</P>
<P>First of all, <SAMP>n</SAMP> must be greater than the number of characters currently in the buffer. If <SAMP>n</SAMP> is too small, then <SAMP>setbuf()</SAMP> has no effect and returns a null pointer to indicate failure. </P>
<P>If <SAMP>n</SAMP> is large enough, this function has one of the following effects:</P>
<UL>
<LI><P CLASS="LIST">If <SAMP>s</SAMP> is not a null pointer, <SAMP>setbuf()</SAMP> copies the buffered contents of the <B><I><A HREF="basic-stringbuf.html">stringbuf</A></I></B> into the <SAMP>n</SAMP> character array starting at <SAMP>s,</SAMP> and installs <SAMP>s</SAMP> as the underlying character array used by the <B><I>stringbuf</I></B>.  <SAMP>s</SAMP> replaces the old underlying array. In this case, the function returns <SAMP>s</SAMP> on success or a null pointer on failure. The caller is responsible for deleting the buffer.</P></LI>
<LI><P CLASS="LIST">If <SAMP>s</SAMP> is a null pointer and <SAMP>n</SAMP> is <SAMP>0</SAMP>, the function has no effect. </P></LI>
<LI><P CLASS="LIST">If <SAMP>s</SAMP> is a null pointer,  <SAMP>setbuf()</SAMP> resizes the underlying character array to <SAMP>n</SAMP> characters. The function returns a pointer to the beginning of the resized array if the operation is successful, or a null pointer if not. The object is responsible for deleting the buffer.</P></LI>
</UL>
</UL>


<A NAME="idx405"></A><PRE>
basic_string&lt;char_type, traits_type, Allocator&gt;
<B>str</B>() const; </PRE>
<UL>
<P>Returns a string object of type <SAMP>basic_string&lt;char_type, traits_type, Allocator&gt;</SAMP>, whose content is a copy of the underlying buffer contents.</P>
</UL>


<A NAME="idx406"></A><PRE>void 
<B>str</B>(const basic_string&lt;char_type,<I> </I>traits_type,<I> </I>Allocator&gt;&amp;<I> </I>str);</PRE>
<UL>
<P>Clears the underlying buffer and copies the string object <SAMP>str</SAMP> into it. If the opening mode is <SAMP>in</SAMP>, initializes the input sequence to point to the first character of the buffer. If the opening mode is <SAMP>out</SAMP>, the function initializes the output sequence to point to the first character of the buffer. If the opening mode is <SAMP>out | app</SAMP>, it initializes the output sequence to point to the last character of the buffer. </P>
</UL>


<A NAME="idx407"></A><PRE>int_type 
<B>underflow</B>();</PRE>
<UL>
<P>If the input sequence has a read position available, returns the contents of this position. Otherwise, it tries to expand the input sequence to match the output sequence, and if possible returns the content of the new current position, <SAMP>traits_type::to_int_type(*gptr())</SAMP>. The function returns <SAMP>traits_type::eof()</SAMP> to indicate failure.</P>
</UL>


<A NAME="idx408"></A><PRE>streamsize 
<B>xsputn</B>(const char_type* s, streamsize n); </PRE>
<UL>
<P>Writes up to <SAMP>n</SAMP> characters to the output sequence. The characters written are obtained from successive elements of the array whose first element is designated by <SAMP>s</SAMP>. The function returns the number of characters written.</P>
</UL>

<A NAME="sec10"><H3>Example</H3></A>

<UL><PRE>//
//  stringbuf.cpp
//
 
#include &lt;iostream&gt;   // for cout, endl
#include &lt;sstream&gt;    // for istringstream, ostringstream
#include &lt;string&gt;     // for string


int main ()
{
    // create a read/write string-stream object on tiny char
    // and attach it to an ostringstream object
    std::ostringstream out_1 (std::ios::in | std::ios::out);

    // tie the istream object to the ostringstream object
    std::istream in_1 (out_1.rdbuf ());   

    // output to out_1
    out_1 &lt;&lt; "Here is the first ouput";

    // create a string object on tiny char 
    std::string string_ex = "L'heure est grave!";

    // open a read only stringstream object and initialize it
    std::istringstream in_2 (string_ex);

    // output in_1 to the standard output
    std::cout &lt;&lt; in_1.rdbuf () &lt;&lt; std::endl;

    // reposition in_1 at the beginning
    in_1.seekg (0);

    // output in_2 to the standard output
    std::cout &lt;&lt; in_2.rdbuf () &lt;&lt; std::endl;

    // reposition in_2 at the beginning
    in_2.seekg (0);

    // get the current put position (equivalent to 
    // out_1.tellp())
    std::stringbuf::pos_type pos =
        out_1.rdbuf ()-&gt;pubseekoff (0, std::ios::cur, 
                                    std::ios::out);

    // append the content of the stringbuf pointed to by in_2
    // to the one  pointed at by out_1
    out_1 &lt;&lt; ' ' &lt;&lt; in_2.rdbuf ();

    // output in_1 to the standard output
    std::cout &lt;&lt; in_1.rdbuf () &lt;&lt; std::endl;

    // position the get sequence (equivalent to 
    // in_1.seekg (pos))
    in_1.rdbuf ()-&gt;pubseekpos (pos, std::ios::in);

    // output "L'heure est grave!"
    std::cout &lt;&lt; in_1.rdbuf () &lt;&lt; std::endl;  

    return 0;
}


Program Output:
</PRE></UL>
<UL><PRE>Here is the first ouput
L'heure est grave!
Here is the first ouput L'heure est grave!
 L'heure est grave!

</PRE></UL>
<A NAME="sec11"><H3>See Also</H3></A>
<P><B><I><A HREF="char-traits.html">char_traits</A></I></B>, <B><I><A HREF="ios-base.html">ios_base</A></I></B>, <B><I><A HREF="basic-ios.html">basic_ios</A></I></B>, <B><I><A HREF="basic-streambuf.html">basic_streambuf</A></I></B>, <B><I><A HREF="basic-string.html">basic_string</A></I></B>, <B><I><A HREF="basic-istringstream.html">basic_istringstream</A></I></B>, <B><I><A HREF="basic-ostringstream.html">basic_ostringstream</A></I></B>, <B><I><A HREF="basic-stringstream.html">basic_stringstream</A></I></B></P>
<A NAME="sec12"><H3>Standards Conformance</H3></A>
<P><I>ISO/IEC 14882:1998 -- International Standard for Information Systems --Programming Language C++, Section 27.7.1</I></P>

<BR>
<HR>
<A HREF="basic-string.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="basic-stringstream.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>