Standard C++ Library
Copyright 1998, Rogue Wave Software, Inc.
NAME
basic_stringbuf, stringbuf, wstringbuf
- Associates the input or output sequence with a sequence
of arbitrary characters.
SYNOPSIS
#include <sstream>
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<charT> >
class basic_stringbuf
: public basic_streambuf<charT, traits>
DESCRIPTION
The class basic_stringbuf is derived from basic_streambuf.
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
basic_string. Each object of type
basic_stringbuf<charT,_traits,Allocator> controls two char-
acter sequences:
o A character input sequence;
o A character output sequence.
Note: see basic_streambuf.
The two sequences are related to each other, but are manipu-
lated separately. This allows you to read and write charac-
ters at different positions in objects of type
basic_stringbuf_without any conflict (as opposed to the
basic_filebuf_objects, in which a joint file position is
maintained).
INTERFACE
template<class charT, class traits = char_traits<charT>,
class allocator<charT> >
class basic_stringbuf
: public basic_streambuf<charT, traits> {
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;
typedef basic_ios<charT, traits> ios_type;
typedef basic_string<charT, traits,
Allocator> string_type;
explicit basic_stringbuf(ios_base::openmode which =
(ios_base::in | ios_base::out));
explicit basic_stringbuf(const string_type& str,
ios_base::openmode which =
(ios_base::in | ios_base::out));
virtual ~basic_stringbuf();
string_type str() const;
void str(const string_type& str_arg);
protected:
virtual int_type underflow();
virtual int_type pbackfail(int_type c = traits::eof());
virtual int_type overflow(int_type c = traits::eof());
virtual basic_streambuf<charT,traits>*
setbuf(char_type *s,streamsize n);
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual pos_type seekpos(pos_type sp,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual streamsize xsputn(const char_type* s,
streamsize n);
};
TYPES
char_type
The type char_type is a synonym for the template parame-
ter charT.
ios_type
The type ios_type is an instantiation of class basic_ios
on type charT.
off_type
The type off_type is a synonym of type traits::off_type.
pos_type
The type pos_type is a synonym of type traits::pos_type.
string_type
The type string_type is an instantiation of class
basic_string on type charT.
stringbuf
The type stringbuf is an instantiation of class
basic_stringbuf on type char:
typedef basic_stringbuf<char> stringbuf;
traits_type
The type traits_type is a synonym for the template param-
eter traits.
wstringbuf
The type wstringbuf is an instantiation of class
basic_stringbuf on type wchar_t:
typedef basic_stringbuf<wchar_t> wstringbuf;
CONSTRUCTORS
explicit basic_stringbuf(ios_base::openmode which =
ios_base::in | ios_base::out);
Constructs an object of class basic_stringbuf, initializ-
ing the base class with basic_streambuf(), and initializ-
ing the open mode with which.
explicit basic_stringbuf(const string_type& str,
ios_base::openmode which =
ios_base::in | ios_base::out);
Constructs an object of class basic_stringbuf, initializ-
ing the base class with basic_streambuf(), and initializ-
ing the open mode with which. The string object str is
copied to the underlying buffer. If the opening mode is
in, initializes the input sequence to point to the first
character of the buffer. If the opening mode is out, it
initializes the output sequence to point to the first
character of the buffer. If the opening mode is out |
app, it initializes the output sequence to point to the
last character of the buffer.
DESTRUCTORS
virtual ~basic_stringbuf();
Destroys an object of class basic_stringbuf.
MEMBER FUNCTIONS
int_type
overflow(int_type c = traits::eof() );
If the output sequence has a put position available, and
c is not traits::eof(), then this function writes c into
it. If there is no position available, the function
increases the size of the buffer by allocating more
memory and then writes c at the new current put position.
If the operation fails, the function returns
traits::eof(). Otherwise it returns traits::not_eof(c).
int_type
pbackfail( int_type c = traits::eof() );
Puts back the character designated by c into the input
sequence. If traits::eq_int_type(c,traits::eof()) returns
true, the function moves the input sequence one position
backward. If the operation fails, the function returns
traits::eof(). Otherwise it returns traits::not_eof(c).
pos_type
seekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
If the open mode is in | out, this function alters the
stream position of both the input and the output
sequences. If the open mode is in, it alters the stream
position of only the input sequence, and if it is out, it
alters the stream position of the output sequence. The
new position is calculated by combining the two parame-
ters off (displacement) and way (reference point). If the
current position of the sequence is invalid before repo-
sitioning, the operation fails and the return value is
pos_type(off_type(-1)). Otherwise the function returns
the current new position.
pos_type
seekpos(pos_type sp,ios_base::openmode which =
ios_base::in | ios_base::out);
If the open mode is in | out, seekpos() alters the stream
position of both the input and the output sequences. If
the open mode is in, it alters the stream position of the
input sequence only, and if the open mode is out, 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 pos_type(off_type(-1)). Otherwise the function returns
the current new position.
basic_streambuf<charT,traits>*
setbuf(char_type*s, streamsize n);
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 res-
trictions.
First of all, n must be greater than the number of char-
acters currently in the buffer. If n is too small, then
setbuf has no effect and returns a null pointer to indi-
cate failure.
If n is large enough, then this function has one of two
effects:
- If s is not a null pointer, then setbuf copies
the buffered contents of the stringbuf into the
n character array starting at s and installs s
as the underlying character array used by the
stringbuf. s replaces the old underlying
array. In this case, the function returns s on
success or a null pointer to indicate failure.
Note that the stringbuf now owns s and deletes
it if a subsequent call to setbuf replaces it
or, failing that, when the stringbuf is des-
troyed. A program should not itself delete a
pointer passed to setbuf if the call succeeds.
And s must have been allocated from the heap
using new.
- If s is a null pointer, then setbuf resizes the
underlying character array to n characters.
The function returns a pointer to the beginning
of the resized array if the operation is suc-
cessful, or a null pointer if not.
string_type
str() const;
Returns a string object of type string_type whose content
is a copy of the underlying buffer contents.
void
str(const string_type& str_arg);
Clears the underlying buffer and copies the string object
str_arg into it. If the opening mode is in, initializes
the input sequence to point to the first character of the
buffer. If the opening mode is out, the function initial-
izes the output sequence to point to the first character
of the buffer. If the opening mode is out | app, it ini-
tializes the output sequence to point to the last charac-
ter of the buffer.
int_type
underflow();
If the input sequence has a read position available, the
function 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. The function returns traits::eof() to
indicate failure.
streamsize
xsputn(const char_type* s, streamsize n);
Writes up to n characters to the output sequence. The
characters written are obtained from successive elements
of the array whose first element is designated by s. The
function returns the number of characters written.
EXAMPLE
// stdlib/examples/manual/stringbuf.cpp
//
#include<iostream>
#include<sstream>
#include<string>
void main ( )
{
using namespace std;
// create a read/write string-stream object on tiny char
// and attach it to an ostringstream object
ostringstream out_1(ios_base::in | ios_base::out);
// tie the istream object to the ostringstream object
istream in_1(out_1.rdbuf());
// output to out_1
out_1 << "Here is the first output";
// create a string object on tiny char
string string_ex("l'heure est grave !");
// open a read only string-stream object on tiny char
// and initialize it
istringstream in_2(string_ex);
// output in_1 to the standard output
cout << in_1.str() << endl;
// output in_2 to the standard output
cout << in_2.rdbuf() << endl;
// reposition in_2 at the beginning
in_2.seekg(0);
stringbuf::pos_type pos;
// get the current put position
// equivalent to
// out_1.tellp();
pos = out_1.rdbuf()->pubseekoff(0,ios_base::cur,
ios_base::out);
// append the content of stringbuffer
// pointed to by in_2 to the one
// pointed to by out_1
out_1 << ' ' << in_2.rdbuf();
// output in_1 to the standard output
cout << in_1.str() << endl;
// position the get sequence
// equivalent to
// in_1.seekg(pos);
in_1.rdbuf()->pubseekpos(pos, ios_base::in);
// output "l'heure est grave !"
cout << in_1.rdbuf() << endl << endl;
}
SEE ALSO
char_traits(3C++), ios_base(3C++), basic_ios(3C++),
basic_streambuf(3C++), basic_string(3C++),
basic_istringstream(3C++), basic_ostringstream(3C++),
basic_stringstream(3C++)
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section
27.7.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee