iostream_intro
Name
iostream_intro - Introduction to the DIGITAL C++ Standard Library iostream
Package
This page is an introduction to the ANSI I/O stream classes. If you
would like information on the pre-ANSI I/O stream package, use the
command:
help cxxl
Description
[ TBS ] A more detailed description of the ANSI iostream package will
be available in a future release of the DIGITAL C++ compiler.
Compatibility
[Digital] The ANSI Standard Library provides two macros which
enable or disable use of the ANSI iostream package at compile
time. The ANSI iostream package may cause compile time and/or
run time behavior incompatibilities which require source
code changes to resolve. These macros allow users to choose the
iostream package they want.
Check the cxx documentation for a description of the default
settings of these macros in different compiler modes.
The -D DIGITAL C++ compiler switch can be used on the compile
command line without requiring source code changes while the
#define line should be added to the source code prior to any #include
statement.
All source modules within the same application must be compiled in
the same mode.
________________________________________________________________
__USE_STD_IOSTREAM
Usage Description
________________________________________________________________
cxx -D__USE_STD_IOSTREAM Use ANSI iostream package
#define __USE_STD_IOSTREAM Use ANSI iostream package
________________________________________________________________
__NO_USE_STD_IOSTREAM
Usage Description
________________________________________________________________
cxx -D__NO_USE_STD_IOSTREAM Use pre-ANSI iostream package
#define __NO_USE_STD_IOSTREAM Use pre-ANSI iostream package
________________________________________________________________
See Also
basic_iostream
basic_filebuf
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_filebuf,filebuf
This page describes the ANSI basic_filebuf class. If you would like
information on the pre-ANSI filebuf class, use the command:
help cxxl
SYNOPSIS
#include <fstream>
template<class charT, class traits = char_traits<charT> >
class basic_filebuf
: public basic_streambuf<charT, traits>
DESCRIPTION
The template class basic_filebuf is derived from basic_streambuf. It
associates the input or output sequence with a file. Each object
of type basic_filebuf<charT, traits> controls two character sequences:
+ a character input sequence
+ a character output sequence
The restrictions on reading and writing a sequence controlled by an
object of class basic_filebuf<charT,traits> are the same as for
reading and writing with the Standard C library files.
If the file is not open for reading the input sequence
cannot be read. If the file is not open for writing the
output sequence cannot be written. A joint file position is
maintained for both the input and output sequences.
A file provides byte sequences. So the basic_filebuf class treats a
file as the external source (or sink) byte sequence. In order to
provide the contents of a file as wide character sequences, a
wide-oriented file buffer called wfilebuf converts wide
character sequences to multibytes character sequences (and vice
versa) according to the current locale being used in the stream
buffer.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_filebuf
: public basic_streambuf<charT, traits> {
public:
typedef traits traits_type;
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;
basic_filebuf();
basic_filebuf(int fd);
virtual ~basic_filebuf();
bool is_open() const;
basic_filebuf<charT, traits>* open(const char *s,
ios_base::openmode,
long protection = 0666);
basic_filebuf<charT, traits>* open(int fd);
basic_filebuf<charT, traits>* close();
protected:
virtual int showmanyc();
virtual int_type overflow(int_type c = traits::eof());
virtual int_type pbackfail(int_type c = traits::eof());
virtual int_type underflow();
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 int sync();
virtual streamsize xsputn(const char_type* s, streamsize n);
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
filebuf
The type filebuf is an instantiation of class basic_filebuf on type
char:
typedef basic_filebuf<char> filebuf;
int_type
The type int_type is a synonym of type traits::in_type.
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.
traits_type
The type traits_type is a synonym for the template parameter traits.
wfilebuf
The type wfilebuf is an instantiation of class basic_filebuf on type
wchar_t:
typedef basic_filebuf<wchar_t> wfilebuf;
CONSTRUCTORS
basic_filebuf();
Constructs an object of class basic_filebuf<charT,traits>,
initializing the base class with basic_streambuf<charT,traits>().
basic_filebuf(int fd);
Constructs an object of class basic_filebuf<charT,traits>,
initializing the base class with basic_streambuf<charT,traits>(),
then calls open(fd). This function is not described in the
C++ standard, and is provided as an extension in order to
manipulate pipes, sockets or other UNIX devices, that
can be accessed through file descriptors.
DESTRUCTOR
virtual ~basic_filebuf();
Calls close() and destroys the object.
MEMBER FUNCTIONS
basic_filebuf<charT,traits>*
close();
If is_open() == false, returns a null pointer. Otherwise,
closes the
file, and returns *this.
bool
is_open() const;
Returns true if the associated file is open.
basic_filebuf<charT,traits>*
open(const char* s, ios_base::openmode mode,
long protection = 0666);
If is_open() == true, returns a null pointer. Otherwise opens
the file, whose name is stored in the
null-terminated byte-string s. The file open modes are
given by their C-equivalent description (see the C
function fopen):
in "w"
in|binary "rb"
out "w"
out|app "a"
out|binary "wb"
out|binary|app "ab"
out|in "r+"
out|in|app "a+"
out|in|binary "r+b"
out|in|binary|app "a+b"
trunc|out "w"
trunc|out|binary "wb"
trunc|out|in "w+"
trunc|out|in|binary "w+b"
The third argument, protection, is used as the file permission.
It does not appear in the Standard C++ description of the
function open and is provided as an extension. It determines
the file read/write/execute permissions under UNIX. It is more
limited under DOS since files are always readable and do not
have special execute permission. If the open function fails,
it returns a null pointer.
basic_filebuf<charT,traits>*
open(int fd);
Attaches the file previously opened and identified by its file
descriptor fd, to the basic_filebuf object. This function is
not described in the C++ standard, and is provided as an extension
in order to manipulate pipes, sockets or other UNIX devices,
that can be accessed through file descriptors.
int_type
overflow(int_type c = traits::eof() );
If the output sequence has a put position available, and c is not
traits::eof(), then write c into it. If there is no position
available, the function output the content of the buffer to
the associated file and then write c at the new current put
position. If the operation fails, the function returns
traits::eof(). Otherwise it returns traits::not_eof(c). In wide
characters file buffer, overflow converts the internal wide
characters to their external multibytes representation by using
the locale::codecvt facet located in the locale object imbued in
the stream buffer.
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, move 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, alters the stream position of both
the input and the output sequence. If the open mode is in,
alters the stream position of only the input sequence, and
if it is out, alters the stream position of only the output
sequence. The new position is calculated by combining the two
parameters 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. File buffers using locale::codecvt facet
performing state dependent conversion, only support
seeking to the beginning of the file, to the current
position, or to a position previously obtained by a call
to one of the iostreams seeking functions.
pos_type
seekpos(pos_type sp,ios_base::openmode which = ios_base::in |
ios_base::out);
If the open mode is in | out, alters the stream position of both
the input and the output sequence. If the open mode is in,
alters the stream position of only the input sequence, and
if it is out, alters the stream position of only the output
sequence. 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. File buffers using locale::codecvt
facet performing state dependent conversion, only support
seeking to the beginning of the file, to the current position,
or to a position previously obtained by a call to one of the
iostreams seeking functions.
basic_filebuf<charT,traits>*
setbuf(char_type*s, streamsize n);
If s is not a null pointer, output the content of the current
buffer to the associated file, then delete the current buffer and
replace it by s. Otherwise resize the current buffer to size n
after outputting its content to the associated file if
necessary.
int
sync();
Synchronizes the content of the external file, with its image
maintained in memory by the file buffer. If the function
fails, it returns -1, otherwise it returns 0.
int_type
underflow();
If the input sequence has a read position available, returns the
content of this position. Otherwise fills up the buffer by
reading characters from the associated file and if it
succeeds, returns the content of the new current position. The
function returns traits::eof() to indicate failure. In wide
characters file buffer, underflow converts the external
mutltibytes characters to their wide character representation by
using the locale::codecvt facet located in the locale object
imbued in the stream buffer.
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.
EXAMPLES
//
// stdlib/examples/manual/filebuf.cpp
//
#include<iostream>
#include<fstream>
void main ( )
{
using namespace std;
// create a read/write file-stream object on tiny char
// and attach it to the file "filebuf.out"
ofstream out("filebuf.out",ios_base::in | ios_base::out);
// tie the istream object to the ofstream object
istream in(out.rdbuf());
// output to out
out << "Il errait comme un ame en peine";
// seek to the beginning of the file
in.seekg(0);
// output in to the standard output
cout << in.rdbuf() << endl;
// close the file "filebuf.out"
out.close();
// open the existing file "filebuf.out"
// and truncate it
out.open("filebuf.out",ios_base::in | ios_base::out |
ios_base::trunc);
// set the buffer size
out.rdbuf()->pubsetbuf(0,4096);
// open the source code file
ifstream ins("filebuf.cpp");
//output it to filebuf.out
out << ins.rdbuf();
// seek to the beginning of the file
out.seekp(0);
// output the all file to the standard output
cout << out.rdbuf();
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_streambuf, basic_ifstream, basic_ofstream,
basic_fstream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.8.1.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
basic_fstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_fstream,fstream,ofstream
This page describes the ANSI basic_fstream class. If you would like
information on the pre-ANSI fstream class, use the command:
help cxxl
SYNOPSIS
#include <fstream>
template<class charT, class traits = char_traits<charT> >
class basic_fstream
: public basic_iostream<charT, traits>
DESCRIPTION
The template class basic_fstream<charT,traits> supports reading and
writing to named files or other devices associated with a file
descriptor. It uses a basic_filebuf object to control the
associated sequences. It inherits from basic_iostream and can
therefore use all the formatted and unformatted input and
output functions.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_fstream
: public basic_iostream<charT, traits> {
public:
typedef basic_ios<charT, traits> ios_type;
typedef charT char_type;
typedef traits traits_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
basic_fstream();
explicit basic_fstream(const char *s, ios_base::openmode
mode = ios_base::in | ios_base::out,
long protection = 0666);
explicit basic_fstream(int fd);
basic_fstream(int fd, char_type *buf, int len);
virtual ~basic_fstream();
basic_filebuf<charT, traits> *rdbuf() const;
bool is_open();
void open(const char *s, ios_base::openmode mode =
ios_base::in | ios_base::out,
long protection = 0666);
void close();
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
fstream
The type fstream is an instantiation of class basic_fstream on type
char:
typedef basic_fstream<char> fstream;
int_type
The type int_type is a synonym of type traits::in_type.
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.
traits_type
The type traits_type is a synonym for the template parameter traits.
wfstream
The type wfstream is an instantiation of class basic_fstream on type
wchar_t:
typedef basic_fstream<wchar_t> wfstream;
CONSTRUCTORS
basic_fstream();
Constructs an object of class basic_fstream<charT,traits>,
initializing the base class basic_iostream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). After construction,
a file can be attached to the basic_ftream object by using the
open() member function.
basic_fstream(const char* s,
ios_base::openmode mode=
ios_base::in | iosw_base::out,
long protection= 0666);
Constructs an object of class basic_fstream<charT,traits>,
initializing the base class basic_iostream with the
associated file buffer, which is initialized by calling the
basic_filebuf constructor basic_filebuf<charT,traits>().
The constructor then calls the open function
open(s,mode,protection) in order to attach the file, whose name
is pointed at by s, to the basic_ftream object. The third
argument, protection, is used as the file permission. It does
not appear in the Standard C++ description and is provided
as an extension. It determines the file read/write/execute
permissions under UNIX. It is more limited under DOS since
files are always readable and do not have special execute
permission.
explicit basic_fstream(int fd);
Constructs an object of class basic_fstream<charT,traits>,
initializing the base class basic_iostream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). The constructor
then calls the basic_filebuf open function open(fd) in order to
attach the file descriptor fd to the basic_ftream object. This
constructor is not described in the C++ standard, and
is provided as an extension in order to manipulate pipes,
sockets or other UNIX devices, that can be accessed through
file descriptors. If the function fails, it sets
ios_base::failbit.
basic_fstream(int fd, char_type* buf,int len);
Constructs an object of class basic_fstream<charT,traits>,
initializing the base class basic_iostream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). The constructor
then calls the basic_filebuf open function open(fd) in order to
attach the file descriptor fd to the basic_ftream object. The
underlying buffer is then replaced by calling the
basic_filebuf member function, setbuf(), with parameters buf
and len. This constructor is not described in the C++
standard, and is provided as an extension in order to manipulate
pipes, sockets, or other UNIX devices that can be accessed
through file descriptors. It also maintains compatibility with
the old iostreams library. If the function fails, it sets
ios_base::failbit.
DESTRUCTOR
virtual ~basic_fstream();
Destroys an object of class basic_fstream.
MEMBER FUNCTIONS
void
close();
Calls the associated basic_filebuf function close() and if this
function fails, it calls the basic_ios member function
setstate(failbit).
bool
is_open();
Calls the associated basic_filebuf function is_open() and return
its result.
void
open(const char* s,ios_base::openmode =
ios_base::out | ios_base::in,
long protection = 0666);
Calls the associated basic_filebuf function
open(s,mode,protection) and, if this function fails at
opening the file, calls the basic_ios member function
setstate(failbit). The third argument protection is used as
the file permissions. It does not appear in the Standard C++
description and is provided as an extension. It determines
the file read/write/execute permissions under UNIX. It
is more limited under DOS since files are always readable and do
not have special execute permission.
basic_filebuf<charT,traits>*
rdbuf() const;
Returns a pointer to the basic_filebuf associated with the stream.
EXAMPLES
//
// stdlib/examples/manual/fstream.cpp
//
#include<iostream>
#include<bidirec>
void main ( )
{
using namespace std;
// create a bi-directional fstream object
fstream inout("fstream.out");
// output characters
inout << "Das ist die rede von einem man" << endl;
inout << "C'est l'histoire d'un home" << endl;
inout << "This is the story of a man" << endl;
char p[100];
// seek back to the beginning of the file
inout.seekg(0);
// extract the first line
inout.getline(p,100);
// output the first line to stdout
cout << endl << "Deutch :" << endl;
cout << p;
fstream::pos_type pos = inout.tellg();
// extract the seconf line
inout.getline(p,100);
// output the second line to stdout
cout << endl << "Francais :" << endl;
cout << p;
// extract the third line
inout.getline(p,100);
// output the third line to stdout
cout << endl << "English :" << endl;
cout << p;
// move the put sequence before the second line
inout.seekp(pos);
// replace the second line
inout << "This is the story of a man" << endl;
// replace the third line
inout << "C'est l'histoire d'un home";
// seek to the beginning of the file
inout.seekg(0);
// output the all content of the fstream object to stdout
cout << endl << endl << inout.rdbuf();
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_filebuf, basic_ifstream, basic_ofstream
Working Paper for Draft Proposed International Standard for Information
Systems--Programming Language C++, Section 27.8.1.11
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
basic_ifstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_ifstream,fstream
This page describes the ANSI basic_ifstream class. If you would like
information on the pre-ANSI ifstream class, use the command:
help cxxl
SYNOPSIS
#include <fstream>
template<class charT, class traits = char_traits<charT> >
class basic_ifstream
: public basic_istream<charT, traits>
DESCRIPTION
The template class basic_ifstream<charT,traits> supports reading
from named files or other devices associated with a file
descriptor. It uses a basic_filebuf object to control the
associated sequences. It inherits from basic_istream and
can therefore use all the formatted and unformatted input
functions.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_ifstream
: public basic_istream<charT, traits> {
public:
typedef basic_ios<charT, traits> ios_type;
typedef traits traits_type;
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;
basic_ifstream();
explicit basic_ifstream(const char *s,
ios_base::openmode mode =
ios_base::in,
long protection = 0666);
explicit basic_ifstream(int fd);
basic_ifstream(int fd, char_type* buf, int len);
virtual ~basic_ifstream();
basic_filebuf<charT, traits> *rdbuf() const;
bool is_open();
void open(const char *s, ios_base::openmode mode =
ios_base::in, long protection = 0666);
void close();
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
ifstream
The type ifstream is an instantiation of class basic_ifstream on type
char:
typedef basic_ifstream<char> ifstream;
int_type
The type int_type is a synonym of type traits::in_type.
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.
traits_type
The type traits_type is a synonym for the template parameter traits.
wifstream
The type wifstream is an instantiation of class basic_ifstream on
type wchar_t:
typedef basic_ifstream<wchar_t> wifstream;
CONSTRUCTORS
basic_ifstream();
Constructs an object of class basic_ifstream<charT,traits>,
initializing the base class basic_istream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). After construction,
a file can be attached to the basic_iftream object by using the
open member function.
basic_ifstream(const char* s,
ios_base::openmode mode= ios_base::in,
long protection= 0666);
Constructs an object of class basic_ifstream<charT,traits>,
initializing the base class basic_istream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). The constructor then
calls the open function open(s,mode,protection) in order to
attach the file whose name is pointed at by s, to the
basic_iftream object. The third argument protection provides file
permissions. It does not appear in the Standard C++ description
and is provided as an extension. It determines the file
read/write/execute permissions under UNIX. It is more limited
under DOS since files are always readable and do not have
special execute permission.
explicit basic_ifstream(int fd)
Constructs an object of class basic_ifstream<charT,traits>,
initializing the base class basic_istream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). The constructor
then calls the basic_filebuf open function open(fd) in order to
attach the file descriptor fd to the basic_iftream object. This
constructor is not described in the C++ standard, and is
provided as an extension in order to manipulate pipes,
sockets or other UNIX devices, that can be accessed through
file descriptors. If the function fails, it sets
ios_base::failbit.
basic_ifstream(int fd, char_type* buf,int len);
Constructs an object of class basic_ifstream<charT,traits>,
initializing the base class basic_istream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). The constructor
then calls the basic_filebuf open function open(fd) in order to
attach the file descriptor fd to the basic_iftream object. The
underlying buffer is then replaced by calling the basic_filebuf
member function setbuf with parameters buf and len. This
constructor is not described in the C++ standard, and is
provided as an extension in order to manipulate pipes, sockets or
other UNIX devices, that can be accessed through file
descriptors. It also maintains compatibility with the old
iostreams library. If the function fails, it sets
ios_base::failbit.
DESTRUCTOR
virtual ~basic_ifstream();
Destroys an object of class basic_ifstream.
MEMBER FUNCTIONS
void
close();
Calls the associated basic_filebuf function close() and if this function
fails, it calls the basic_ios member function setstate(failbit).
bool
is_open();
Calls the associated basic_filebuf function is_open() and return its
result.
void
open(const char* s,ios_base::openmode =
ios_base::in, long protection = 0666);
Calls the associated basic_filebuf function
open(s,mode,protection). If this function fails opening the
file, it calls the basic_ios member function
setstate(failbit). The third argument protection provides
file permissions. It does not appear in the Standard C++
description and is provided as an extension. It determines
the file read/write/execute permissions under UNIX. It
is more limited under DOS since files are always readable and do
not have special execute permission.
basic_filebuf<charT,traits>*
rdbuf() const;
Returns a pointer to the basic_filebuf associated with the stream.
EXAMPLES
//
// stdlib/examples/manual/ifstream.cpp
//
#include<iostream>
#include<fstream>
#include<iomanip>
void main ( )
{
using namespace std;
long l= 20;
char *ntbs="Le minot passait la piece a frotter";
char c;
char buf[50];
try {
// create a read/write file-stream object on char
// and attach it to an ifstream object
ifstream in("ifstream.out",ios_base::in |
ios_base::out | ios_base::trunc);
// tie the ostream object to the ifstream object
ostream out(in.rdbuf());
// output ntbs in out
out << ntbs << endl;
// seek to the beginning of the file
in.seekg(0);
// output each word on a separate line
while ( in.get(c) )
{
if ( char_traits<char>::eq(c,' ') )
cout << endl;
else
cout << c;
}
cout << endl << endl;
// move back to the beginning of the file
in.seekg(0);
// clear the state flags
in.clear();
// does the same thing as the previous code
// output each word on a separate line
while ( in >> buf )
cout << buf << endl;
cout << endl << endl;
// output the base info before each integer
out << showbase;
ostream::pos_type pos= out.tellp();
// output l in hex with a field with of 20
out << hex << setw(20) << l << endl;
// output l in oct with a field with of 20
out << oct << setw(20) << l << endl;
// output l in dec with a field with of 20
out << dec << setw(20) << l << endl;
// move back to the beginning of the file
in.seekg(0);
// output the all file
cout << in.rdbuf();
// clear the flags
in.clear();
// seek the input sequence to pos
in.seekg(pos);
int a,b,d;
// read the previous outputted integer
in >> a >> b >> d;
// output 3 times 20
cout << a << endl << b << endl << d << endl;
}
catch( ios_base::failure& var )
{
cout << var.what();
}
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_filebuf, basic_ofstream, basic_fstream
Working Paper for Draft Proposed International Standard for Information
Systems--Programming Language C++, Section 27.8.1.5
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
basic_ios
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_ios,ios
This page describes the ANSI ios class. If you would like
information on the pre-ANSI ios class, use the command:
help cxxl
SYNOPSIS
#include <ios>
template<class charT, class traits = char_traits<charT> >
class basic_ios : public ios_base
DESCRIPTION
The class basic_ios is a base class that provides the common
functionality required by all streams. It maintains state
information that reflects the integrity of the stream and stream
buffer. It also maintains the link between the stream classes and
the stream buffers classes via the rdbuf member functions.
Classes derived from basic_ios specialize operations for input, and
output.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_ios : public ios_base {
public:
typedef basic_ios<charT, traits> ios_type;
typedef basic_streambuf<charT, traits> streambuf_type;
typedef basic_ostream<charT, traits> ostream_type;
typedef typename traits::char_type char_type;
typedef traits traits_type;
typedef typename traits::int_type int_type;
typedef typename traits::off_type off_type;
typedef typename traits::pos_type pos_type;
explicit basic_ios(basic_streambuf<charT, traits> *sb_arg);
virtual ~basic_ios();
char_type fill() const;
char_type fill(char_type ch);
void exceptions(iostate except);
iostate exceptions() const;
void clear(iostate state = goodbit);
void setstate(iostate state);
iostate rdstate() const;
operator void*() const;
bool operator!() const;
bool good() const;
bool eof() const;
bool fail() const;
bool bad() const;
ios_type& copyfmt(const ios_type& rhs);
ostream_type *tie() const;
ostream_type *tie(ostream_type *tie_arg);
streambuf_type *rdbuf() const;
streambuf_type *rdbuf( streambuf_type *sb);
locale imbue(const locale& loc);
char narrow(charT, char) const;
charT widen(char) const;
protected:
basic_ios();
void init(basic_streambuf<charT, traits> *sb);
};
TYPES
char_type
The type char_type is a synonym of type traits::char_type.
ios
The type ios is an instantiation of basic_ios on char:
typedef basic_ios<char> ios;
int_type
The type int_type is a synonym of type traits::in_type.
ios_type
The type ios_type is a synonym for basic_ios<charT, traits> .
off_type
The type off_type is a synonym of type traits::off_type.
ostream_type
The type ostream_type is a synonym for basic_ostream<charT, traits> .
pos_type
The type pos_type is a synonym of type traits::pos_type.
streambuf_type
The type streambuf_type is a synonym for basic_streambuf<charT, traits>
.
traits_type
The type traits_type is a synonym for the template parameter traits.
wios
The type wios is an instantiation of basic_ios on wchar_t:
typedef basic_ios<wchar_t> wios;
PUBLIC CONSTRUCTORS
explicit basic_ios(basic_streambuf<charT, traits>* sb);
Constructs an object of class basic_ios, assigning initial values
to its member objects by calling init(sb). If sb is a null
pointer, the stream is positioned in error state, by
triggering its badbit.
basic_ios();
Constructs an object of class basic_ios leaving its member
objects uninitialized. The object must be initialized
by calling the init member function before using it.
PUBLIC DESTRUCTOR
virtual ~basic_ios();
Destroys an object of class basic_ios.
PUBLIC MEMBER FUNCTIONS
bool
bad() const;
Returns true if badbit is set in rdstate().
void
clear(iostate state = goodbit);
If (state & exception()) == 0, returns. Otherwise, the function
throws an object of class ios_base::failure. After the call
returns state == rdstate().
basic_ios&
copyfmt(const basic_ios& rhs);
Assigns to the member objects of *this the corresponding member
objects of rhs, with the following exceptions:
+ rdstate() and rdbuf() are left unchanged
+ calls ios_base::copyfmt
+ exceptions() is altered last by calling
exceptions(rhs.exceptions())
bool
eof() const;
Returns true if eofbit is set in rdstate().
iostate
exceptions() const;
Returns a mask that determines what elements set in rdstate()
cause exceptions to be thrown.
void
exceptions(iostate except);
Set the exception mask to except then calls clear(rdstate()).
bool
fail() const;
Returns true if failbit or badbit is set in rdstate().
char_type
fill() const;
Returns the character used to pad (fill) an output conversion to
the specified field width.
char_type
fill(char_type fillch);
Saves the field width value then replaces it by fillch and
returns the previously saved value.
bool
good() const;
Returns rdstate() == 0.
locale
imbue(const locale& loc);
Saves the value returned by getloc() then assigns loc to a
private variable and if rdbuf() != 0 calls
rdbuf()->pubimbue(loc) and returns the previously saved value.
void
init(basic_streambuf<charT,traits>* sb);
Performs the following initialization:
rdbuf() sb
tie() 0
rdstate() goodbit if sb is not null otherwise badbit
exceptions() goodbit
flags() skipws | dec
width() 0
precision() 6
fill() the space character
getloc() locale::locale()
char
narrow(charT c, char dfault) const;
Uses the stream's locale to convert the wide character c to a
tiny character, and then returns it. If no
conversion exists, it returns the character dfault.
bool
operator!() const;
Returns fail() ? 1 : 0;
streambuf_type*
rdbuf() const;
Returns a pointer to the stream buffer associated with the stream.
streambuf_type*
rdbuf(streambuf_type* sb);
Associates a stream buffer with the stream. All the input and
output will be directed to this stream buffer. If sb is a null
pointer, the stream is positioned in error state, by triggering
its badbit.
iostate
rdstate() const;
Returns the control state of the stream.
void
setstate(iostate state);
Calls clear(rdstate() | state).
ostream_type*
tie() const;
Returns an output sequence that is tied to (synchronized with) the
sequence controlled by the stream buffer.
ostream_type*
tie(ostream_type* tiestr);
Saves the tie() value then replaces it by tiestr and returns the
value previously saved.
operator
void*() const;
Returns fail() ? 0 : 1;
charT
widen(char c) const;
Uses the stream's locale to convert the tiny character c to a
wide character, then returns it.
SEE ALSO
ios_base, basic_istream, basic_ostream,
basic_streambuf, char_traits
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++.
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
basic_iostream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_iostream,iostream
This page describes the ANSI basic_iostream class. If you would
like information on the pre-ANSI iostream class, use the command:
help cxxl
SYNOPSIS
#include <istream>
template<class charT, class traits = char_traits<charT> >
class basic_iostream
: public basic_istream<charT, traits>,
public basic_ostream<charT, traits>
DESCRIPTION
The class basic_iostream inherits a number of functions from classes
basic_ostream<charT, traits> and basic_istream<charT, traits>. They
assist in formatting and interpreting sequences of characters
controlled by a stream buffer. Two groups of functions share common
properties, the formatted functions and the unformatted functions.
INTERFACE
template<class charT, class traits>
class basic_iostream
: public basic_istream<charT, traits>,
public basic_ostream<charT, traits>
{
public:
explicit basic_iostream(basic_streambuf<charT, traits> *sb);
virtual ~basic_iostream();
protected:
explicit basic_iostream();
};
PUBLIC CONSTRUCTORS
explicit basic_iostream(basic_streambuf<charT, traits>* sb);
Constructs an object of class basic_iostream, assigning initial
values to the base class by calling
basic_istream<charT, traits>(sb) and
basic_ostream<charT, traits>(sb).
explicit basic_iostream();
Constructs an object of class basic_iostream, assigning
initial values to the base class by calling
basic_istream<charT, traits>() and basic_ostream<charT, traits>().
After construction the object has its badbit set.
DESTRUCTOR
virtual ~basic_iostream();
Destroys an object of class basic_iostream.
EXAMPLES
See basic_istream and basic_ostream examples.
COMPATIBILITY
[Digital] The ANSI Standard Library provides two macros which
enable or disable use of the ANSI iostream package at compile
time.
______________________________________________________________
Macro Description
______________________________________________________________
__USE_STD_IOSTREAM Use the ANSI Standard iostream package
__NO_USE_STD_IOSTREAM Use the pre-ANSI iostream package
______________________________________________________________
See ios_intro(help cxxl) or iostream_intro(help cxxlstd) for more
details.
SEE ALSO
char_traits, ios_base, basic_ios,
basic_streambuf, basic_istream, basic_ostream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section
27.6.1.4.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
basic_istream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_istream,istream
This page describes the ANSI basic_istream class. If you would like
information on the pre-ANSI istream class, use the command:
help cxxl
SYNOPSIS
#include <istream>
template<class charT, class traits = char_traits<charT> >
class basic_istream
: virtual public basic_ios<charT, traits>
DESCRIPTION
The class basic_istream defines a number of member function
signatures that assist in reading and interpreting input from
sequences controlled by a stream buffer.
Two groups of member function signatures share common properties:
the formatted input functions (or extractors) and the unformatted
input functions. Both groups of input functions obtain (or
extract) input characters by calling basic_streambuf member
functions. They both begin by constructing an object of class
basic_istream::sentry and, if this object is in good state after
construction, the function endeavors to obtain the requested
input. The sentry object performs exception safe initialization,
such as controlling the status of the stream or locking it
in multithread environment.
Some formatted input functions parse characters extracted from the
input sequence, converting the result to a value of some scalar
data type, and storing the converted value in an object of that
scalar type. The conversion behavior is locale dependent,
and directly depend on the locale object imbued in the
stream.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_istream
: virtual public basic_ios<charT, traits> {
public:
typedef basic_istream<charT, traits> istream_type;
typedef basic_ios<charT, traits> ios_type;
typedef basic_streambuf<charT, traits> streambuf_type;
typedef traits traits_type;
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_istream(basic_streambuf<charT, traits> *sb);
virtual ~basic_istream();
class sentry
{
public:
inline explicit sentry(basic_istream<charT,traits>&,
bool noskipws = 0);
~sentry();
operator bool ();
};
istream_type& operator>>(istream_type& (*pf)(istream_type&));
istream_type& operator>>(ios_base& (*pf)(ios_base&));
istream_type& operator>>(ios_type& (*pf)(ios_type&));
istream_type& operator>>(bool& n);
istream_type& operator>>(short& n);
istream_type& operator>>(unsigned short& n);
istream_type& operator>>(int& n);
istream_type& operator>>(unsigned int& n);
istream_type& operator>>(long& n);
istream_type& operator>>(unsigned long& n);
istream_type& operator>>(float& f);
istream_type& operator>>(double& f);
istream_type& operator>>(long double& f);
istream_type& operator>>(void*& p);
istream_type& operator>>(streambuf_type& sb);
istream_type& operator>>(streambuf_type *sb);
int_type get();
istream_type& get(char_type *s, streamsize n, char_type delim);
istream_type& get(char_type *s, streamsize n);
istream_type& get(char_type& c);
istream_type& get(streambuf_type& sb,char_type delim);
istream_type& get(streambuf_type& sb);
istream_type& getline(char_type *s, streamsize n,char_type delim);
istream_type& getline(char_type *s, streamsize n);
istream_type& ignore(streamsize n = 1,
int_type delim = traits::eof());
istream_type& read(char_type *s, streamsize n);
streamsize readsome(char_type *s, streamsize n);
int peek();
pos_type tellg();
istream_type& seekg(pos_type&);
istream_type& seekg(off_type&, ios_base::seekdir);
istream_type& putback(char_type c);
istream_type& unget();
streamsize gcount() const;
int sync();
protected:
explicit basic_istream( );
};
//global function
template<class charT, class traits>
basic_istream<charT, traits>&
ws(basic_istream<charT, traits>&);
template<class charT, class traits>
basic_istream<charT, traits>&
operator>> (basic_istream<charT, traits>&, charT&);
template<class charT, class traits>
basic_istream<charT, traits>&
operator>> (basic_istream<charT, traits>&, charT*);
template<class traits>
basic_istream<char, traits>&
operator>> (basic_istream<char, traits>&, unsigned char&);
template<class traits>
basic_istream<char, traits>&
operator>> (basic_istream<char, traits>&, signed char&);
template<class traits>
basic_istream<char, traits>&
operator>> (basic_istream<char, traits>&, unsigned char*);
template<class traits>
basic_istream<char, traits>&
operator>> (basic_istream<char, traits>&, signed char*);
TYPES
char_type
The type char_type is a synonym for them template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
ios_type
The type ios_type is a synonym for basic_ios<charT, traits> .
istream
The type istream is an instantiation of class basic_istream on type
char:
typedef basic_istream<char> istream;
istream_type
The type istream_type is a synonym for basic_istream<charT, traits>.
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.
streambuf_type
The type streambuf_type is a synonym for
basic_streambuf<charT, traits>.
traits_type
The type traits_type is a synonym for the template parameter traits.
wistream
The type wistream is an instantiation of class basic_istream on type
wchar_t:
typedef basic_istream<wchar_t> wistream;
PUBLIC CONSTRUCTOR
explicit basic_istream(basic_streambuf<charT, traits>* sb);
Constructs an object of class basic_istream, assigning initial
values to the base class by calling basic_ios::init(sb).
PUBLIC DESTRUCTOR
virtual ~basic_istream();
Destroys an object of class basic_istream.
SENTRY CLASS
explicit sentry(basic_istream<charT,traits>&, bool noskipws=0);
Prepares for formatted or unformatted input. First if the
basic_ios member function tie() is not a null pointer, the
function synchronizes the output sequence with any associated
stream. If noskipws is zero and the ios_base member function
flags() & skipws is nonzero, the function extracts and discards
each character as long as the next available input
character is a white space character. If after any preparation is
completed the basic_ios member function good() is true, the
sentry conversion function operator bool() will return true.
Otherwise it will return false. In multithread environment the
sentry object constructor is responsible for locking the stream
and the stream buffer associated with the stream.
~sentry();
Destroys an object of class sentry. In multithread environment,
the sentry object destructor is responsible for
unlocking the stream and the stream buffer associated with the
stream.
operator bool();
If after any preparation is completed the basic_ios member
function good() is true, the sentry conversion function
operator bool() will return true else it will return false.
EXTRACTORS
istream_type&
operator>>(istream_type&
(*pf) (istream_type&));
Calls pf(*this), then return *this. See, for example, the
function signature ws(basic_istream&).
istream_type&
operator>>(ios_type& (*pf) (ios_type&));
Calls pf(*this), then return *this.
istream_type&
operator>>(ios_base& (*pf) (ios_base&));
Calls pf(*this), then return *this. See, for example, the
function signature dec(ios_base&).
istream_type&
operator>>(bool& n);
Converts a Boolean value, if one is available, and stores it in
n. If the ios_base member function flag() & ios_base::boolalpha
is false it tries to read an integer value, which if found must
be 0 or 1. If the boolalpha flag is true, it reads
characters until it determines whether the characters read are
correct according to the locale function numpunct<>::truename()
or numpunct<>::falsename(). If no match is found, it
calls the basic_ios member function setstate(failbit), which may
throw ios_base::failure.
istream_type&
operator>>(short& n);
Converts a signed short integer, if one is available, and stores
it in n, then returns *this.
istream_type&
operator>>(unsigned short& n);
Converts an unsigned short integer, if one is available, and
stores it in n, then return *this.
istream_type&
operator>>(int& n);
Converts a signed integer, if one is available, and stores it in
n, then return *this.
istream_type&
operator>>(unsigned int& n);
Converts an unsigned integer, if one is available, and stores it
in n, then return *this.
istream_type&
operator>>(long& n);
Converts a signed long integer, if one is available, and stores
it in n, then returns *this.
istream_type&
operator>>(unsigned long& n);
Converts an unsigned long integer, if one is available, and
stores it in n, then returns *this.
istream_type&
operator>>(float& f);
Converts a float, if one is available, and stores it in f, then
returns *this.
istream_type&
operator>>(double& f);
Converts a double, if one is available, and stores it in f, then
returns *this.
istream_type&
operator>>(long double& f);
Converts a long double, if one is available, and stores it in f,
then returns *this.
istream_type&
operator>>(void*& p);
Extracts a void pointer, if one is available, and stores it in p,
then return *this.
istream_type&
operator>>(streambuf_type* sb);
If sb is null, calls the basic_ios member function
setstate(badbit), which may throw ios_base::failure.
Otherwise extracts characters from *this and inserts them in the
output sequence controlled by sb. Characters are extracted
and inserted until any of the following occurs:
+ end-of-file occurs on the input sequence
+ inserting in the output sequence fails
+ an exception occurs
If the function stores no characters, it calls the basic_ios
member function setstate(failbit), which may throw
ios_base::failure. If failure was due to catching an exception
thrown while extracting characters from sb and failbit is on in
exception(), then the caught exception is rethrown.
istream_type& operator>>(streambuf_type& sb);
Extracts characters from *this and inserts them in the
output sequence controlled by sb. Characters are extracted
and inserted until and of the following occurs:
+ end-of-file occurs on the input sequence
+ inserting in the output sequence fails
+ an exception occurs
If the function stores no characters, it calls the basic_ios
member function setstate(failbit), which may throw
ios_base::failure. If failure was due to catching an exception
thrown while extracting characters from sb and failbit is on in
exception(), then the caught exception is rethrown.
UNFORMATTED FUNCTIONS
streamsize
gcount() const;
Returns the number of characters extracted by the last
unformatted input member function called.
int_type
get();
Extracts a character, if one is available. Otherwise, the
function calls the basic_ios member function setstate(failbit),
which may throw ios_base::failure. Returns the character
extracted or traits::eof() if none is available.
istream_type&
get(char_type& c);
Extracts a character, if one is available, and assigns it to c.
Otherwise, the function calls the basic_ios member function
setstate(failbit), which may throw ios_base::failure.
istream_type&
get(char_type* s, streamsize n,char_type delim);
Extracts characters and stores them into successive locations of
an array whose first element is designated by s. Characters
are extracted and stored until any of the following occurs:
+ n-1 characters are stored
+ end-of-file occurs on the input sequence
+ the next available input character == delim.
If the function stores no characters, it calls the basic_ios
member function setstate(failbit), which may throw
ios_base::failure. In any case, it stores a null character into
the next successive location of the array.
istream_type&
get(char_type* s, streamsize n);
Calls get(s,n,widen('0)).
istream_type&
get(streambuf_type& sb,char_type delim);
Extracts characters and inserts them in the output sequence
controlled by sb. Characters are extracted and inserted
until any of the following occurs:
+ end-of-file occurs on the input sequence
+ inserting in the output sequence fails
+ the next available input character == delim.
+ an exception occurs
If the function stores no characters, it calls the basic_ios
member function setstate(failbit), which may throw
ios_base::failure. If failure was due to catching an exception
thrown while extracting characters from sb and failbit is on in
exception(), then the caught exception is rethrown.
istream_type&
get(streambuf_type& sb);
Calls get(sb,widen('0)).
istream_type&
getline(char_type* s, streamsize n, char_type delim);
Extracts characters and stores them into successive locations of
an array whose first element is designated by s. Characters
are extracted and stored until any of the following occurs:
+ n-1 characters are stored
+ end-of-file occurs on the input sequence
+ the next available input character == delim.
If the function stores no characters, it calls the basic_ios
member function setstate(failbit), which may throw
ios_base::failure. In any case, it stores a null character into
the next successive location of the array.
istream_type&
getline(char_type* s, streamsize n);
Calls getline(s,n,widen('0)).
istream_type&
ignore(streamsize n=1, int_type delim=traits::eof());
Extracts characters and discards them. Characters are extracted
until any of the following occurs:
+ n characters are extracted
+ end-of-file occurs on the input sequence
+ the next available input character == delim.
int_type
peek();
Returns traits::eof() if the basic_ios member function good()
returns false. Otherwise, returns the next available character.
Does not increment the current get pointer.
istream_type&
putback(char_type c);
Insert c in the putback sequence.
istream_type&
read(char_type* s, streamsize n);
Extracts characters and stores them into successive locations of
an array whose first element is designated by s. Characters
are extracted and stored until any of the following occurs:
+ n characters are stored
+ end-of-file occurs on the input sequence
If the function does not store n characters, it calls the
basic_ios member function setstate(failbit), which may
throw ios_base::failure.
streamsize
readsome(char_type* s, streamsize n);
Extracts characters and stores them into successive locations of
an array whose first element is designated by s. If
rdbuf()->in_avail() == -1, calls the basic_ios member function
setstate(eofbit).
+ If rdbuf()->in_avail() == 0, extracts no characters
+ If rdbuf()->in_avail() > 0, extracts min( rdbuf()->in_avail(),
n)
In any case the function returns the number of characters
extracted.
istream_type&
seekg(pos_type& pos);
If the basic_ios member function fail() returns false, executes
rdbuf()->pubseekpos(pos), which will position the current pointer
of the input sequence at the position designated by pos.
istream_type&
seekg(off_type& off, ios_base::seekdir dir);
If the basic_ios member function fail() returns false, executes
rdbuf()->pubseekpos(off,dir), which will position the current
pointer of the input sequence at the position designated by
off and dir.
int
sync();
If rdbuf() is a null pointer, return -1. Otherwise, calls
rdbuf()- >pubsync() and if that function returns -1 calls
the basic_ios member function setstate(badbit). The purpose of
this function is to synchronize the internal input buffer,
with the external sequence of characters.
pos_type
tellg();
If the basic_ios member function fail() returns true, tellg()
returns pos_type(off_type(-1)) to indicate failure. Otherwise it
returns the current position of the input sequence by calling
rdbuf()- >pubseekoff(0,cur,in).
istream_type&
unget();
If rdbuf() is not null, calls rdbuf()->sungetc(). If rdbuf() is
null or if sungetc() returns traits::eof(), calls the basic_ios
member function setstate(badbit).
NON MEMBER FUNCTIONS
template<class charT, class traits>
basic_istream<charT, traits>&
operator>>(basic_istream<charT, traits>& is, charT& c);
Extracts a character if one is available, and stores it in c.
Otherwise the function calls the basic_ios member function
setstate(failbit), which may throw ios_base::failure.
template<class charT, class traits>
basic_istream<charT, traits>&
operator>>(basic_istream<charT, traits>& is, charT* s);
Extracts characters and stores them into successive locations of
an array whose first element is designated by s. If the
ios_base member function is.width() is greater than zero, then
is.width() is the maximum number of characters stored. Characters
are extracted and stored until any of the following occurs:
+ if is.witdh()>0, is.witdh()-1 characters are extracted
+ end-of-file occurs on the input sequence
+ the next available input character is a white space.
If the function stores no characters, it calls the basic_ios
member function setstate(failbit), which may throw
ios_base::failure. In any case, it then stores a null character
into the next successive location of the array and calls
width(0).
Template<class traits>
basic_istream<char, traits>&
operator>>(basic_istream<char, traits>& is, unsigned char& c);
Returns is >> (char&)c.
Template<class traits>
basic_istream<char, traits>&
operator>>(basic_istream<char, traits>& is, signed char& c);
Returns is >> (char&)c.
Template<class traits>
basic_istream<char, traits>&
operator>>(basic_istream<char, traits>& is, unsigned char* c);
Returns is >> (char*)c.
Template<class traits>
basic_istream<char, traits>&
operator>>(basic_istream<char, traits>& is, signed char* c);
Returns is >> (char*)c.
template<class charT, class traits>
basic_istream<charT, traits>&
ws(basic_istream<charT, traits>& is);
Skips any white space in the input sequence and returns is.
EXAMPLES
//
// stdlib/examples/manual/istream1.cpp
//
#include<iostream>
#include<istream>
#include<fstream>
void main ( )
{
using namespace std;
float f= 3.14159;
int i= 3;
char s[200];
// open a file for read and write operations
ofstream out("example", ios_base::in | ios_base::out
| ios_base::trunc);
// tie the istream object to the ofstream filebuf
istream in (out.rdbuf());
// output to the file
out << "Annie is the Queen of porting" << endl;
out << f << endl;
out << i << endl;
// seek to the beginning of the file
in.seekg(0);
f = i = 0;
// read from the file using formatted functions
in >> s >> f >> i;
// seek to the beginning of the file
in.seekg(0,ios_base::beg);
// output the all file to the standard output
cout << in.rdbuf();
// seek to the beginning of the file
in.seekg(0);
// read the first line in the file
// "Annie is the Queen of porting"
in.getline(s,100);
cout << s << endl;
// read the second line in the file
// 3.14159
in.getline(s,100);
cout << s << endl;
// seek to the beginning of the file
in.seekg(0);
// read the first line in the file
// "Annie is the Queen of porting"
in.get(s,100);
// remove the newline character
in.ignore();
cout << s << endl;
// read the second line in the file
// 3.14159
in.get(s,100);
cout << s << endl;
// remove the newline character
in.ignore();
// store the current file position
istream::pos_type position = in.tellg();
out << "replace the int" << endl;
// move back to the previous saved position
in.seekg(position);
// output the remain of the file
// "replace the int"
// this is equivalent to
// cout << in.rdbuf();
while( !char_traits<char>::eq_int_type(in.peek(),
char_traits<char>::eof()) )
cout << char_traits<char>::to_char_type(in.get());
cout << "0 << flush;
}
//
// istream example two
//
#include <iostream>
void main ( )
{
using namespace std;
char p[50];
// remove all the white spaces
cin >> ws;
// read characters from stdin until a newline
// or 49 characters have been read
cin.getline(p,50);
// output the result to stdout
cout << p;
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_streambuf, basic_iostream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.6.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
basic_istringstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_istringstream
SYNOPSIS
#include <sstream>
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
class basic_istringstream
: public basic_istream<charT, traits>
DESCRIPTION
The template class basic_istringstream<charT,traits,Allocator>
provides functionality to read from an array in memory. It
supports reading objects of class
basic_string<charT,traits,Allocator>. It uses a basic_stringbuf
object to control the associated storage. It inherits from
basic_istream and therefore can use all the formatted and
unformatted input functions.
INTERFACE
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
class basic_istringstream
: public basic_istream<charT, traits> {
public:
typedef basic_stringbuf<charT, traits, Allocator> sb_type;
typedef basic_ios<charT, traits> ios_type;
typedef basic_string<charT, traits, Allocator> string_type;
typedef traits traits_type;
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_istringstream(ios_base::openmode which =
ios_base::in);
explicit basic_istringstream(const string_type& str,
ios_base::openmode which =
ios_base::in);
virtual ~basic_istringstream();
basic_stringbuf<charT,traits,Allocator> *rdbuf() const;
string_type str() const;
void str(const string_type& str);
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
ios_type
The type ios_type is an instantiation of class basic_ios on type
charT.
istringstream
The type istringstream is an instantiation of class
basic_istringstream on type char:
typedef basic_istringstream<char> istringstream;
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.
sb_type
The type sb_type is an instantiation of class basic_stringbuf on
type charT.
string_type
The type string_type is an instantiation of class basic_string on
type charT.
traits_type
The type traits_type is a synonym for the template parameter traits.
wistringstream
The type wistringstream is an instantiation of class
basic_istringstream on type wchar_t:
typedef basic_istringstream<wchar_t> wistringstream;
CONSTRUCTORS
explicit basic_istringstream(ios_base::openmode which =
ios_base::in);
Constructs an object of class basic_istringstream,
initializing the base class basic_istream with the
associated string buffer. The string buffer is ini-
tialized by calling the basic_stringbuf constructor
basic_stringbuf<charT,traits,Allocator>(which).
explicit basic_istringstream(const string_type& str,
ios_base::openmode which =
ios_base::in);
Constructs an object of class basic_istringstream,
initializing the base class basic_istream with the
associated string buffer. The string buffer is ini-
tialized by calling the basic_stringbuf constructor
basic_stringbuf<charT,traits,Allocator>(str,which).
DESTRUCTOR
virtual ~basic_istringstream();
Destroys an object of class basic_istringstream.
MEMBER FUNCTIONS
basic_stringbuf<charT,traits,Allocator>*
rdbuf() const;
Returns a pointer to the basic_stringbuf associated with the
stream.
string_type
str() const;
Returns a string object of type string_type, which contains a
copy of the underlying buffer contents.
void
str(const string_type& str);
Clears the string buffer and copies the string object str into
it. If the opening mode is in, initialize the input
sequence to point at the first character of the buffer. If
the opening mode is out, initialize the output sequence to
point at the first character of the buffer. If the opening
mode is out | app, initialize the output sequence to point at
the last character of the buffer.
EXAMPLES
//
// stdlib/examples/manual/istringstream.cpp
//
#include<iostream>
#include<sstream>
#include<string>
#include<iomanip>
void main ( )
{
using namespace std;
long l= 20;
wchar_t *ntbs=L"Il avait l'air heureux";
wchar_t c;
wchar_t buf[50];
// create a read/write string-stream object on wide char
// and attach it to an wistringstream object
wistringstream in(ios_base::in | ios_base::out);
// tie the ostream object to the wistringstream object
wostream out(in.rdbuf());
// output ntbs in out
out << ntbs;
// output each word on a separate line
while ( in.get(c) )
{
if ( c == L' ' )
wcout << endl;
else
wcout << c;
}
wcout << endl << endl;
// move back the input sequence to the beginning
in.seekg(0);
// clear the state flags
in.clear();
// does the same thing as the previous code
// output each word on a separate line
while ( in >> buf )
wcout << buf << endl;
wcout << endl << endl;
// create a tiny string object
string test_string("Il dormait pour l'eternite");
// create a read/write string-stream object on char
// and attach it to an istringstream object
istringstream in_bis(ios_base:: in | ios_base::out |
ios_base::app );
// create an ostream object
ostream out_bis(in_bis.rdbuf());
// initialize the string buffer with test_string
in_bis.str(test_string);
out_bis << endl;
// output the base info before each integer
out_bis << showbase;
ostream::pos_type pos= out_bis.tellp();
// output l in hex with a field with of 20
out_bis << hex << setw(20) << l << endl;
// output l in oct with a field with of 20
out_bis << oct << setw(20) << l << endl;
// output l in dec with a field with of 20
out_bis << dec << setw(20) << l << endl;
// output the all buffer
cout << in_bis.rdbuf();
// seek the input sequence to pos
in_bis.seekg(pos);
int a,b,d;
// read the previous outputted integer
in_bis >> a >> b >> d;
// output 3 times 20
cout << a << endl << b << endl << d << endl;
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_stringbuf, basic_string,
basic_ostringstream, basic_stringstream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.7.2
STANDARDS CONFORMANC
ANSI X3J16/ISO WG21 Joint C++ Committee
basic_ofstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_ofstream,ofstream
This page describes the ANSI basic_ofstream class. If you would
like information on the pre-ANSI ofstream class, use the command:
help cxxl
SYNOPSIS
#include <fstream>
template<class charT, class traits = char_traits<charT> >
class basic_ofstream
: public basic_ostream<charT, traits>
DESCRIPTION
The template class basic_ofstream<charT,traits> supports writing
into named files or other devices associated with a file
descriptor. It uses a basic_filebuf object to control the
associated sequences. It inherits from basic_ostream and
can therefore use all the formatted and unformatted output
functions.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_ofstream
: public basic_ostream<charT, traits> {
public:
typedef basic_ios<charT, traits> ios_type;
typedef charT char_type;
typedef traits traits_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
basic_ofstream();
explicit basic_ofstream(const char *s,
ios_base::openmode mode =
ios_base::out,
long protection = 0666);
explicit basic_ofstream(int fd);
basic_ofstream(int fd, char_type* buf, int len);
virtual ~basic_ofstream();
basic_filebuf<charT, traits> *rdbuf() const;
bool is_open();
void open(const char *s, ios_base::openmode mode =
ios_type::out, long protection = 0666);
void close();
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
off_type
The type off_type is a synonym of type traits::off_type.
ofstream
The type ofstream is an instantiation of class basic_ofstream on
type char:
typedef basic_ofstream<char> ofstream;
int_type
The type int_type is a synonym of type traits::in_type.
ios_type
The type ios_type is an instantiation of class basic_ios on type
charT.
pos_type
The type pos_type is a synonym of type traits::pos_type.
traits_type
The type traits_type is a synonym for the template parameter traits.
wofstream
The type wofstream is an instantiation of class basic_ofstream on
type wchar_t:
typedef basic_ofstream<wchar_t> wofstream;
CONSTRUCTORS
basic_ofstream();
Constructs an object of class basic_ofstream<charT,traits>,
initializing the base class basic_ostream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). After construction a
file can be attached to the basic_oftream object using the
open member function.
basic_ofstream(const char* s,
ios_base::openmode mode= ios_base::in,
long protection= 0666);
Constructs an object of class
basic_ofstream<charT,traits>, initializing the base class
basic_ostream with the associated file buffer, which is
initialized by calling the basic_filebuf constructor
basic_filebuf<charT,traits>(). The constructor then calls
the open function open(s,mode,protection) in order to
attach the file whose name is pointed at by s, to the
basic_oftream object. The third argument, protection, is
used as the file permissions. It does not appear in the
Standard C++ description and is provided as an extension.
It determines the file read/write/execute permissions
under UNIX. It is more limited under DOS since files are
always readable and do not have special execute permission.
explicit basic_ofstream(int fd);
Constructs an object of class basic_ofstream<charT,traits>,
initializing the base class basic_ostream with the
associated file buffer, which is initialized by calling the
basic_filebuf constructor basic_filebuf<charT,traits>(). The
constructor then calls the basic_filebuf open function
open(fd) in order to attach the file descriptor fd to the
basic_oftream object. This constructor is not described in
the C++ standard, and is provided as an extension in order
to manipulate pipes, sockets or other UNIX devices, that can be
accessed through file descriptors. If the function fails, it sets
ios_base::failbit.
basic_ofstream(int fd, char_type* buf,int len);
Constructs an object of class basic_ofstream<charT,traits>,
initializing the base class basic_ostream with the
associated file buffer, which is initialized by calling the
basic_filebuf constructor basic_filebuf<charT,traits>(). The
constructor then calls the basic_filebuf open function
open(fd) in order to attach the file descriptor fd to the
basic_oftream object. The underlying buffer is then
replaced by calling the basic_filebuf member function setbuf
with parameters buf and len. This constructor is not described
in the C++ standard, and is provided as an extension in order
to manipulate pipes, sockets or other UNIX devices, that can
be accessed through file descriptors. It also maintains
compatibility with the old iostreams library. If the function
fails, it sets ios_base::failbit.
DESTRUCTOR
virtual ~basic_ofstream();
Destroys an object of class basic_ofstream.
MEMBER FUNCTIONS
void
close();
Calls the associated basic_filebuf function close() and if this
function fails, it calls the basic_ios member function
setstate(failbit).
bool
is_open();
Calls the associated basic_filebuf function is_open() and return
its result.
void
open(const char* s,ios_base::openmode =
ios_base::out, long protection = 0666);
Calls the associated basic_filebuf function
open(s,mode,protection) and, if this function fails opening the
file, calls the basic_ios member function setstate(failbit).
The third argument, protection, is used as the file permis-
sions. It does not appear in the Standard C++ description and
is provided as an extension. It determines the file
read/write/execute permissions under UNIX, and is more limited
under DOS since files are always readable and do not have special
execute permission.
basic_filebuf<charT,traits>*
rdbuf() const;
Returns a pointer to the basic_filebuf associated with the stream.
EXAMPLES
See basic_fstream, basic_ifstream and basic_filebuf examples.
SEE ALSO
char_traits, ios_base, basic_ios,
basic_filebuf, basic_ifstream, basic_fstream
Working Paper for Draft Proposed International Standard for Information
Systems--Programming Language C++, Section 27.8.1.8
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
basic_ostream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_ostream
SYNOPSIS
#include <ostream>
template<class charT, class traits = char_traits<charT> >
class basic_ostream
: virtual public basic_ios<charT, traits>
DESCRIPTION
The class basic_ostream defines a number of member function
signatures that assist in formatting and writing output to sequences
controlled by a stream buffer.
Two groups of member function signatures share common properties:
the formatted output functions (or insertors) and the
unformatted output functions. Both groups of functions
insert characters by calling basic_streambuf member functions. They
both begin by constructing an object of class basic_ostream::sentry
and, if this object is in good state after construction,
the function tries to perform the requested output. The sentry
object performs exception-safe initialization, such as
controlling the status of the stream or locking it in multithread
environment.
Some formatted output functions generate the requested output by
converting a value from some scalar to text form and inserting
the converted text in the output sequence. The conversion behavior
is locale dependent, and directly depend on the locale object
imbued in the stream.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_ostream
:virtual public basic_ios<charT, traits> {
public:
typedef basic_ostream<charT, traits> ostream_type;
typedef basic_ios<charT, traits> ios_type;
typedef traits traits_type;
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_ostream(basic_streambuf<charT, traits> *sb);
virtual ~basic_ostream();
class sentry {
public:
explicit sentry(basic_ostream<charT,traits>&);
~sentry();
operator bool ();
};
ostream_type& operator<<(ostream_type& (*pf)(ostream_type&));
ostream_type& operator<<(ios_base& (*pf)(ios_base&));
ostream_type& operator<<(ios_type& (*pf)(ios_type&));
ostream_type& operator<<(bool n);
ostream_type& operator<<(short n);
ostream_type& operator<<(unsigned short n);
ostream_type& operator<<(int n);
ostream_type& operator<<(unsigned int n);
ostream_type& operator<<(long n);
ostream_type& operator<<(unsigned long n);
ostream_type& operator<<(float f);
ostream_type& operator<<(double f);
ostream_type& operator<<(long double f);
ostream_type& operator<<(void *p);
ostream_type& operator<<(basic_streambuf<char_type, traits>& sb);
ostream_type& operator<<(basic_streambuf<char_type, traits> *sb);
ostream_type& put(char_type c);
ostream_type& write(const char_type *s, streamsize n);
ostream_type& flush();
ostream_type& seekp(pos_type );
ostream_type& seekp(off_type , ios_base::seekdir );
pos_type tellp();
protected:
basic_ostream();
};
//global functions
template <class charT, class traits>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>&, charT);
template <class charT, class traits>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>&, char);
template <class traits>
basic_ostream<char,traits>&
operator<<(basic_ostream<char,traits>&, char);
template <class charT, class traits>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>&, const charT*);
template <class charT, class traits>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>&, const char*);
template <class traits>
basic_ostream<char,traits>&
operator<<(basic_ostream<char,traits>&, const char*);
template <class traits>
basic_ostream<char,traits>&
operator<<(basic_ostream<char,traits>&, unsigned char);
template <class traits>
basic_ostream<char,traits>&
operator<<(basic_ostream<char,traits>&, signed char);
template <class traits>
basic_ostream<char,traits>&
operator<<(basic_ostream<char,traits>&, const unsigned char*);
template <class traits>
basic_ostream<char,traits>&
operator<<(basic_ostream<char,traits>&, const signed char*);
template<class charT, class traits>
basic_ostream<charT, traits>&
endl(basic_ostream<charT, traits>& os);
template<class charT, class traits>
basic_ostream<charT, traits>&
ends(basic_ostream<charT, traits>& os);
template<class charT, class traits>
basic_ostream<charT, traits>&
flush(basic_ostream<charT, traits>& os);
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
ios_type
The type ios_type is a synonym for basic_ios<charT, traits>.
off_type
The type off_type is a synonym of type traits::off_type.
ostream
The type ostream is an instantiation of class basic_ostream on type
char:
typedef basic_ostream<char> ostream;
ostream_type
The type ostream_type is a synonym for basic_ostream<charT, traits>.
pos_type
The type pos_type is a synonym of type traits::pos_type.
traits_type
The type traits_type is a synonym for the template parameter traits.
wostream
The type wostream is an instantiation of class basic_ostream on type
wchar_t:
typedef basic_ostream<wchar_t> wostream;
CONSTRUCTOR
explicit basic_ostream(basic_streambuf<charT, traits>* sb);
Constructs an object of class basic_ostream, assigning initial
values to the base class by calling
basic_ios<charT,traits>::init(sb).
DESTRUCTOR
virtual ~basic_ostream();
Destroys an object of class basic_ostream.
SENTRY CLASS
explicit sentry(basic_ostream<charT,traits>&);
Prepares for formatted or unformatted output. First if the
basic_ios member function tie() is not a null pointer, the
function synchronizes the output sequence with any associated
stream. If after any preparation is completed the
basic_ios member function good() is true, the sentry conversion
function operator bool () will return true. Otherwise it will
return false. In multithread environment the sentry object
constructor is responsible for locking the stream and the
stream buffer associated with the stream.
~sentry();
Destroys an object of class sentry. If the ios_base member
function flags() & unitbuf == true, then flush the buffer.
In multithread environment the sentry object destructor is
responsible for unlocking the stream and the stream buffer
associated with the stream.
operator bool();
If after any preparation is completed the ios_base member
function good() is true, the sentry conversion function
operator bool() will return true else it will return false.
INSERTORS
ostream_type&
operator<<(ostream_type& (*pf) (ostream_type&));
Calls pf(*this), then return *this. See, for example, the
function signature endl(basic_ostream&).
ostream_type&
operator<<(ios_type& (*pf) (ios_type&));
Calls pf(*this), then return *this.
ostream_type&
operator<<(ios_base& (*pf) (ios_base&));
Calls pf(*this), then return *this. See, for example, the
function signature dec(ios_base&).
ostream_type&
operator<<(bool n);
Converts the boolean value n, and outputs it into the
basic_ostream object's buffer. If the ios_base member function
flag() & ios_base::boolalpha is false it tries to write an
integer value, which must be 0 or 1. If the boolalpha flag is
true, it writes characters according to the locale function
numpunct<>::truename() or numpunct<>::falsename().
ostream_type&
operator<<(short n);
Converts the signed short integer n, and output it into the stream
buffer, then return *this.
ostream_type&
operator<<(unsigned short n);
Converts the unsigned short integer n, and output it into the
stream buffer, then return *this.
ostream_type&
operator<<(int n);
Converts the signed integer n, and output it into the stream
buffer, then return *this.
ostream_type&
operator<<(unsigned int n);
Converts the unsigned integer n, and output it into the stream
buffer, then return *this.
ostream_type&
operator<<(long n);
Converts the signed long integer n, and output it into the stream
buffer, then return *this.
ostream_type&
operator<<(unsigned long n);
Converts the unsigned long integer n, and output it into the
stream buffer, then return *this.
ostream_type&
operator<<(float f);
Converts the float f and output it into the stream buffer, then
return *this.
ostream_type&
operator<<(double f);
Converts the double f and output it into the stream buffer, then
return *this.
ostream_type&
operator<<(long double f);
Converts the long double f and output it into the stream buffer,
then return *this.
ostream_type&
operator<<(void *p);
Converts the pointer p, and output it into the stream buffer,
then return *this.
ostream_type&
operator<<(basic_streambuf<charT,traits> *sb);
If sb is null calls the basic_ios member function
setstate(badbit). Otherwise gets characters from sb and
inserts them into the stream buffer until any of the
following occurs:
+ end-of-file occurs on the input sequence.
+ inserting in the output sequence fails
+ an exception occurs while getting a character from sb
If the function inserts no characters or if it stopped because an
exception was thrown while extracting a character, it calls
the basic_ios member function setstate(failbit). If an
exception was thrown while extracting a character it is
rethrown.
ostream_type&
operator<<(basic_streambuf<charT,traits>& sb);
Gets characters from sb and inserts them into the stream buffer
until any of the following occurs:
+ end-of-file occurs on the input sequence.
+ inserting in the output sequence fails
+ an exception occurs while getting a character from sb
If the function inserts no characters or if it stopped because an
exception was thrown while extracting a character, it calls
the basic_ios member function setstate(failbit). If an
exception was thrown while extracting a character it is
rethrown.
UNFORMATTED FUNCTIONS
ostream_type&
flush();
If rdbuf() is not a null pointer, calls rdbuf()->pubsync() and
returns *this. If that function returns -1 calls
setstate(badbit).
ostream_type&
put(char_type c);
Inserts the character c. If the operation fails, calls the
basic_ios member function setstate(badbit).
ostream_type&
seekp(pos_type pos);
If the basic_ios member function fail() returns false, executes
rdbuf()->pubseekpos(pos), which will position the current pointer
of the output sequence at the position designated by pos.
ostream_type&
seekp(off_type off, ios_base::seekdir dir);
If the basic_ios member function fail() returns false, executes
rdbuf()->pubseekpos(off,dir), which will position the current
pointer of the output sequence at the position designated by
off and dir.
pos_type
tellp();
If the basic_ios member function fail() returns true, tellp()
returns pos_type(off_type(-1)) to indicate failure. Otherwise it
returns the current position of the output sequence by
calling rdbuf()-> pubseekoff(0,cur, out).
ostream_type&
write(const char_type* s, streamsize n);
Obtains characters to insert from successive locations of an
array whose first element is designated by s. Characters are
inserted until either of the following occurs:
+ n characters are inserted
+ inserting in the output sequence fails
In the second case the function calls the basic_ios member function
setstate(badbit). The function returns *this.
NON MEMBER FUNCTIONS
template<class charT, class traits>
basic_ostream<charT, traits>&
endl(basic_ostream<charT, traits>& os);
Outputs a newline character and flush the buffer, then returns os.
template<class charT, class traits>
basic_ostream<charT, traits>&
ends(basic_ostream<charT, traits>& os);
Inserts a null character into the output sequence, then returns os.
template<class charT, class traits>
basic_ostream<charT, traits>&
flush(basic_ostream<charT, traits>& os);
Flushes the buffer, then returns os.
template<class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os, charT c);
Outputs the character c of type charT into the basic_ostream
object's buffer. Both the stream and the stream buffer are
instantiated on type charT. Padding is not ignored.
template<class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os, char c);
Outputs the character c of type char into the basic_ostream
object's buffer. Both the stream and the stream buffer are
instantiated on type charT. Conversion from characters of type
char to characters of type charT is performed by the
basic_ios member function widen. padding is not ignored.
template<class traits>
basic_ostream<char, traits>&
operator<<(basic_ostream<char, traits>& os, char c);
Outputs the character c of type char into the basic_ostream
object's buffer. Both the stream and the stream buffer are
instantiated on type char. Padding is not ignored.
template<class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os, const charT* s);
Outputs the null-terminated-byte-string s of type charT* into the
basic_ostream object's buffer. Both the stream and the stream
buffer are instantiated on type charT.
template<class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os, const char* s);
Outputs the null-terminated-byte-string s of type char* into the
basic_ostream object's buffer. Both the stream and the stream
buffer are instantiated on type charT. Conversion from characters
of type char to characters of type charT is performed by the
basic_ios member function widen.
template<class traits>
basic_ostream<char, traits>&
operator<<(basic_ostream<char, traits>& os, const char* s);
Outputs the null-terminated-byte-string s of type char* into the
basic_ostream object's buffer. Both the stream and the stream
buffer are instantiated on type char.
template<class traits>
basic_ostream<char, traits>&
operator<<(basic_ostream<char, traits>& os, unsigned char c);
Returns os << (char)c.
template<class traits>
basic_ostream<char, traits>&
operator<<(basic_ostream<char, traits>& os, signed char c);
Returns os << (char)c.
template<class traits>
basic_ostream<char, traits>&
operator<<(basic_ostream<char, traits>& os, unsigned char* c);
Returns os << (char*)c.
template<class traits>
basic_ostream<char, traits>&
operator<<(basic_ostream<char, traits>& os, signed char* c);
Returns os << (char*)c.
FORMATTING
The formatting is done through member functions or manipulators.
Manipulators Member Functions
showpos setf(ios_base::showpos)
noshowpos unsetf(ios_base::showpos)
showbase setf(ios_base::showbase)
noshowbase unsetf(ios_base::showbase)
uppercase setf(ios_base::uppercase)
nouppercase unsetf(ios_base::uppercase)
showpoint setf(ios_base::showpoint)
noshowpoint unsetf(ios_base::showpoint)
boolalpha setf(ios_base::boolalpha)
noboolalpha unsetf(ios_base::boolalpha)
unitbuf setf(ios_base::unitbuf)
nounitbuf unsetf(ios_base::unitbuf)
internal setf(ios_base::internal,
ios_base::adjustfield)
left setf(ios_base::left,
ios_base::adjustfield)
right setf(ios_base::right,
ios_base::adjustfield)
dec setf(ios_base::dec,
ios_base::basefield)
hex setf(ios_base::hex,
ios_base::basefield)
oct setf(ios_base::oct,
ios_base::basefield)
fixed setf(ios_base::fixed,
ios_base::floatfield)
scientific setf(ios_base::scientific,
ios_base::floatfield)
resetiosflags
(ios_base::fmtflags flag) setf(0,flag)
setiosflags
(ios_base::fmtflags flag) setf(flag)
setbase(int base) See above
setfill(char_type c) fill(c)
setprecision(int n) precision(n)
setw(int n) width(n)
DESCRIPTION
showpos Generates a + sign in non-negative generated numeric output
showbase Generates a prefix indicating the numeric base of generated
integer output
uppercase Replaces certain lowercase letters with their uppercase
equivalents in generated output
showpoint Generates a decimal-point character unconditionally in gen-
erated floating-point output
boolalpha Insert and extract bool type in alphabetic format
unitbuf Flushes output after each output operation
internal Adds fill characters at a designated internal point in certain
generated output, or identical to right if no such point is
designated
left Adds fill characters on the right (final positions) of certain
generated output
right Adds fill characters on the left (initial positions) of certain
generated output
dec Converts integer input or generates integer output in decimal base
hex Converts integer input or generates integer output in hexadecimal
base
oct Converts integer input or generates integer output in octal base
fixed Generates floating-point output in fixed-point notation
scientific Generates floating-point output in scientific notation
resetiosflagss
(ios_base::fmtflags flag) Resets the fmtflags field flag
setiosflags
(ios_base::fmtflags flag) Set up the flag flag
setbase(int base) Converts integer input or generates integer output
in base base. The parameter base can be 8, 10
or 16.
setfill(char_type c) Set the character used to pad (fill) an output
conversion to the specified field width
setprecision(int n) Set the precision (number of digits after the
decimal point) to generate on certain output
conversions
setw(int n) Set the field with (number of characters) to generate
on certain output conversions
EXAMPLES
//
// stdlib/examples/manual/ostream1.cpp
//
#include<iostream>
#include<ostream>
#include<sstream>
#include<iomanip>
void main ( )
{
using namespace std;
float f= 3.14159;
int i= 22;
char* s= "Randy is the king of stdlib";
// create a read/write stringbuf object on tiny char
// and attach it to an istringstream object
istringstream in( ios_base::in | ios_base::out );
// tie the ostream object to the istringstream object
ostream out(in.rdbuf());
out << "test beginning !" << endl;
// output i in hexadecimal
out << hex << i <<endl;
// set the field width to 10
// set the padding character to '@'
// and output i in octal
out << setw(10) << oct << setfill('@') << i << endl;
// set the precision to 2 digits after the separator
// output f
out << setprecision(3) << f << endl;
// output the 17 first characters of s
out.write(s,17);
// output a newline character
out.put('0);
// output s
out << s << endl;
// output the all buffer to standard output
cout << in.rdbuf();
}
//
// stdlib/examples/manual/ostream2.cpp
//
#include<iostream>
#include<ostream>
#include<sstream>
void main ( )
{
using namespace std;
float f= 3.14159;
wchar_t* s= L"Kenavo !";
// create a read/write stringbuf object on wide char
// and attach it to an wistringstream object
wistringstream in( ios_base::in | ios_base::out );
// tie the wostream object to the wistringstream object
wostream out(in.rdbuf());
out << L"test beginning !" << endl;
// output f in scientific format
out << scientific << f <<endl;
// store the current put-pointer position
wostream::pos_type pos = out.tellp();
// output s
out << s << endl;
// output the all buffer to standard output
wcout << in.rdbuf() << endl;
// position the get-pointer
in.seekg(pos);
// output s
wcout << in.rdbuf() << endl;
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_streambuf, basic_iostream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.6.2.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
basic_ostringstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_ostringstream
SYNOPSIS
#include <sstream>
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
class basic_ostringstream
: public basic_ostream<charT, traits>
DESCRIPTION
The template class basic_ostringstream<charT,traits,Allocator>
provides functionality to write to an array in memory. It
supports writing objects of class
basic_string<charT,traits,Allocator>. It uses a basic_stringbuf
object to control the associated storage. It inherits from
basic_ostream and therefore can use all the formatted and
unformatted output functions.
INTERFACE
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
class basic_ostringstream
: public basic_ostream<charT, traits> {
public:
typedef basic_stringbuf<charT, traits, Allocator> sb_type;
typedef basic_ios<charT, traits> ios_type;
typedef basic_string<charT, traits, Allocator> string_type;
typedef traits traits_type;
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_ostringstream(ios_base::openmode which =
ios_base::out);
explicit basic_ostringstream(const string_type& str,
ios_base::openmode which =
ios_base::out);
virtual ~basic_ostringstream();
basic_stringbuf<charT,traits,Allocator> *rdbuf() const;
string_type str() const;
void str(const string_type& str);
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
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.
ostringstream
The type ostringstream is an instantiation of class
basic_ostringstream on type char:
typedef basic_ostringstream<char> ostringstream;
pos_type
The type pos_type is a synonym of type traits::pos_type.
sb_type
The type sb_type is an instantiation of class basic_stringbuf
on type charT.
string_type
The type string_type is an instantiation of class basic_string
on type charT.
traits_type
The type traits_type is a synonym for the template parameter
traits.
wostringstream
The type wostringstream is an instantiation of class
basic_ostringstream on type wchar_t:
typedef basic_ostringstream<wchar_t> wostringstream;
CONSTRUCTORS
explicit basic_ostringstream(ios_base::openmode which =
ios_base::out);
Constructs an object of class
basic_ostringstream, initializing the base
class basic_ostream with the associated
string buffer. The string buffer is initial-
ized by calling the basic_stringbuf con-
structor
basic_stringbuf<charT,traits,Allocator>(which).
explicit basic_ostringstream(const string_type& str,
ios_base::openmode which =
ios_base::out);
Constructs an object of class
basic_ostringstream, initializing the base
class basic_ostream with the associated
string buffer. The string buffer is initial-
ized by calling the basic_stringbuf con-
structor
basic_stringbuf<charT,traits,Allocator>(str,which).
DESTRUCTOR
virtual ~basic_ostringstream();
Destroys an object of class basic_ostringstream.
MEMBER FUNCTIONS
basic_stringbuf<charT,traits,Allocator>*
rdbuf() const;
Returns a pointer to the basic_stringbuf associated with the
stream.
string_type
str() const;
Returns a string object of type string_type whose contents is a
copy of the underlying buffer contents.
void
str(const string_type& str);
Clears the underlying string buffer and copies the string object
str into it. If the opening mode is in, initialize the input
sequence to point at the first character of the buffer. If
the opening mode is out, initialize the output sequence to
point at the first character of the buffer. If the opening
mode is out | app, initialize the output sequence to
point at the last character of the buffer.
EXAMPLES
See basic_stringstream, basic_istringstream and basic_stringbuf
examples.
SEE ALSO
char_traits, ios_base, basic_ios,
basic_stringbuf, basic_string,
basic_istringstream, basic_stringstream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.7.2.3
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
basic_streambuf
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_streambuf,streambuf
This page describes the ANSI streambuf class. If you would like
information on the pre-ANSI streambuf class, use the
command:
help cxxl
SYNOPSIS
#include <streambuf>
template<class charT, class traits = char_traits<charT> >
class basic_streambuf;
DESCRIPTION
The class template basic_streambuf<charT,traits> serves as an
abstract base class for deriving various stream buffers whose
objects each control two character sequences:
+ A character input sequence;
+ A character output sequence.
Each sequence is characterized by three pointers which, if non-null,
all point into the same charT array object. The array object
represents, at any moment, a subsequence of characters from the
sequence. Operations performed on a sequence alter the values
stored in these pointers, perform reads and writes directly
to or from associated sequences, and alter "the stream position" and
conversion state as needed to maintain this subsequence rela-
tionship. The three pointers are:
+ The beginning pointer, or lowest element address in the array;
+ The next pointer, or next element address that is a current
candidate for reading or writing;
+ The end pointer, or first element address beyond the end of
the array.
Stream buffers can impose various constraints on the sequences they
control, including:
+ The controlled input sequence may be unreadable;
+ The controlled output sequence may be unwritable;
+ The controlled sequences can be associated with the
contents of other representations for character sequences, such
as external files;
+ The controlled sequences can impose limitations on how the
program can read characters from a sequence, write characters
to a sequence, put characters back into an input sequence,
or alter the stream position.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_streambuf {
public:
typedef charT char_type;
typedef traits traits_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
virtual ~basic_streambuf();
locale pubimbue( const locale& loc);
locale getloc() const;
basic_streambuf<char_type, traits> *
pubsetbuf(char_type *s, streamsize n);
pos_type pubseekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
pos_type pubseekpos(pos_type sp, ios_base::openmode which =
ios_base::in | ios_base::out);
int pubsync();
ios_base::openmode which_open_mode();
streamsize in_avail();
int_type snextc();
int_type sbumpc();
int_type sgetc();
streamsize sgetn(char_type *s, streamsize n);
int_type sputbackc(char_type c);
int sungetc();
int_type sputc(char_type c);
streamsize sputn(const char_type *s, streamsize n);
protected:
basic_streambuf();
char_type *eback() const;
char_type *gptr() const;
char_type *egptr() const;
void gbump(int n);
void setg(char_type *gbeg_arg,char_type *gnext_arg,
char_type *gend_arg);
char_type *pbase() const;
char_type *pptr() const;
char_type *epptr() const;
void pbump(int n);
void setp(char_type *pbeg_arg,char_type *pend_arg);
virtual void imbue( const locale& loc);
virtual int_type overflow(int_type c = traits::eof());
virtual int_type pbackfail(int_type c = traits::eof());
virtual int showmanyc();
virtual int_type underflow();
virtual int_type uflow();
virtual streamsize xsgetn(char_type *s, streamsize n);
virtual streamsize xsputn(const 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 basic_streambuf<charT, traits>*
setbuf(char_type *s, streamsize n);
virtual int sync();
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
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.
streambuf
The type streambuf is an instantiation of class
basic_streambuf on type char:
typedef basic_streambuf<char> streambuf;
traits_type
The type traits_type is a synonym for the template parameter traits.
wstreambuf
The type wstreambuf is an instantiation of class basic_streambuf on
type wchar_t:
typedef basic_streambuf<wchar_t> wstreambuf;
PUBLIC CONSTRUCTOR
basic_streambuf();
Constructs an object of class basic_streambuf and initializes all
its pointer member objects to null pointers and the getloc()
member function to return the value of locale::locale().
PUBLIC DESTRUCTOR
virtual ~basic_streambuf();
Destroys an object of class basic_streambuf.
PUBLIC MEMBER FUNCTIONS
locale
getloc() const;
If pubimbue() has ever been called, returns the last value of loc
supplied, otherwise, the default locale locale::locale() in
effect at the time of construction.
streamsize
in_avail();
If a read position is available, returns the number of available
character in the input sequence. Otherwise calls the protected
function showmanyc().
locale
pubimbue(const locale& loc);
Calls the protected function imbue(loc).
pos_type
pubseekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out );
Calls the protected function seekoff(off,way,which).
pos_type
pubseekpos(pos_type sp, ios_base::openmode which=
ios_base::in | ios_base::out );
Calls the protected function seekpos(sp,which).
basic_streambuf<char_type,traits>*
pubsetbuf(char_type* s,streamsize n);
Calls the protected function setbuf(s,n) .
int
pubsync();
Calls the protected function sync().
int_type
sbumpc();
If the input sequence read position is not available, calls the
function uflow(), otherwise returns *gptr() and increments
the next pointer for the input sequence.
int_type
sgetc();
If the input sequence read position is not available, calls the
protected function underflow(), otherwise returns *gptr() .
streamsize
sgetn(char_type* s, streamsize n);
Calls the protected function xsgetn(s,n).
int_type
snextc();
Calls the function sbumpc() and if it returns traits::eof(),
returns traits::eof(); otherwise calls the function sgetc() .
int_type
sputbackc(char_type c);
If the input sequence putback position is not available, or if
traits::eq(c,gptr() [-1]) returns false, calls the protected
function pbackfail(c), otherwise decrements the next
pointer for the input sequence and returns *gptr().
int_type
sputc(char_type c);
If the output sequence write position is not available, calls the
protected function overflow(traits::to_int_type( c )).
Otherwise, stores c at the next pointer for the output
sequence, increments the pointer, and returns *pptr() .
streamsize
sputn(const char_type* s, streamsize n);
Calls the protected function xsputn(s,n).
int_type
sungetc();
If the input sequence putback position is not available, calls
the protected function pbackfail(). Otherwise decrements
the next pointer for the input sequence and returns *gptr().
ios_base::openmode
which_open_mode();
Returns the mode in which the stream buffer is opened. This
function is not described in the C++ standard.
PROTECTED MEMBER FUNCTIONS
char_type*
eback() const;
Returns the beginning pointer for the input sequence.
char_type*
egptr() const;
Returns the end pointer for the input sequence.
char_type*
epptr() const;
Returns the end pointer for the output sequence.
void
gbump(int n);
Advances the next pointer for the input sequence by n.
char_type*
gptr() const;
Returns the next pointer for the input sequence.
void
imbue(const locale&);
Changes any translations based on locale. The default behavior is
to do nothing, this function has to be overloaded in the
classes derived from basic_streambuf. The purpose of this
function is to allow the derived class to be informed of changes
in locale at the time they occur. The new imbued locale object
is only used by the stream buffer, it does not affect the stream
itself.
int_type
overflow(int_type c = traits::eof() );
The member functions sputc() and sputn() call this function in
case that not enough room can be found in the put buffer to
accommodate the argument character sequence. The function
returns traits::eof() if it fails to make more room
available, or to empty the buffer by writing the characters
to their output device.
int_type
pbackfail(int_type c = traits::eof() );
If c is equal to traits::eof(), gptr() is moved back one position
otherwise c is prepended. The function returns traits::eof() to
indicate failure.
char_type*
pbase() const;
Returns the beginning pointer for the output sequence.
void
pbump(int n);
Advances the next pointer for the output sequence by n.
char_type*
pptr() const;
Returns the next pointer for the output sequence.
pos_type
seekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out );
Alters the stream positions within one or more of the controlled
sequences in a way that is defined separately for each class
derived from basic_streambuf. The default behavior is to return
an object of type pos_type that stores an invalid stream posi-
tion.
pos_type
seekpos(pos_type sp, ios_base::openmode which=
ios_base::in | ios_base::out );
Alters the stream positions within one or more of the controlled
sequences in a way that is defined separately for each class
derived from basic_streambuf. The default behavior is to return
an object of class pos_type that stores an invalid stream posi-
tion.
basic_streambuf*
setbuf(char_type* s, streamsize n);
Performs an operation that is defined separately for each class
derived from basic_streambuf. The purpose of this function is to
allow the user to provide his own buffer, or to resize the
current buffer.
void
setg(char_type* gbeg, char_type* gnext, char_type* gend);
Sets up private member for the following to be true:
eback() == gbeg, gptr() == gnext and egptr() == gend
void
setp(char_type* pbeg, char_type* pend);
Sets up private member for the following to be true:
pbase() == pbeg, pptr() == pbeg and epptr() == pend
int
showmanyc();
Returns the number of characters available in the internal
buffer, or -1.
int
sync();
Synchronizes the controlled sequences with the internal buffer,
in a way that is defined separately for each class derived
from basic_streambuf. The default behavior is to do nothing. On
failure the return value is -1.
int_type
underflow();
The public members of basic_streambuf call this function only if
gptr() is null or gptr() >= egptr(). This function returns the
character pointed at by gptr() if gptr() is not null and if
gptr() < egptr(). Otherwise the function try to read
character into the buffer, and if it fails return traits::eof().
int_type
uflow();
Calls underflow() and if underflow() returns traits::eof(),
returns traits::eof(). Otherwise, does gbump(1) and returns the
value of *gptr().
streamsize
xsgetn(char_type* s, streamsize n);
Assigns up to n characters to successive elements of the array
whose first element is designated by s. The characters are read
from the input sequence. Assigning stops when either n
characters have been assigned or a call to sbumpc() would
return traits::eof(). The function returns the number of
characters read.
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. Writing stops when either n
characters have been written or a call to sputc() would return
traits::eof(). The function returns the number of characters
written.
SEE ALSO
char_traits, basic_filebuf, basic_stringbuf,
strstreambuf
Working Paper for Draft Proposed International Standard for Information
Systems--Programming Language C++, Section 27.5
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
basic_stringstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_stringstream
SYNOPSIS
#include <sstream>
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
class basic_stringstream
: public basic_iostream<charT, traits>
DESCRIPTION
The template class basic_stringstream<charT,traits,Allocator>
provides functionality to read and write to an array in
memory. It supports writing and reading objects of class
basic_string<charT,traits,Alocator>. It uses a basic_stringbuf
object to control the associated storage. It inherits from
basic_iostream and therefore can use all the formatted and
unformatted output and input functions.
INTERFACE
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
class basic_stringstream
: public basic_iostream<charT, traits> {
public:
typedef basic_stringbuf<charT, traits, Allocator> sb_type;
typedef basic_ios<charT, traits> ios_type;
typedef basic_string<charT, traits, Allocator> string_type;
typedef traits traits_type;
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_stringstream(ios_base::openmode which =
ios_base::out | ios_base::in);
explicit basic_stringstream(const string_type& str,
ios_base::openmode which =
ios_base::out | ios_base::in);
virtual ~basic_stringstream();
basic_stringbuf<charT,traits,Allocator> *rdbuf() const;
string_type str() const;
void str(const string_type& str);
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
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.
sb_type
The type sb_type is an instantiation of class basic_stringbuf on
type charT.
string_type
The type string_type is an instantiation of class basic_string on
type charT.
stringstream
The type stringstream is an instantiation of class
basic_stringstream on type char:
typedef basic_stringstream<char> stringstream;
traits_type
The type traits_type is a synonym for the template parameter
traits.
wstringstream
The type wstringstream is an instantiation of class
basic_stringstream on type wchar_t:
typedef basic_stringstream<wchar_t> wstringstream;
CONSTRUCTORS
explicit basic_stringstream(ios_base::openmode which =
ios_base::in | ios_base::out);
Constructs an object of class basic_stringstream, ini-
tializing the base class basic_iostream with the asso-
ciated string buffer. The string buffer is initialized
by calling the basic_stringbuf constructor
basic_stringbuf<charT,traits,Allocator>(which).
explicit basic_stringstream(const string_type& str,
ios_base::openmode which =
ios_base::in | ios_base::out);
Constructs an object of class basic_stringstream, ini-
tializing the base class basic_iostream with the asso-
ciated string buffer. The string buffer is initialized
by calling the basic_stringbuf constructor
basic_stringbuf<charT,traits,Allocator>(str,which).
DESTRUCTOR
virtual ~basic_stringstream();
Destroys an object of class basic_stringstream.
MEMBER FUNCTIONS
basic_stringbuf<charT,traits,Allocator>*
rdbuf() const;
Returns a pointer to the basic_stringbuf associated with the
stream.
string_type
str() const;
Returns a string object of type string_type whose contents is a
copy of the underlying buffer contents.
void
str(const string_type& str);
Clears the string buffer and copies the string object str into
it. If the opening mode is in, initializes the input
sequence to point at the first character of the buffer. If
the opening mode is out, initializes the output sequence to
point at the first character of the buffer. If the opening mode
is out | app, initializes the output sequence to point at the
last character of the buffer.
EXAMPLES
//
// stdlib/examples/manual/stringstream.cpp
//
#include<iostream>
#include<sstream>
void main ( )
{
using namespace std;
// create a bi-directional wstringstream object
wstringstream inout;
// output characters
inout << L"Das ist die rede von einem man" << endl;
inout << L"C'est l'histoire d'un home" << endl;
inout << L"This is the story of a man" << endl;
wchar_t p[100];
// extract the first line
inout.getline(p,100);
// output the first line to stdout
wcout << endl << L"Deutch :" << endl;
wcout << p;
// extract the seconf line
inout.getline(p,100);
// output the second line to stdout
wcout << endl << L"Francais :" << endl;
wcout << p;
// extract the third line
inout.getline(p,100);
// output the third line to stdout
wcout << endl << L"English :" << endl;
wcout << p;
// output the all content of the
//wstringstream object to stdout
wcout << endl << endl << inout.str();
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_stringbuf, basic_string,
basic_istringstream, basic_ostringstream(3c++)
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.7.3
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
cerr
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
cerr
SYNOPSIS
#include <iostream>
extern ostream cerr;
DESCRIPTION
ostream cerr;
The object cerr controls output to an unbuffered stream buffer
associated with the object stderr declared in
<cstdio>. By default, the standard C and C++ streams are
synchronized, but you may improve performance by using the
ios_base member function synch_with_stdio to desynchronize them.
FORMATTING
The formatting is done through member functions or manipulators. See
cout or basic_ostream for details.
EXAMPLES
//
// cerr example
//
#include<iostream>
#include<fstream>
void main ( )
{
using namespace std;
// open the file "file_name.txt"
// for reading
ifstream in("file_name.txt");
// output the all file to stdout
if ( in )
cout << in.rdbuf();
else
// if the ifstream object is in a bad state
// output an error message to stderr
cerr << "Error while opening the file" << endl;
}
SEE ALSO
basic_ostream, iostream, basic_filebuf,
cout, cin, clog, wcin, wcout,
wcerr, wclog, iomanip, ios_base,
basic_ios
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.3.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
char_traits
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
char_traits_ - A traits class providing types and operations to the
basic_string container and iostream classes.
SYNOPSIS
#include <string>
template <class charT> struct char_traits
struct char_traits<char>; .
struct char_traits<wchar_t>;
DESCRIPTION
The char_traits struct provides elementary operations to
instantiations of basic_string and iostream classes. As with all
traits classes, char_traits is used to specialize the behavior
of a template. In this case, the traits class provides
functions based on character type to the basic_string template
and to the templates that are part of the iostreams library.
Specializations of char_traits are provided for char and wchar_t.
These are used to define, respectively, string and wstring, cout
and wcout, etc.
INTERFACE
template <class charT> struct char_traits .
{
typedef charT char_type;
typedef int int_type;
typedef streampos pos_type;
typedef streamoff off_type;
typedef mbstate_t state_type;
static void assign (char_type&, const char_type&);
static char_type* assign (char_type*, size_t, const char_type&);
static bool eq (const char_type&, const char_type&);
static bool lt (const char_type&, const char_type&);
static int compare (const char_type*, const char_type*, size_t);
static size_t length (const char_type * s);
static const char_type*
find (const char_type*, int, const char_type&);
static char_type* move (char_type*, const char_type*, size_t);
static char_type* copy (char_type*, const char_type*, size_t);
static int_type not_eof(const int_type& c);
static char_type to_char_type(const int_type& c);
static int_type to_int_type(const char_type& c);
static bool eq_int_type(const int_type& c1, const int_type& c2);
static int_type eof();
};
TYPE
char_type
The basic character type. Same as the template parameter.
int_type
A type that can represent all the character values
of char_type as well as and end of file value.
pos_type
A type used to represent a position within a stream buffer.
off_type
A type used to represent an offset to a position within a stream
buffer.
state_type
A type used to represent the state class or type that is applied
to the codecvt facet. This type is only relevant for streams
with a underlying character type that is multi-byte.
OPERATIONS
static
void assign(char_type& c1, const char_type& c2)
Assigns one character value to another. The value of c2 is
assigned to c1.
static
char_type* assign(char_type* s, size_t n, const char_type& a)
Assigns one character value to n elements of a character array.
The value of a is assigned to n elements of s.
static
bool eq(const char_type& c1, const char_type& c2)
Returns true if c1 equals c2.
static
bool lt(const char_type& c1, const char_type& c2)
Returns true if c1 is less than c2.
static
int compare(const char_type* s1, const char_type* s2,
size_t n)
Compares n values from s1 with n values from s2. Return 1 if
s1 is greater than s2, -1 if s1 is less than s2, or 0 if they
are equal.
static
size_t length(const char_type * s)
Returns the length of the null terminated character array s. The
eos terminator is not counted.
static
const char_type* find(const char_type* s, int n,
const char_type& a)
Looks for the value of a in s. Only n elements of s are
examined. Returns a pointer to the matched element if one is
found. Otherwise returns s + n.
static
char_type* move(char_type* s1, const char_type* s2, size_t n)
Moves n values from s1 to s2. The ranges of (s1,s1+n) and
(s2,s2+n) may overlap.
static
char_type* copy(char_type* s1, const char_type* s2, size_t n)
Copy n values from s1 to s2. The ranges of (s1,s1+n) and
(s2,s2+n) may not overlap.
static
int_type not_eof(const int_type& c)
Returns c if c is not equal to eof(), otherwise returns 0.
static
int_type to_char_type(const int_type& c)
Returns the char_type representation of c. This value may not be
useful if no such representation exists.
static
int_type to_int_type(const char_type& c)
Returns the int_type representation of c.
static
bool eq_int_type(const int_type& c1, const int_type& c2)
Returns true if c1 equals c2.
static
int_type eof()
Returns EOF.
SEE ALSO
basic_string, traits, basic_ostream, basic_istream, cout, cin,
wcout, wcin
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
cin
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
cin
SYNOPSIS
#include <iostream>
extern istream cin;
DESCRIPTION
istream cin;
The object cin controls input from a stream buffer associated
with the object stdin declared in <cstdio>. By default,
the standard C and C++ streams are syn chronized, but you
can improve performance by using the ios_base member function
synch_with_stdio to desynchronize them.
After the object cin is initialized, cin.tie() returns &cout,
which implies that cin and cout are synchronized.
EXAMPLES
//
// cin example one
//
#include <iostream>
void main ( )
{
using namespace std;
int i;
float f;
char c;
//read an integer, a float and a character from stdin
cin >> i >> f >> c;
// output i, f and c to stdout
cout << i << endl << f << endl << c << endl;
}
//
// cin example two
//
#include <iostream>
void main ( )
{
using namespace std;
char p[50];
// remove all the white spaces
cin >> ws;
// read characters from stdin until a newline
// or 49 characters have been read
cin.getline(p,50);
// output the result to stdout
cout << p;
}
When inputting " Grendel the monster" (newline) in the previous
test, the output will be "Grendel the monster". The manipulator
ws removes spaces.
SEE ALSO
basic_istream, iostream, basic_filebuf,
cout, cerr, clog, wcin, wcout,
wcerr, wclog, ios_base, basic_ios
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.3.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
cout
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
cout
SYNOPSIS
#include <iostream>
extern ostream cout;
DESCRIPTION
ostream cout;
The object cout controls output to a stream buffer associated
with the object stdout declared in <cstdio>. By default the
standard C and C++ streams are synchronized, but performance
improvement can be achieved by using the ios_base member
function synch_with_stdio to desynchronize them.
After the object cin is initialized, cin.tie() returns &cout,
which implies that cin and cout are synchronized.
FORMATTING
The formatting is done through member functions or manipulators.
Manipulators Member functions
showpos setf(ios_base::showpos)
noshowpos unsetf(ios_base::showpos)
showbase setf(ios_base::showbase)
noshowbase unsetf(ios_base::showbase)
uppercase setf(ios_base::uppercase)
nouppercase unsetf(ios_base::uppercase)
showpoint setf(ios_base::showpoint)
noshowpoint unsetf(ios_base::showpoint)
boolalpha setf(ios_base::boolalpha)
noboolalpha unsetf(ios_base::boolalpha)
unitbuf setf(ios_base::unitbuf)
nounitbuf unsetf(ios_base::unitbuf)
internal setf(ios_base::internal,
ios_base::adjustfield)
left setf(ios_base::left,
ios_base::adjustfield)
right setf(ios_base::right,
ios_base::adjustfield)
dec setf(ios_base::dec,
ios_base::basefield)
hex setf(ios_base::hex,
ios_base::basefield)
oct setf(ios_base::oct,
ios_base::basefield)
fixed setf(ios_base::fixed,
ios_base::floatfield)
scientific setf(ios_base::scientific,
ios_base::floatfield)
resetiosflags
(ios_base::fmtflags flag) setf(0,flag)
setiosflags
(ios_base::fmtflags flag) setf(flag)
setbase(int base) See above
setfill(char_type c) fill(c)
setprecision(int n) precision(n)
setw(int n) width(n)
endl
ends
flush flush( )
DESCRIPTION
showpos Generates a + sign in non-negative generated numeric output.
showbase Generates a prefix indicating the numeric base of generated
integer output.
uppercase Replaces certain lowercase letters with their uppercase
equivalents in generated output.
showpoint Generates a decimal-point character unconditionally in
generated floating-point output.
boolalpha Insert and extract bool type in alphabetic format.
unitbuf Flushes output after each output operation.
internal Adds fill characters at a designated internal point in
certain generated output, or identical to right if no
such point is designated.
left Adds fill characters on the right (final positions) of certain
generated output.
right Adds fill characters on the left (initial positions) of
certain generated output.
dec Converts integer input or generates integer output in decimal
base.
hex Converts integer input or generates integer output in hexadecimal
base.
oct Converts integer input or generates integer output in octal base.
fixed Generates floating-point output in fixed-point notation.
scientific Generates floating-point output in scientific notation.
resetiosflagss
(ios_base::fmtflags flag) Resets the fmtflags field flag.
setiosflags
(ios_base::fmtflags flag) Sets up the flag flag.
setbase(int base) Converts integer input or generates integer
output in base base. The parameter base can
be 8, 10 or 16.
setfill(char_type c) Sets the character used to pad (fill) an output
conversion to the specified field width.
setprecision(int n) Set the precision (number of digits after the
decimal point) to generate on certain output
conversions.
setw(int n) Sets the field with (number of characters) to generate on
certain output conversions
endl Inserts a newline character into the output sequence and flush
the output buffer.
ends Inserts a null character into the output sequence.
flush Flush the output buffer.
DEFAULT VALUES
precision() 6
width() 0
fill() the space character
flags() skipws | dec
getloc() locale::locale()
EXAMPLES
//
// cout example one
//
#include<iostream>
#include<iomanip>
void main ( )
{
using namespace std;
int i;
float f;
// read an integer and a float from stdin
cin >> i >> f;
// output the integer and goes at the line
cout << i << endl;
// output the float and goes at the line
cout << f << endl;
// output i in hexa
cout << hex << i << endl;
// output i in octal and then in decimal
cout << oct << i << dec << i << endl;
// output i preceded by its sign
cout << showpos << i << endl;
// output i in hexa
cout << setbase(16) << i << endl;
// output i in dec and pad to the left with character
// @ until a width of 20
// if you input 45 it outputs 45@@@@@@@@@@@@@@@@@@
cout << setfill('@') << setw(20) << left << dec << i;
cout << endl;
// output the same result as the code just above
// but uses member functions rather than manipulators
cout.fill('@');
cout.width(20);
cout.setf(ios_base::left, ios_base::adjustfield);
cout.setf(ios_base::dec, ios_base::basefield);
cout << i << endl;
// outputs f in scientific notation with
// a precision of 10 digits
cout << scientific << setprecision(10) << f << endl;
// change the precision to 6 digits
// equivalents to cout << setprecision(6);
cout.precision(6);
// output f and goes back to fixed notation
cout << f << fixed << endl;
}
//
// cout example two
//
#include <iostream>
void main ( )
{
using namespace std;
char p[50];
cin.getline(p,50);
cout << p;
}
//
// cout example three
//
#include <iostream>
#include <fstream>
void main ( )
{
using namespace std;
// open the file "file_name.txt"
// for reading
ifstream in("file_name.txt");
// output the all file to stdout
if ( in )
cout << in.rdbuf();
else
{
cout << "Error while opening the file";
cout << endl;
}
}
WARNINGS
Keep in mind that the manipulator endl flushes the stream buffer.
Therefore it is recommended to use '0 if your only intent is
to go at the line. It will greatly improve performance when
C and C++ streams are not synchronized.
SEE ALSO
basic_ostream, iostream, basic_filebuf,
cin, cerr, clog, wcin, wcout,
wcerr, wclog, iomanip
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.3.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
ctype
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
ctype, ctype<char> - A facet that provides character classification
facilities. (The description for ctype<char>, a specialization of
ctype, follows the ctype description.)
SYNOPSIS
#include <locale>
class ctype_base;
template <class charT> class ctype;
SPECIALIZATION
class ctype<char>;
DESCRIPTION
ctype<charT> is the character classification facet. This facet
provides facilities for classifying characters and performing
simple conversions. ctype<charT> provides conversions for upper
to lower and lower to upper case. The facet also
provides conversions between charT, and char. ctype<charT>
relies on ctype_base for a set of masks that identify the
various classes of characters. These classes are:
space
print
cntrl
upper
lower
alpha
digit
punct
xdigit
alnum
graph
The masks are passed to member functions of ctype in order to obtain
verify the classifications of a character or range of characters.
INTERFACE
class ctype_base {
public:
enum mask {
space, print, cntrl, upper, lower,
alpha, digit, punct, xdigit,
alnum=alpha|digit, graph=alnum|punct
};
};
template <class charT>
class ctype : public locale::facet, public ctype_base {
public:
typedef charT char_type;
explicit ctype(size_t);
bool is(mask, charT) const;
const charT* is(const charT*,
const charT*, mask*) const;
const charT* scan_is(mask,
const charT*,
const charT*) const;
const charT* scan_not(mask,
const charT*,
const charT*) const;
charT toupper(charT) const;
const charT* toupper(charT*, const charT*) const;
charT tolower(charT) const;
const charT* tolower(charT*, const charT*) const;
charT widen(char) const;
const char* widen(const char*,
const char*, charT*) const;
char narrow(charT, char) const;
const charT* narrow(const charT*, const charT*,
char, char*) const;
static locale::id id;
protected:
~ctype(); // virtual
virtual bool do_is(mask, charT) const;
virtual const charT* do_is(const charT*,
const charT*,
mask*) const;
virtual const charT* do_scan_is(mask,
const charT*,
const charT*) const;
virtual const charT* do_scan_not(mask,
const charT*,
const charT*) const;
virtual charT do_toupper(charT) const;
virtual const charT* do_toupper(charT*,
const charT*) const;
virtual charT do_tolower(charT) const;
virtual const charT* do_tolower(charT*,
const charT*) const;
virtual charT do_widen(char) const;
virtual const char* do_widen(const char*,
const char*,
charT*) const;
virtual char do_narrow(charT, char) const;
virtual const charT* do_narrow(const charT*,
const charT*,
char, char*) const;
};
TYPE
char_type
Type of character the facet is instantiated on.
CONSTRUCTOR AND DESTRUCTOR
explicit ctype(size_t refs = 0)
Construct a ctype facet. If the refs argument is 0 then
destruction of the object is delegated to the locale, or
locales, containing it. This allows the user to ignore
lifetime management issues. On the other had, if refs
is 1 then the object must be explicitly deleted; the locale will
not do so. In this case, the object can be maintained
across the lifetime of multiple locales.
~ctype(); // virtual and protected
Destroy the facet.
PUBLIC MEMBER FUNCTIONS
The public members of the ctype facet provide an interface to
protected members. Each public member xxx has a corresponding
virtual protected member do_xxx. All work is delagated to
these protected members. For instance, the public widen function
simply calls its protected cousin do_widen.
bool
is(mask m, charT c) const;
const charT*
is(const charT* low,
const charT* high, mask* vec) const;
Returns do_is(m,c) or do_is(low,high,vec).
char
narrow(charT c, char dfault) const;
const charT*
narrow(const charT* low, const charT*, char dfault,
char* to) const;
Returns do_narrow(c,dfault) or do_narrow(low,high,dfault,to).
const charT*
scan_is(mask m, const charT*, const charT* high) const;
Returns do_scan_is(m,low,high).
const charT*
scan_not(mask m, const charT* low, const charT* high) const;
Returns do_scan_not(m,low,high).
charT
tolower(charT c) const;
const charT*
tolower(charT* low, const charT* high) const;
Returns do_tolower(c) or do_tolower(low,high).
charT
toupper(charT) const;
const charT*
toupper(charT* low, const charT* high) const;
Returns do_toupper(c) or do_toupper(low,high).
charT
widen(char c) const;
const char*
widen(const char* low, const char* high, charT* to) const;
Returns do_widen(c) or do_widen(low,high,to).
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PROTECTED MEMBER FUNCTIONS
virtual bool
do_is(mask m, charT c) const;
Returns true if c matches the classification indicated by the
mask m, where m is one of the values available from
ctype_base. For instance, the following call returns true
since 'a' is an alphabetic character:
ctype<char>().is(ctype_base::alpha,'a');
See ctype_base for a description of the masks.
virtual const charT*
do_is(const charT* low, const charT* high,
mask* vec) const;
Fills vec with every mask from ctype_base that applies to the
range of characters indicated by [low,high). See
ctype_base for a description of the masks. For instance,
after the following call v would contain {alpha, lower,
print,alnum ,graph}:
char a[] = "abcde";
ctype_base::mask v[12];
ctype<char>().is(a,a+5,v);
This function returns high.
virtual char
do_narrow(charT, char dfault) const;
Returns the appropriate char representation for c, if such
exists. Otherwise do_narrow returns dfault.
virtual const charT*
do_narrow(const charT* low, const charT* high,
char dfault, char* dest) const;
Converts each character in the range [low,high) to its char
representation, if such exists. If a char representation is
not available then the character will be converted to
dfault. Returns high.
virtual const charT*
do_scan_is(mask m, const charT* low, const charT* high) const;
Finds the first character in the range [low,high) that matches
the classification indicated by the mask m.
virtual const charT*
do_scan_not(mask m, const charT* low, const charT* high) const;
Finds the first character in the range [low,high) that does not
match the classification indicated by the mask m.
virtual charT
do_tolower(charT) const;
Returns the lower case representation of c, if such exists,
otherwise returns c;
virtual const charT*
do_tolower(charT* low, const charT* high) const;
Converts each character in the range [low,high) to its lower case
representation, if such exists. If a lower case representation
does not exist then the character is not changed. Returns
high.
virtual charT
do_toupper(charT c) const;
Returns the upper case representation of c, if such exists,
otherwise returns c;
virtual const charT*
do_toupper(charT* low, const charT* high) const;
Converts each character in the range [low,high) to its upper case
representation, if such exists. If an upper case representation
does not exist then the character is not changed. Returns
high.
virtual charT
do_widen(char c) const;
Returns the appropriate charT representation for c.
virtual const char*
do_widen(const char* low, const char* high,charT* dest) const;
Converts each character in the range [low,high) to its charT
representation. Returns high.
EXAMPLE
//
// ctype.cpp
//
#include <iostream>
int main ()
{
using namespace std;
locale loc;
string s1("blues Power");
// Get a reference to the ctype<char> facet
const ctype<char>& ct =
#ifndef _RWSTD_NO_TEMPLATE_ON_RETURN_TYPE
use_facet<ctype<char> >(loc);
#else
use_facet(loc,(ctype<char>*)0);
#endif
// Check the classification of the 'a' character
cout << ct.is(ctype_base::alpha,'a') << endl;
cout << ct.is(ctype_base::punct,'a') << endl;
// Scan for the first upper case character
cout << (char)*(ct.scan_is(ctype_base::upper,
s1.begin(),s1.end())) << endl;
// Convert characters to upper case
ct.toupper(s1.begin(),s1.end());
cout << s1 << endl;
return 0;
}
SEE ALSO
locale, facets, collate, ctype<char>, ctype_byname
NAME
ctype<char> - A specialization of the ctype facet.
SYNOPSIS
#include <locale>
class ctype<char>;
DESCRIPTION
This specialization of the ctype<charT> template provides inline
versions of ctype's member functions. The facet provides the same
public interface, and uses the same set of masks, as the ctype
template.
INTERFACE
template <>
class ctype<char> : public locale::facet, public ctype_base {
public:
typedef char char_type;
explicit ctype(const mask* = 0, bool = false,
size_t = 0);
bool is(mask, char) const;
const charT* is(const char*,
const char*, mask*) const;
const charT* scan_is(mask,
const char*,
const char*) const;
const charT* scan_not(mask,
const char*,
const char*) const;
charT toupper(char) const;
const charT* toupper(char*, const charT*) const;
charT tolower(char) const;
const charT* tolower(char*, const char*) const;
charT widen(char) const;
const char* widen(const char*,
const char*, char*) const;
char narrow(char, char) const;
const charT* narrow(const char*, const char*,
char, char*) const;
static locale::id id;
static const size_t table_size = 256;
protected:
const mask* table() const throw();
static const mask* classic_table() throw();
~ctype(); // virtual
virtual charT do_toupper(charT) const;
virtual const charT* do_toupper(charT*,
const charT*) const;
virtual charT do_tolower(charT) const;
virtual const charT* do_tolower(charT*,
const charT*) const;
};
TYPE
char_type
Type of character the facet is instantiated on.
CONSTRUCTORS AND DESTRUCTORS
explicit ctype(const mask* tbl = 0, bool del = false,
size_t refs = 0)
Construct a ctype facet. The three parameters set up the
following conditions:
+ The tbl argument must be either 0 or an array of at least
table_size elements. If tbl is non zero then the supplied
table will be used for character classification.
+ If tbl is non zero, and del is true then the tbl array will
be deleted by the destructor, so the calling program need
not concern itself with the lifetime of the facet.
+ If the refs argument is 0 then destruction of the object
itself is delegated to the locale, or locales, containing it.
This allows the user to ignore lifetime management issues. On
the other had, if refs is 1 then the object must be explicitly
deleted; the locale will not do so. In this case, the object
can be maintained across the lifetime of multiple locales.
~ctype(); // virtual and protected
Destroy the facet. If the constructor was called with a non-zero
tbl argumentand a true del argument, then the array supplied
by the tbl argument will be deleted
PUBLIC MEMBER FUNCTIONS
The public members of the ctype<char> facet specialization do not
all serve the same purpose as the functions in the template. In
many cases these functions implement functionality, rather than just
forwarding a call to a protected implementation function.
static const mask*
classic_table() throw();
Returns a pointer to a table_size character array that represents
the classifications of characters in the "C" locale.
bool
is(mask m, charT c) const;
Determines if the character c has the classification indicated by
the mask m. Returns table()[(unsigned char)c] & m.
const charT*
is(const charT* low,
const charT* high, mask* vec) const;
Fills vec with every mask from ctype_base that applies to the
range of characters indicated by [low,high). See
ctype_base for a description of the masks. For instance,
after the following call v would contain {alpha, lower,
print,,alnum ,graph}:
char a[] = "abcde";
ctype_base::mask v[12];
ctype<char>().do_is(a,a+5,v);
This function returns high.
char
narrow(charT c, char dfault) const;
Returns c.
const charT*
narrow(const charT* low, const charT*, char dfault,
char* to) const;
Performs ::memcpy(to,low,high-low). Returns high.
const charT*
scan_is(mask m, const charT*, const charT* high) const;
Finds the first character in the range [low,high) that matches
the classification indicated by the mask m. The
classification is matched by checking for table()[(unsigned char)
p] & m, where p is in the range [low,high). Returns the
first p that matches, or high if none do.
const charT*
scan_not(mask m, const charT* low, const charT* high) const;
Finds the first character in the range [low,high) that does not
match the classification indicated by the mask m. The
classification is matched by checking for
!(table()[(unsigned char) p] & m), where p is in the range
[low,high). Returns the first p that matches, or high if none
do.
const mask*
table() const throw();
If the tbl argument that was passed to the constructor was
non-zero, then this function returns that argument,
otherwise it returns classic_table().
charT
tolower(charT c) const;
const charT*
tolower(charT* low, const charT* high) const;
Returns do_tolower(c) or do_tolower(low,high).
charT
toupper(charT) const;
const charT*
toupper(charT* low, const charT* high) const;
Returns do_toupper(c) or do_toupper(low,high).
charT
widen(char c) const;
Returns c.
const char*
widen(const char* low, const char* high, charT* to) const;
Performs ::memcpy(to,low,high-low. Returns high.
FACET ID
static locale::id id;
Unique identifier for this type of facet.
PROTECTED MEMBER FUNCTIONS
virtual charT
do_tolower(charT) const;
Returns the lower case representation of c, if such exists,
otherwise returns c;
virtual const charT*
do_tolower(charT* low, const charT* high) const;
Converts each character in the range [low,high) to its lower case
representation, if such exists. If a lower case representation
does not exist then the character is not changed. Returns
high.
virtual charT
do_toupper(charT c) const;
Returns the upper case representation of c, if such exists,
otherwise returns c;
virtual const charT*
do_toupper(charT* low, const charT* high) const;
Converts each character in the range [low,high) to its upper case
representation, if such exists. If an upper case representation
does not exist then the character is not changed. Returns
high.
SEE ALSO
locale, facets, collate, ctype<char>, ctype_byname
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
filebuf
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_filebuf,filebuf
This page describes the ANSI basic_filebuf class. If you would like
information on the pre-ANSI filebuf class, use the command:
help cxxl
SYNOPSIS
#include <fstream>
template<class charT, class traits = char_traits<charT> >
class basic_filebuf
: public basic_streambuf<charT, traits>
DESCRIPTION
The template class basic_filebuf is derived from basic_streambuf.
It associates the input or output sequence with a file. Each
object of type basic_filebuf<charT, traits> controls two character
sequences:
+ a character input sequence
+ a character output sequence
The restrictions on reading and writing a sequence controlled by an
object of class basic_filebuf<charT,traits> are the same as for
reading and writing with the Standard C library files.
If the file is not open for reading the input sequence cannot be
read. If the file is not open for writing the output sequence cannot
be written. A joint file position is maintained for both the input
and output sequences.
A file provides byte sequences. So the basic_filebuf class treats a
file as the external source (or sink) byte sequence. In order to
provide the contents of a file as wide character sequences, a
wide-oriented file buffer called wfilebuf converts wide
character sequences to multibytes character sequences (and vice
versa) according to the current locale being used in the stream
buffer.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_filebuf
: public basic_streambuf<charT, traits> {
public:
typedef traits traits_type;
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;
basic_filebuf();
basic_filebuf(int fd);
virtual ~basic_filebuf();
bool is_open() const;
basic_filebuf<charT, traits>* open(const char *s,
ios_base::openmode,
long protection = 0666);
basic_filebuf<charT, traits>* open(int fd);
basic_filebuf<charT, traits>* close();
protected:
virtual int showmanyc();
virtual int_type overflow(int_type c = traits::eof());
virtual int_type pbackfail(int_type c = traits::eof());
virtual int_type underflow();
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 int sync();
virtual streamsize xsputn(const char_type* s, streamsize n);
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
filebuf
The type filebuf is an instantiation of class basic_filebuf on type
char:
typedef basic_filebuf<char> filebuf;
int_type
The type int_type is a synonym of type traits::in_type.
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.
traits_type
The type traits_type is a synonym for the template parameter traits.
wfilebuf
The type wfilebuf is an instantiation of class basic_filebuf on type
wchar_t:
typedef basic_filebuf<wchar_t> wfilebuf;
CONSTRUCTORS
basic_filebuf();
Constructs an object of class basic_filebuf<charT,traits>,
initializing the base class with basic_streambuf<charT,traits>().
basic_filebuf(int fd);
Constructs an object of class basic_filebuf<charT,traits>,
initializing the base class with basic_streambuf<charT,traits>(),
then calls open(fd). This function is not described in the
C++ standard, and is provided as an extension in order to
manipulate pipes, sockets or other UNIX devices, that can be
accessed through file descriptors.
DESTRUCTOR
virtual ~basic_filebuf();
Calls close() and destroys the object.
MEMBER FUNCTIONS
basic_filebuf<charT,traits>*
close();
If is_open() == false, returns a null pointer. Otherwise, closes the
file, and returns *this.
bool
is_open() const;
Returns true if the associated file is open.
basic_filebuf<charT,traits>*
open(const char* s, ios_base::openmode mode, long protection = 0666);
If is_open() == true, returns a null pointer. Otherwise opens
the file, whose name is stored in the
null-terminated byte-string s. The file open modes are
given by their C-equivalent description (see the C func-
tion fopen):
in "w"
in|binary "rb"
out "w"
out|app "a"
out|binary "wb"
out|binary|app "ab"
out|in "r+"
out|in|app "a+"
out|in|binary "r+b"
out|in|binary|app "a+b"
trunc|out "w"
trunc|out|binary "wb"
trunc|out|in "w+"
trunc|out|in|binary "w+b"
The third argument, protection, is used as the file permission.
It does not appear in the Standard C++ description of the
function open and is provided as an extension. It determines
the file read/write/execute permissions under UNIX. It is more
limited under DOS since files are always readable and do not
have special execute permission. If the open function fails,
it returns a null pointer.
basic_filebuf<charT,traits>*
open(int fd);
Attaches the file previously opened and identified by its file
descriptor fd, to the basic_filebuf object. This
function is not described in the C++ standard, and is provided
as an extension in order to manipulate pipes, sockets or other
UNIX devices, that can be accessed through file descriptors.
int_type
overflow(int_type c = traits::eof() );
If the output sequence has a put position available, and c is not
traits::eof(), then write c into it. If there is no position
available, the function output the content of the buffer to
the associated file and then write c at the new current put
position. If the operation fails, the function returns
traits::eof(). Otherwise it returns traits::not_eof(c). In wide
characters file buffer, overflow converts the internal wide
characters to their external multibytes representation by using
the locale::codecvt facet located in the locale object imbued in
the stream buffer.
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, move
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, alters the stream position of both
the input and the output sequence. If the open mode is in,
alters the stream position of only the input sequence, and
if it is out, alters the stream position of only the output
sequence. The new position is calculated by combining the two
parameters 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. File buffers using locale::codecvt facet
performing state dependent conversion, only support
seeking to the beginning of the file, to the current
position, or to a position previously obtained by a call
to one of the iostreams seeking functions.
pos_type
seekpos(pos_type sp,ios_base::openmode which = ios_base::in |
ios_base::out);
If the open mode is in | out, alters the stream position of both
the input and the output sequence. If the open mode is in,
alters the stream position of only the input sequence, and
if it is out, alters the stream position of only the output
sequence. 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. File buffers using locale::codecvt
facet performing state dependent conversion, only support
seeking to the beginning of the file, to the current position,
or to a position previously obtained by a call to one of the
iostreams seeking functions.
basic_filebuf<charT,traits>*
setbuf(char_type*s, streamsize n);
If s is not a null pointer, output the content of the current
buffer to the associated file, then delete the current buffer and
replace it by s. Otherwise resize the current buffer to size n
after outputting its content to the associated file if
necessary.
int
sync();
Synchronizes the content of the external file, with its image
maintained in memory by the file buffer. If the function
fails, it returns -1, otherwise it returns 0.
int_type
underflow();
If the input sequence has a read position available, returns the
content of this position. Otherwise fills up the buffer by
reading characters from the associated file and if it
succeeds, returns the content of the new current position. The
function returns traits::eof() to indicate failure. In wide
characters file buffer, underflow converts the external
mutltibytes characters to their wide character representation by
using the locale::codecvt facet located in the locale object
imbued in the stream buffer.
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.
EXAMPLES
//
// stdlib/examples/manual/filebuf.cpp
//
#include<iostream>
#include<fstream>
void main ( )
{
using namespace std;
// create a read/write file-stream object on tiny char
// and attach it to the file "filebuf.out"
ofstream out("filebuf.out",ios_base::in | ios_base::out);
// tie the istream object to the ofstream object
istream in(out.rdbuf());
// output to out
out << "Il errait comme un ame en peine";
// seek to the beginning of the file
in.seekg(0);
// output in to the standard output
cout << in.rdbuf() << endl;
// close the file "filebuf.out"
out.close();
// open the existing file "filebuf.out"
// and truncate it
out.open("filebuf.out",ios_base::in | ios_base::out |
ios_base::trunc);
// set the buffer size
out.rdbuf()->pubsetbuf(0,4096);
// open the source code file
ifstream ins("filebuf.cpp");
//output it to filebuf.out
out << ins.rdbuf();
// seek to the beginning of the file
out.seekp(0);
// output the all file to the standard output
cout << out.rdbuf();
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_streambuf, basic_ifstream, basic_ofstream,
basic_fstream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.8.1.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
fpos
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
fpos
SYNOPSIS
#include <rw/iotraits>
template<class stateT = mbstate_t>
class fpos
DESCRIPTION
The template class fpos<stateT> is used by the iostream classes to
maintain positioning information. It maintains three kinds of
information: the absolute position, the conversion state and the
validity of the stored position. Streams instantiated on tiny
characters use streampos as their positioning type, whereas
streams instantiated on wide characters use wstreampos, but both are
defined as fpos<mbstate_t>.
INTERFACE
template <class stateT = mbstate_t>
class fpos {
public:
typedef stateT state_type;
fpos(long off = 0);
fpos(state_type);
state_type state(state_type);
state_type state () const;
};
TYPES
state_type
The type state_type holds the conversion state, and is compatible
with the function locale::codecvt(). By default it is defined
as mbstate_t.
PUBLIC CONSTRUCTORS
fpos(long off =0);
Constructs an fpos object, initializing its position with off and
its conversion state with the default stateT constructor.
This function is not described in the C++ standard.
fpos(state_type st);
Construct an fpos object, initializing its conversion state with
st, its position with the start position, and its status to good.
PUBLIC MEMBER FUNCTIONS
state_type
state() const;
Returns the conversion state stored in the fpos object.
state_type
state(state_type st);
Store st as the new conversion state in the fpos object and
return its previous value.
VALID OPERATIONS
In the following,
+ P refers to type fpos<stateT>
+ p and q refer to an value of type fpos<stateT>
+ O refers to the offset type ( streamoff, wstreamoff, long _)
+ o refers to a value of the offset type
+ i refers to a value of type int
Valid operations:
P p( i ); Constructs from int.
P p = i; Assigns from int.
P( o ) Converts from offset.
O( p ) Converts to offset.
p == q Tests for equality.
p != q Tests for inequality.
q = p + o Adds offset.
p += o Adds offset.
q = p -o Subtracts offset.
q -= o Subtracts offset.
o = p - q Returns offset.
SEE ALSO
iosfwd, char_traits
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.4.
Amendment 1 to the C Standard.
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
fstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_fstream,fstream,ofstream
This page describes the ANSI basic_fstream class. If you would like
information on the pre-ANSI fstream class, use the command:
help cxxl
SYNOPSIS
#include <fstream>
template<class charT, class traits = char_traits<charT> >
class basic_fstream
: public basic_iostream<charT, traits>
DESCRIPTION
The template class basic_fstream<charT,traits> supports reading and
writing to named files or other devices associated with a file
descriptor. It uses a basic_filebuf object to control the
associated sequences. It inherits from basic_iostream and can
therefore use all the formatted and unformatted input and
output functions.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_fstream
: public basic_iostream<charT, traits> {
public:
typedef basic_ios<charT, traits> ios_type;
typedef charT char_type;
typedef traits traits_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
basic_fstream();
explicit basic_fstream(const char *s, ios_base::openmode
mode = ios_base::in | ios_base::out,
long protection = 0666);
explicit basic_fstream(int fd);
basic_fstream(int fd, char_type *buf, int len);
virtual ~basic_fstream();
basic_filebuf<charT, traits> *rdbuf() const;
bool is_open();
void open(const char *s, ios_base::openmode mode =
ios_base::in | ios_base::out,
long protection = 0666);
void close();
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
fstream
The type fstream is an instantiation of class basic_fstream on type
char:
typedef basic_fstream<char> fstream;
int_type
The type int_type is a synonym of type traits::in_type.
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.
traits_type
The type traits_type is a synonym for the template parameter
traits.
wfstream
The type wfstream is an instantiation of class basic_fstream on
type wchar_t:
typedef basic_fstream<wchar_t> wfstream;
CONSTRUCTORS
basic_fstream();
Constructs an object of class basic_fstream<charT,traits>,
initializing the base class basic_iostream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). After construction,
a file can be attached to the basic_ftream object by using the
open() member function.
basic_fstream(const char* s,
ios_base::openmode mode=
ios_base::in | iosw_base::out,
long protection= 0666);
Constructs an object of class basic_fstream<charT,traits>,
initializing the base class basic_iostream with the associ-
ated file buffer, which is initialized by calling the
basic_filebuf constructor basic_filebuf<charT,traits>().
The constructor then calls the open function
open(s,mode,protection) in order to attach the file, whose
name is pointed at by s, to the basic_ftream object. The
third argument, protection, is used as the file permission.
It does not appear in the Standard C++ description and is
provided as an extension. It determines the file
read/write/execute permissions under UNIX. It is more lim-
ited under DOS since files are always readable and do not
have special execute permission.
explicit basic_fstream(int fd);
Constructs an object of class basic_fstream<charT,traits>,
initializing the base class basic_iostream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). The constructor
then calls the basic_filebuf open function open(fd) in order to
attach the file descriptor fd to the basic_ftream object. This
constructor is not described in the C++ standard, and
is provided as an extension in order to manipulate pipes,
sockets or other UNIX devices, that can be accessed through
file descriptors. If the function fails, it sets
ios_base::failbit.
basic_fstream(int fd, char_type* buf,int len);
Constructs an object of class basic_fstream<charT,traits>,
initializing the base class basic_iostream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). The constructor
then calls the basic_filebuf open function open(fd) in order to
attach the file descriptor fd to the basic_ftream object. The
underlying buffer is then replaced by calling the
basic_filebuf member function, setbuf(), with parameters buf
and len. This constructor is not described in the C++
standard, and is provided as an extension in order to manipulate
pipes, sockets, or other UNIX devices that can be accessed
through file descriptors. It also maintains compatibility with
the old iostreams library. If the function fails, it sets
ios_base::failbit.
DESTRUCTOR
virtual ~basic_fstream();
Destroys an object of class basic_fstream.
MEMBER FUNCTIONS
void
close();
Calls the associated basic_filebuf function close() and if this
function fails, it calls the basic_ios member function
setstate(failbit).
bool
is_open();
Calls the associated basic_filebuf function is_open() and return
its result.
void
open(const char* s,ios_base::openmode =
ios_base::out | ios_base::in,
long protection = 0666);
Calls the associated basic_filebuf function open(s,mode,protection)
and, if this function fails at opening the file, calls the basic_ios
member function setstate(failbit). The third argument protection is
used as the file permissions. It does not appear in the Standard C++
description and is provided as an extension. It determines the file
read/write/execute permissions under UNIX. It is more limited under
DOS since files are always readable and do not have special execute
permission.
basic_filebuf<charT,traits>*
rdbuf() const;
Returns a pointer to the basic_filebuf associated with the stream.
EXAMPLES
//
// stdlib/examples/manual/fstream.cpp
//
#include<iostream>
#include<bidirec>
void main ( )
{
using namespace std;
// create a bi-directional fstream object
fstream inout("fstream.out");
// output characters
inout << "Das ist die rede von einem man" << endl;
inout << "C'est l'histoire d'un home" << endl;
inout << "This is the story of a man" << endl;
char p[100];
// seek back to the beginning of the file
inout.seekg(0);
// extract the first line
inout.getline(p,100);
// output the first line to stdout
cout << endl << "Deutch :" << endl;
cout << p;
fstream::pos_type pos = inout.tellg();
// extract the seconf line
inout.getline(p,100);
// output the second line to stdout
cout << endl << "Francais :" << endl;
cout << p;
// extract the third line
inout.getline(p,100);
// output the third line to stdout
cout << endl << "English :" << endl;
cout << p;
// move the put sequence before the second line
inout.seekp(pos);
// replace the second line
inout << "This is the story of a man" << endl;
// replace the third line
inout << "C'est l'histoire d'un home";
// seek to the beginning of the file
inout.seekg(0);
// output the all content of the fstream object to stdout
cout << endl << endl << inout.rdbuf();
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_filebuf, basic_ifstream, basic_ofstream
Working Paper for Draft Proposed International Standard for Information
Systems--Programming Language C++, Section 27.8.1.11
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
ifstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_ifstream,fstream
This page describes the ANSI basic_ifstream class. If you would
like information on the pre-ANSI ifstream class, use the command:
help cxxl
SYNOPSIS
#include <fstream>
template<class charT, class traits = char_traits<charT> >
class basic_ifstream
: public basic_istream<charT, traits>
DESCRIPTION
The template class basic_ifstream<charT,traits> supports reading
from named files or other devices associated with a file
descriptor. It uses a basic_filebuf object to control the
associated sequences. It inherits from basic_istream and
can therefore use all the formatted and unformatted input
functions.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_ifstream
: public basic_istream<charT, traits> {
public:
typedef basic_ios<charT, traits> ios_type;
typedef traits traits_type;
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;
basic_ifstream();
explicit basic_ifstream(const char *s,
ios_base::openmode mode =
ios_base::in,
long protection = 0666);
explicit basic_ifstream(int fd);
basic_ifstream(int fd, char_type* buf, int len);
virtual ~basic_ifstream();
basic_filebuf<charT, traits> *rdbuf() const;
bool is_open();
void open(const char *s, ios_base::openmode mode =
ios_base::in, long protection = 0666);
void close();
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
ifstream
The type ifstream is an instantiation of class basic_ifstream on
type char:
typedef basic_ifstream<char> ifstream;
int_type
The type int_type is a synonym of type traits::in_type.
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.
traits_type
The type traits_type is a synonym for the template parameter
traits.
wifstream
The type wifstream is an instantiation of class basic_ifstream on
type wchar_t:
typedef basic_ifstream<wchar_t> wifstream;
CONSTRUCTORS
basic_ifstream();
Constructs an object of class basic_ifstream<charT,traits>,
initializing the base class basic_istream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). After construction,
a file can be attached to the basic_iftream object by using the
open member function.
basic_ifstream(const char* s,
ios_base::openmode mode= ios_base::in,
long protection= 0666);
Constructs an object of class
basic_ifstream<charT,traits>, initializing the base class
basic_istream with the associated file buffer, which is
initialized by calling the basic_filebuf constructor
basic_filebuf<charT,traits>(). The constructor then calls
the open function open(s,mode,protection) in order to
attach the file whose name is pointed at by s, to the
basic_iftream object. The third argument protection pro-
vides file permissions. It does not appear in the Standard
C++ description and is provided as an extension. It deter-
mines the file read/write/execute permissions under UNIX.
It is more limited under DOS since files are always read-
able and do not have special execute permission.
explicit basic_ifstream(int fd);
Constructs an object of class basic_ifstream<charT,traits>,
initializing the base class basic_istream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). The constructor
then calls the basic_filebuf open function open(fd) in order to
attach the file descriptor fd to the basic_iftream object. This
constructor is not described in the C++ standard, and is
provided as an extension in order to manipulate pipes,
sockets or other UNIX devices, that can be accessed through
file descriptors. If the function fails, it sets
ios_base::failbit.
basic_ifstream(int fd, char_type* buf,int len);
Constructs an object of class basic_ifstream<charT,traits>,
initializing the base class basic_istream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). The constructor
then calls the basic_filebuf open function open(fd) in order to
attach the file descriptor fd to the basic_iftream object. The
underlying buffer is then replaced by calling the basic_filebuf
member function setbuf with parameters buf and len. This
constructor is not described in the C++ standard, and is
provided as an extension in order to manipulate pipes, sockets or
other UNIX devices, that can be accessed through file
descriptors. It also maintains compatibility with the old
iostreams library. If the function fails, it sets
ios_base::failbit.
DESTRUCTOR
virtual ~basic_ifstream();
Destroys an object of class basic_ifstream.
MEMBER FUNCTIONS
void
close();
Calls the associated basic_filebuf function close() and if this
function fails, it calls the basic_ios member function
setstate(failbit).
bool
is_open();
Calls the associated basic_filebuf function is_open() and return
its result.
void
open(const char* s,ios_base::openmode =
ios_base::in, long protection = 0666);
Calls the associated basic_filebuf function
open(s,mode,protection). If this function fails opening the
file, it calls the basic_ios member function
setstate(failbit). The third argument protection provides
file permissions. It does not appear in the Standard C++
description and is provided as an extension. It determines
the file read/write/execute permissions under UNIX. It
is more limited under DOS since files are always readable and do
not have special execute permission.
basic_filebuf<charT,traits>*
rdbuf() const;
Returns a pointer to the basic_filebuf associated with the
stream.
EXAMPLES
//
// stdlib/examples/manual/ifstream.cpp
//
#include<iostream>
#include<fstream>
#include<iomanip>
void main ( )
{
using namespace std;
long l= 20;
char *ntbs="Le minot passait la piece a frotter";
char c;
char buf[50];
try {
// create a read/write file-stream object on char
// and attach it to an ifstream object
ifstream in("ifstream.out",ios_base::in |
ios_base::out | ios_base::trunc);
// tie the ostream object to the ifstream object
ostream out(in.rdbuf());
// output ntbs in out
out << ntbs << endl;
// seek to the beginning of the file
in.seekg(0);
// output each word on a separate line
while ( in.get(c) )
{
if ( char_traits<char>::eq(c,' ') )
cout << endl;
else
cout << c;
}
cout << endl << endl;
// move back to the beginning of the file
in.seekg(0);
// clear the state flags
in.clear();
// does the same thing as the previous code
// output each word on a separate line
while ( in >> buf )
cout << buf << endl;
cout << endl << endl;
// output the base info before each integer
out << showbase;
ostream::pos_type pos= out.tellp();
// output l in hex with a field with of 20
out << hex << setw(20) << l << endl;
// output l in oct with a field with of 20
out << oct << setw(20) << l << endl;
// output l in dec with a field with of 20
out << dec << setw(20) << l << endl;
// move back to the beginning of the file
in.seekg(0);
// output the all file
cout << in.rdbuf();
// clear the flags
in.clear();
// seek the input sequence to pos
in.seekg(pos);
int a,b,d;
// read the previous outputted integer
in >> a >> b >> d;
// output 3 times 20
cout << a << endl << b << endl << d << endl;
}
catch( ios_base::failure& var )
{
cout << var.what();
}
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_filebuf, basic_ofstream, basic_fstream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.8.1.5
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
ios
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_ios,ios
This page describes the ANSI ios class. If you would like
information on the pre-ANSI ios class, use the command:
help cxxl
SYNOPSIS
#include <ios>
template<class charT, class traits = char_traits<charT> >
class basic_ios : public ios_base
DESCRIPTION
The class basic_ios is a base class that provides the common
functionality required by all streams. It maintains state
information that reflects the integrity of the stream and stream
buffer. It also maintains the link between the stream classes and
the stream buffers classes via the rdbuf member functions.
Classes derived from basic_ios specialize operations for input, and
output.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_ios : public ios_base {
public:
typedef basic_ios<charT, traits> ios_type;
typedef basic_streambuf<charT, traits> streambuf_type;
typedef basic_ostream<charT, traits> ostream_type;
typedef typename traits::char_type char_type;
typedef traits traits_type;
typedef typename traits::int_type int_type;
typedef typename traits::off_type off_type;
typedef typename traits::pos_type pos_type;
explicit basic_ios(basic_streambuf<charT, traits> *sb_arg);
virtual ~basic_ios();
char_type fill() const;
char_type fill(char_type ch);
void exceptions(iostate except);
iostate exceptions() const;
void clear(iostate state = goodbit);
void setstate(iostate state);
iostate rdstate() const;
operator void*() const;
bool operator!() const;
bool good() const;
bool eof() const;
bool fail() const;
bool bad() const;
ios_type& copyfmt(const ios_type& rhs);
ostream_type *tie() const;
ostream_type *tie(ostream_type *tie_arg);
streambuf_type *rdbuf() const;
streambuf_type *rdbuf( streambuf_type *sb);
locale imbue(const locale& loc);
char narrow(charT, char) const;
charT widen(char) const;
protected:
basic_ios();
void init(basic_streambuf<charT, traits> *sb);
};
TYPES
char_type
The type char_type is a synonym of type traits::char_type.
ios
The type ios is an instantiation of basic_ios on char:
typedef basic_ios<char> ios;
int_type
The type int_type is a synonym of type traits::in_type.
ios_type
The type ios_type is a synonym for basic_ios<charT, traits>.
off_type
The type off_type is a synonym of type traits::off_type.
ostream_type
The type ostream_type is a synonym for basic_ostream<charT, traits>.
pos_type
The type pos_type is a synonym of type traits::pos_type.
streambuf_type
The type streambuf_type is a synonym for
basic_streambuf<charT, traits>.
traits_type
The type traits_type is a synonym for the template parameter
traits.
wios
The type wios is an instantiation of basic_ios on wchar_t:
typedef basic_ios<wchar_t> wios;
PUBLIC CONSTRUCTORS
explicit basic_ios(basic_streambuf<charT, traits>* sb);
Constructs an object of class basic_ios, assigning initial values
to its member objects by calling init(sb). If sb is a null
pointer, the stream is positioned in error state, by
triggering its badbit.
basic_ios();
Constructs an object of class basic_ios leaving its member
objects uninitialized. The object must be initialized
by calling the init member function before using it.
PUBLIC DESTRUCTOR
virtual ~basic_ios();
Destroys an object of class basic_ios.
PUBLIC MEMBER FUNCTIONS
bool
bad() const;
Returns true if badbit is set in rdstate().
void
clear(iostate state = goodbit);
If (state & exception()) == 0, returns. Otherwise, the function
throws an object of class ios_base::failure. After the call
returns state == rdstate().
basic_ios&
copyfmt(const basic_ios& rhs);
Assigns to the member objects of *this the corresponding member
objects of rhs, with the following exceptions:
+ rdstate() and rdbuf() are left unchanged
+ calls ios_base::copyfmt
+ exceptions() is altered last by calling
exceptions(rhs.exceptions())
bool
eof() const;
Returns true if eofbit is set in rdstate().
iostate
exceptions() const;
Returns a mask that determines what elements set in rdstate()
cause exceptions to be thrown.
void
exceptions(iostate except);
Set the exception mask to except then calls clear(rdstate()).
bool
fail() const;
Returns true if failbit or badbit is set in rdstate().
char_type
fill() const;
Returns the character used to pad (fill) an output conversion to
the specified field width.
char_type
fill(char_type fillch);
Saves the field width value then replaces it by fillch and
returns the previously saved value.
bool
good() const;
Returns rdstate() == 0.
locale
imbue(const locale& loc);
Saves the value returned by getloc() then assigns loc to a
private variable and if rdbuf() != 0 calls
rdbuf()->pubimbue(loc) and returns the previously saved value.
void
init(basic_streambuf<charT,traits>* sb);
Performs the following initialization:
rdbuf() sb
tie() 0
rdstate() goodbit if sb is not null otherwise badbit
exceptions() goodbit
flags() skipws | dec
width() 0
precision() 6
fill() the space character
getloc() locale::locale()
char
narrow(charT c, char dfault) const;
Uses the stream's locale to convert the wide character c to a
tiny character, and then returns it. If no
conversion exists, it returns the character dfault.
bool
operator!() const;
Returns fail() ? 1 : 0;
streambuf_type*
rdbuf() const;
Returns a pointer to the stream buffer associated with the
stream.
streambuf_type*
rdbuf(streambuf_type* sb);
Associates a stream buffer with the stream. All the input and
output will be directed to this stream buffer. If sb is a null
pointer, the stream is positioned in error state, by triggering
its badbit.
iostate
rdstate() const;
Returns the control state of the stream.
void
setstate(iostate state);
Calls clear(rdstate() | state).
ostream_type*
tie() const;
Returns an output sequence that is tied to (synchronized with)
the sequence controlled by the stream buffer.
ostream_type*
tie(ostream_type* tiestr);
Saves the tie() value then replaces it by tiestr and returns the
value previously saved.
operator
void*() const;
Returns fail() ? 0 : 1;
charT
widen(char c) const;
Uses the stream's locale to convert the tiny character c to a
wide character, then returns it.
SEE ALSO
ios_base, basic_istream, basic_ostream,
basic_streambuf, char_traits
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++.
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
iosfwd
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
iosfwd
DESCRIPTION
The header iosfwd forward declares the input/output library template
classes and specializes them for wide and tiny characters. It also
defines the positional types used in class char_traits instantiated
on tiny and wide characters.
SYNOPSIS
#include <iosfwd>
// forward declare the traits class
template<class charT> struct char_traits;
// forward declare the positioning class
template<class stateT> class fpos;
// forward declare the state class
class mbstate_t;
// forward declare the allocator class
template<class T> class allocator;
// forward declare the iostreams template classes
template<class charT,class traits=char_traits<charT>>
class basic_ios;
template<class charT,class traits=char_traits<charT>>
class basic_streambuf;
template<class charT,class traits=char_traits<charT>>
class basic_istream;
template<class charT,class traits=char_traits<charT>>
class basic_ostream;
template<class charT,class traits=char_traits<charT>,
class Allocator = allocator<void> >
class basic_stringbuf;
template<class charT,class traits=char_traits<charT>,
class Allocator = allocator<void> >
class basic_istringstream;
template<class charT,class traits=char_traits<charT>,
class Allocator = allocator<void> >
class basic_ostringstream;
template<class charT,class traits=char_traits<charT>>
class basic_filebuf;
template<class charT,class traits=char_traits<charT>>
class basic_ifstream;
template<class charT,class traits=char_traits<charT>>
class basic_ofstream;
template<class charT,class traits=char_traits<charT>>
class ostreambuf_iterator;
template<class charT,class traits=char_traits<charT>>
class istreambuf_iterator;
template<class charT,class traits=char_traits<charT>>
class basic_iostream;
template<class charT,class traits=char_traits<charT>,
class Allocator = allocator<void> >
class basic_stringstream;
template<class charT,class traits=char_traits<charT>>
class basic_fstream;
// specializations on tiny characters
typedef basic_ios<char> ios;
typedef basic_streambuf<char> streambuf;
typedef basic_istream<char> istream;
typedef basic_ostream<char> ostream;
typedef basic_stringbuf<char> stringbuf;
typedef basic_istringstream<char> istringstream;
typedef basic_ostringstream<char> ostringstream;
typedef basic_filebuf<char> filebuf;
typedef basic_ifstream<char> ifstream;
typedef basic_ofstream<char> ofstream;
typedef basic_iostream<char> iostream;
typedef basic_stringstream<char> stringstream;
typedef basic_fstream<char> fstream;
// specializations on wide characters
typedef basic_ios<wchar_t> wios;
typedef basic_streambuf<wchar_t> wstreambuf;
typedef basic_istream<wchar_t> wistream;
typedef basic_ostream<wchar_t> wostream;
typedef basic_stringbuf<wchar_t> wstringbuf;
typedef basic_istringstream<wchar_t> wistringstream;
typedef basic_ostringstream<wchar_t> wostringstream;
typedef basic_filebuf<wchar_t> wfilebuf;
typedef basic_ifstream<wchar_t> wifstream;
typedef basic_ofstream<wchar_t> wofstream;
typedef basic_iostream<wchar_t> wiostream;
typedef basic_stringstream<wchar_t> wstringstream;
typedef basic_fstream<wchar_t> wfstream;
// positional types used by char_traits
typedef fpos<mbstate_t> streampos;
typedef fpos<mbstate_t> wstreampos;
typedef long streamoff;
typedef long wstreamoff;
SEE ALSO
fpos, char_traits, basic_ios,
basic_streambuf, basic_istream, basic_ostream,
basic_iostream,
basic_stringbuf, basic_istringstream,
basic_ostringstream, basic_stringstream,
basic_filebuf, basic_ifstream, basic_ofstream,
basic_fstream, istreambuf_iterator,
ostreambuf_iterator
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.2
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
istream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_istream,istream
This page describes the ANSI basic_istream class. If you would like
information on the pre-ANSI istream class, use the command:
help cxxl
SYNOPSIS
#include <istream>
template<class charT, class traits = char_traits<charT> >
class basic_istream
: virtual public basic_ios<charT, traits>
DESCRIPTION
The class basic_istream defines a number of member function
signatures that assist in reading and interpreting input from
sequences controlled by a stream buffer.
Two groups of member function signatures share common properties:
the formatted input functions (or extractors) and the unformatted
input functions. Both groups of input functions obtain (or
extract) input characters by calling basic_streambuf member
functions. They both begin by constructing an object of class
basic_istream::sentry and, if this object is in good state after
construction, the function endeavors to obtain the requested
input. The sentry object performs exception safe initialization,
such as controlling the status of the stream or locking it
in multithread environment.
Some formatted input functions parse characters extracted from the
input sequence, converting the result to a value of some scalar
data type, and storing the converted value in an object of that
scalar type. The conversion behavior is locale dependent,
and directly depend on the locale object imbued in the
stream.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_istream
: virtual public basic_ios<charT, traits> {
public:
typedef basic_istream<charT, traits> istream_type;
typedef basic_ios<charT, traits> ios_type;
typedef basic_streambuf<charT, traits> streambuf_type;
typedef traits traits_type;
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_istream(basic_streambuf<charT, traits> *sb);
virtual ~basic_istream();
class sentry
{
public:
inline explicit sentry(basic_istream<charT,traits>&,
bool noskipws = 0);
~sentry();
operator bool ();
};
istream_type& operator>>(istream_type& (*pf)(istream_type&));
istream_type& operator>>(ios_base& (*pf)(ios_base&));
istream_type& operator>>(ios_type& (*pf)(ios_type&));
istream_type& operator>>(bool& n);
istream_type& operator>>(short& n);
istream_type& operator>>(unsigned short& n);
istream_type& operator>>(int& n);
istream_type& operator>>(unsigned int& n);
istream_type& operator>>(long& n);
istream_type& operator>>(unsigned long& n);
istream_type& operator>>(float& f);
istream_type& operator>>(double& f);
istream_type& operator>>(long double& f);
istream_type& operator>>(void*& p);
istream_type& operator>>(streambuf_type& sb);
istream_type& operator>>(streambuf_type *sb);
int_type get();
istream_type& get(char_type *s, streamsize n, char_type delim);
istream_type& get(char_type *s, streamsize n);
istream_type& get(char_type& c);
istream_type& get(streambuf_type& sb,char_type delim);
istream_type& get(streambuf_type& sb);
istream_type& getline(char_type *s, streamsize n,char_type delim);
istream_type& getline(char_type *s, streamsize n);
istream_type& ignore(streamsize n = 1,
int_type delim = traits::eof());
istream_type& read(char_type *s, streamsize n);
streamsize readsome(char_type *s, streamsize n);
int peek();
pos_type tellg();
istream_type& seekg(pos_type&);
istream_type& seekg(off_type&, ios_base::seekdir);
istream_type& putback(char_type c);
istream_type& unget();
streamsize gcount() const;
int sync();
protected:
explicit basic_istream( );
};
//global function
template<class charT, class traits>
basic_istream<charT, traits>&
ws(basic_istream<charT, traits>&);
template<class charT, class traits>
basic_istream<charT, traits>&
operator>> (basic_istream<charT, traits>&, charT&);
template<class charT, class traits>
basic_istream<charT, traits>&
operator>> (basic_istream<charT, traits>&, charT*);
template<class traits>
basic_istream<char, traits>&
operator>> (basic_istream<char, traits>&, unsigned char&);
template<class traits>
basic_istream<char, traits>&
operator>> (basic_istream<char, traits>&, signed char&);
template<class traits>
basic_istream<char, traits>&
operator>> (basic_istream<char, traits>&, unsigned char*);
template<class traits>
basic_istream<char, traits>&
operator>> (basic_istream<char, traits>&, signed char*);
TYPES
char_type
The type char_type is a synonym for them template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
ios_type
The type ios_type is a synonym for basic_ios<charT, traits> .
istream
The type istream is an instantiation of class basic_istream on type
char:
typedef basic_istream<char> istream;
istream_type
The type istream_type is a synonym for basic_istream<charT, traits>.
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.
streambuf_type
The type streambuf_type is a synonym for basic_streambuf<charT,
traits> .
traits_type
The type traits_type is a synonym for the template parameter
traits.
wistream
The type wistream is an instantiation of class basic_istream on type
wchar_t:
typedef basic_istream<wchar_t> wistream;
PUBLIC CONSTRUCTOR
explicit basic_istream(basic_streambuf<charT, traits>* sb);
Constructs an object of class basic_istream, assigning initial
values to the base class by calling basic_ios::init(sb).
PUBLIC DESTRUCTOR
virtual ~basic_istream();
Destroys an object of class basic_istream.
SENTRY CLASS
explicit sentry(basic_istream<charT,traits>&, bool noskipws=0);
Prepares for formatted or unformatted input. First if the
basic_ios member function tie() is not a null pointer, the
function synchronizes the output sequence with any associated
stream. If noskipws is zero and the ios_base member function
flags() & skipws is nonzero, the function extracts and discards
each character as long as the next available input
character is a white space character. If after any preparation is
completed the basic_ios member function good() is true, the
sentry conversion function operator bool() will return true.
Otherwise it will return false. In multithread environment the
sentry object constructor is responsible for locking the stream
and the stream buffer associated with the stream.
~sentry();
Destroys an object of class sentry. In multithread environment,
the sentry object destructor is responsible for
unlocking the stream and the stream buffer associated with the
stream.
operator bool();
If after any preparation is completed the basic_ios member
function good() is true, the sentry conversion function
operator bool() will return true else it will return false.
EXTRACTORS
istream_type&
operator>>(istream_type&
(*pf) (istream_type&));
Calls pf(*this), then return *this. See, for example, the
function signature ws(basic_istream&).
istream_type&
operator>>(ios_type& (*pf) (ios_type&));
Calls pf(*this), then return *this.
istream_type&
operator>>(ios_base& (*pf) (ios_base&));
Calls pf(*this), then return *this. See, for example, the
function signature dec(ios_base&).
istream_type&
operator>>(bool& n);
Converts a Boolean value, if one is available, and stores it in
n. If the ios_base member function flag() & ios_base::boolalpha
is false it tries to read an integer value, which if found must
be 0 or 1. If the boolalpha flag is true, it reads
characters until it determines whether the characters read are
correct according to the locale function numpunct<>::truename()
or numpunct<>::falsename(). If no match is found, it
calls the basic_ios member function setstate(failbit), which may
throw ios_base::failure.
istream_type&
operator>>(short& n);
Converts a signed short integer, if one is available, and stores
it in n, then returns *this.
istream_type&
operator>>(unsigned short& n);
Converts an unsigned short integer, if one is available, and
stores it in n, then return *this.
istream_type&
operator>>(int& n);
Converts a signed integer, if one is available, and stores it in
n, then return *this.
istream_type&
operator>>(unsigned int& n);
Converts an unsigned integer, if one is available, and stores it
in n, then return *this.
istream_type&
operator>>(long& n);
Converts a signed long integer, if one is available, and stores
it in n, then returns *this.
istream_type&
operator>>(unsigned long& n);
Converts an unsigned long integer, if one is available, and
stores it in n, then returns *this.
istream_type&
operator>>(float& f);
Converts a float, if one is available, and stores it in f, then
returns *this.
istream_type&
operator>>(double& f);
Converts a double, if one is available, and stores it in f, then
returns *this.
istream_type&
operator>>(long double& f);
Converts a long double, if one is available, and stores it in f,
then returns *this.
istream_type&
operator>>(void*& p);
Extracts a void pointer, if one is available, and stores it in p,
then return *this.
istream_type&
operator>>(streambuf_type* sb);
If sb is null, calls the basic_ios member function
setstate(badbit), which may throw ios_base::failure.
Otherwise extracts characters from *this and inserts them in the
output sequence controlled by sb. Characters are extracted
and inserted until any of the following occurs:
+ end-of-file occurs on the input sequence
+ inserting in the output sequence fails
+ an exception occurs
If the function stores no characters, it calls the basic_ios
member function setstate(failbit), which may throw
ios_base::failure. If failure was due to catching an exception
thrown while extracting characters from sb and failbit is on in
exception(), then the caught exception is rethrown.
istream_type&
operator>>(streambuf_type& sb);
Extracts characters from *this and inserts them in the output
sequence controlled by sb. Characters are extracted and
inserted until any of the following occurs:
+ end-of-file occurs on the input sequence
+ inserting in the output sequence fails
+ an exception occurs
If the function stores no characters, it calls the basic_ios
member function setstate(failbit), which may throw
ios_base::failure. If failure was due to catching an exception
thrown while extracting characters from sb and failbit is on in
exception(), then the caught exception is rethrown.
UNFORMATTED FUNCTIONS
streamsize
gcount() const;
Returns the number of characters extracted by the last
unformatted input member function called.
int_type
get();
Extracts a character, if one is available. Otherwise, the
function calls the basic_ios member function setstate(failbit),
which may throw ios_base::failure. Returns the character
extracted or traits::eof() if none is available.
istream_type&
get(char_type& c);
Extracts a character, if one is available, and assigns it to c.
Otherwise, the function calls the basic_ios member function
setstate(failbit), which may throw ios_base::failure.
istream_type&
get(char_type* s, streamsize n,char_type delim);
Extracts characters and stores them into successive locations of
an array whose first element is designated by s. Characters
are extracted and stored until any of the following occurs:
+ n-1 characters are stored
+ end-of-file occurs on the input sequence
+ the next available input character == delim.
If the function stores no characters, it calls the basic_ios
member function setstate(failbit), which may throw
ios_base::failure. In any case, it stores a null character into
the next successive location of the array.
istream_type&
get(char_type* s, streamsize n);
Calls get(s,n,widen('0)).
istream_type&
get(streambuf_type& sb,char_type delim);
Extracts characters and inserts them in the output sequence
controlled by sb. Characters are extracted and inserted
until any of the following occurs:
+ end-of-file occurs on the input sequence
+ inserting in the output sequence fails
+ the next available input character == delim.
+ an exception occurs
If the function stores no characters, it calls the basic_ios
member function setstate(failbit), which may throw
ios_base::failure. If failure was due to catching an exception
thrown while extracting characters from sb and failbit is on in
exception(), then the caught exception is rethrown.
istream_type&
get(streambuf_type& sb);
Calls get(sb,widen('0)).
istream_type&
getline(char_type* s, streamsize n, char_type delim);
Extracts characters and stores them into successive locations of
an array whose first element is designated by s. Characters
are extracted and stored until any of the following occurs:
+ n-1 characters are stored
+ end-of-file occurs on the input sequence
+ the next available input character == delim.
If the function stores no characters, it calls the basic_ios
member function setstate(failbit), which may throw
ios_base::failure. In any case, it stores a null character into
the next successive location of the array.
istream_type&
getline(char_type* s, streamsize n);
Calls getline(s,n,widen('0)).
istream_type&
ignore(streamsize n=1, int_type delim=traits::eof());
Extracts characters and discards them. Characters are extracted
until any of the following occurs:
+ n characters are extracted
+ end-of-file occurs on the input sequence
+ the next available input character == delim.
int_type
peek();
Returns traits::eof() if the basic_ios member function good()
returns false. Otherwise, returns the next available character.
Does not increment the current get pointer.
istream_type&
putback(char_type c);
Insert c in the putback sequence.
istream_type&
read(char_type* s, streamsize n);
Extracts characters and stores them into successive locations of
an array whose first element is designated by s. Characters
are extracted and stored until any of the following occurs:
+ n characters are stored
+ end-of-file occurs on the input sequence
If the function does not store n characters, it calls the
basic_ios member function setstate(failbit), which may
throw ios_base::failure.
streamsize
readsome(char_type* s, streamsize n);
Extracts characters and stores them into successive locations of
an array whose first element is designated by s. If
rdbuf()->in_avail() == -1, calls the basic_ios member function
setstate(eofbit).
+ If rdbuf()->in_avail() == 0, extracts no characters
+ If rdbuf()->in_avail() > 0, extracts min( rdbuf()->in_avail(),
n)
In any case the function returns the number of characters extracted.
istream_type&
seekg(pos_type& pos);
If the basic_ios member function fail() returns false, executes
rdbuf()->pubseekpos(pos), which will position the current pointer
of the input sequence at the position designated by pos.
istream_type&
seekg(off_type& off, ios_base::seekdir dir);
If the basic_ios member function fail() returns false, executes
rdbuf()->pubseekpos(off,dir), which will position the current
pointer of the input sequence at the position designated by
off and dir.
int
sync();
If rdbuf() is a null pointer, return -1. Otherwise, calls
rdbuf()- >pubsync() and if that function returns -1 calls
the basic_ios member function setstate(badbit). The purpose of
this function is to synchronize the internal input buffer,
with the external sequence of characters.
pos_type
tellg();
If the basic_ios member function fail() returns true, tellg()
returns pos_type(off_type(-1)) to indicate failure. Otherwise it
returns the current position of the input sequence by calling
rdbuf()- >pubseekoff(0,cur,in).
istream_type&
unget();
If rdbuf() is not null, calls rdbuf()->sungetc(). If rdbuf() is
null or if sungetc() returns traits::eof(), calls the basic_ios
member function setstate(badbit).
NON MEMBER FUNCTIONS
template<class charT, class traits>
basic_istream<charT, traits>&
operator>>(basic_istream<charT, traits>& is, charT& c);
Extracts a character if one is available, and stores it in c.
Otherwise the function calls the basic_ios member function
setstate(failbit), which may throw ios_base::failure.
template<class charT, class traits>
basic_istream<charT, traits>&
operator>>(basic_istream<charT, traits>& is, charT* s);
Extracts characters and stores them into successive locations of
an array whose first element is designated by s. If the
ios_base member function is.width() is greater than zero, then
is.width() is the maximum number of characters stored. Characters
are extracted and stored until any of the following occurs:
+ if is.witdh()>0, is.witdh()-1 characters are extracted
+ end-of-file occurs on the input sequence
+ the next available input character is a white space.
If the function stores no characters, it calls the basic_ios
member function setstate(failbit), which may throw
ios_base::failure. In any case, it then stores a null character
into the next successive location of the array and calls
width(0).
Template<class traits>
basic_istream<char, traits>&
operator>>(basic_istream<char, traits>& is, unsigned char& c);
Returns is >> (char&)c.
Template<class traits>
basic_istream<char, traits>&
operator>>(basic_istream<char, traits>& is, signed char& c);
Returns is >> (char&)c.
Template<class traits>
basic_istream<char, traits>&
operator>>(basic_istream<char, traits>& is, unsigned char* c);
Returns is >> (char*)c.
Template<class traits>
basic_istream<char, traits>&
operator>>(basic_istream<char, traits>& is, signed char* c);
Returns is >> (char*)c.
template<class charT, class traits>
basic_istream<charT, traits>&
ws(basic_istream<charT, traits>& is);
Skips any white space in the input sequence and returns is.
EXAMPLES
//
// stdlib/examples/manual/istream1.cpp
//
#include<iostream>
#include<istream>
#include<fstream>
void main ( )
{
using namespace std;
float f= 3.14159;
int i= 3;
char s[200];
// open a file for read and write operations
ofstream out("example", ios_base::in | ios_base::out
| ios_base::trunc);
// tie the istream object to the ofstream filebuf
istream in (out.rdbuf());
// output to the file
out << "Annie is the Queen of porting" << endl;
out << f << endl;
out << i << endl;
// seek to the beginning of the file
in.seekg(0);
f = i = 0;
// read from the file using formatted functions
in >> s >> f >> i;
// seek to the beginning of the file
in.seekg(0,ios_base::beg);
// output the all file to the standard output
cout << in.rdbuf();
// seek to the beginning of the file
in.seekg(0);
// read the first line in the file
// "Annie is the Queen of porting"
in.getline(s,100);
cout << s << endl;
// read the second line in the file
// 3.14159
in.getline(s,100);
cout << s << endl;
// seek to the beginning of the file
in.seekg(0);
// read the first line in the file
// "Annie is the Queen of porting"
in.get(s,100);
// remove the newline character
in.ignore();
cout << s << endl;
// read the second line in the file
// 3.14159
in.get(s,100);
cout << s << endl;
// remove the newline character
in.ignore();
// store the current file position
istream::pos_type position = in.tellg();
out << "replace the int" << endl;
// move back to the previous saved position
in.seekg(position);
// output the remain of the file
// "replace the int"
// this is equivalent to
// cout << in.rdbuf();
while( !char_traits<char>::eq_int_type(in.peek(),
char_traits<char>::eof()) )
cout << char_traits<char>::to_char_type(in.get());
cout << "0 << flush;
}
//
// istream example two
//
#include <iostream>
void main ( )
{
using namespace std;
char p[50];
// remove all the white spaces
cin >> ws;
// read characters from stdin until a newline
// or 49 characters have been read
cin.getline(p,50);
// output the result to stdout
cout << p;
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_streambuf, basic_iostream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.6.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
iostream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_iostream,iostream
This page describes the ANSI basic_iostream class. If you would
like information on the pre-ANSI iostream class, use the command:
help cxxl
SYNOPSIS
#include <istream>
template<class charT, class traits = char_traits<charT> >
class basic_iostream
: public basic_istream<charT, traits>,
public basic_ostream<charT, traits>
DESCRIPTION
The class basic_iostream inherits a number of functions from classes
basic_ostream<charT, traits> and basic_istream<charT, traits>. They
assist in formatting and interpreting sequences of characters
controlled by a stream buffer. Two groups of functions share common
properties, the formatted functions and the unformatted functions.
INTERFACE
template<class charT, class traits>
class basic_iostream
: public basic_istream<charT, traits>,
public basic_ostream<charT, traits>
{
public:
explicit basic_iostream(basic_streambuf<charT, traits> *sb);
virtual ~basic_iostream();
protected:
explicit basic_iostream();
};
PUBLIC CONSTRUCTORS
explicit basic_iostream(basic_streambuf<charT, traits>* sb);
Constructs an object of class basic_iostream, assigning initial
values to the base class by calling basic_istream<charT,
traits>(sb) and basic_ostream<charT, traits>(sb).
explicit basic_iostream();
Constructs an object of class basic_iostream, assigning initial
values to the base class by calling basic_istream<charT,
traits>() and basic_ostream<charT, traits>(). After construction
the object has its badbit set.
DESTRUCTOR
virtual ~basic_iostream();
Destroys an object of class basic_iostream.
EXAMPLES
See basic_istream and basic_ostream examples.
COMPATIBILITY
[Digital] The ANSI Standard Library provides two macros which
enable or disable use of the ANSI iostream package at compile
time.
______________________________________________________________
Macro Description
______________________________________________________________
__USE_STD_IOSTREAM Use the ANSI Standard iostream package
__NO_USE_STD_IOSTREAM Use the pre-ANSI iostream package
______________________________________________________________
See help cxxl for more details.
SEE ALSO
char_traits, ios_base, basic_ios,
basic_streambuf, basic_istream, basic_ostream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section
27.6.1.4.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
ios_base
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
ios_base
SYNOPSIS
#include <ios>
class ios_base;
DESCRIPTION
The class ios_base defines several member types:
+ A class failure derived from exception.
+ A class Init.
+ Three bitmask types, fmtflags, iostate and openmode.
+ Two enumerated types, seekdir, and event.
It maintains several kinds of data:
+ Control information that influences how to interpret (format)
input sequences and how to generate (format) output sequences.
+ Locale object used within the stream classes.
+ Additional information that is stored by the program for its
private use.
INTERFACE
class ios_base {
public:
class failure : public exception {
public:
explicit failure(const string& msg);
virtual ~failure() throw();
virtual const char* what() const throw();
};
typedef int iostate;
enum io_state {
goodbit = 0x00,
badbit = 0x01,
eofbit = 0x02,
failbit = 0x04
};
typedef int openmode;
enum open_mode {
app = 0x01,
binary = 0x02,
in = 0x04,
out = 0x08,
trunc = 0x10,
ate = 0x20
};
typedef int seekdir;
enum seek_dir {
beg = 0x0,
cur = 0x1,
end = 0x2
};
typedef int fmtflags;
enum fmt_flags {
boolalpha = 0x0001,
dec = 0x0002,
fixed = 0x0004,
hex = 0x0008,
internal = 0x0010,
left = 0x0020,
oct = 0x0040,
right = 0x0080,
scientific = 0x0100,
showbase = 0x0200,
showpoint = 0x0400,
showpos = 0x0800,
skipws = 0x1000,
unitbuf = 0x2000,
uppercase = 0x4000,
adjustfield = left | right | internal,
basefield = dec | oct | hex,
floatfield = scientific | fixed
};
enum event {
erase_event = 0x0001,
imbue_event = 0x0002,
copyfmt_event = 0x004
};
typedef void (*event_callback) (event, ios_base&, int index);
void register_callback(event_callback fn, int index);
class Init;
fmtflags flags() const;
fmtflags flags(fmtflags fmtfl);
fmtflags setf(fmtflags fmtfl);
fmtflags setf(fmtflags fmtfl, fmtflags mask);
void unsetf(fmtflags mask);
ios_base& copyfmt(const ios_base& rhs);
streamsize precision() const;
streamsize precision(streamsize prec);
streamsize width() const;
streamsize width(streamsize wide);
locale imbue(const locale& loc);
locale getloc() const
static int xalloc();
long& iword(int index);
void*& pword(int index);
bool synch_with_stdio(bool sync = true);
bool is_synch();
protected:
ios_base();
~ios_base();
private:
union ios_user_union {
long lword;
void* pword;
};
union ios_user_union *userwords_;
};
ios_base& boolalpha(ios_base&);
ios_base& noboolalpha(ios_base&);
ios_base& showbase(ios_base&);
ios_base& noshowbase(ios_base&);
ios_base& showpoint(ios_base&);
ios_base& noshowpoint(ios_base&);
ios_base& showpos(ios_base&);
ios_base& noshowpos(ios_base&);
ios_base& skipws(ios_base&);
ios_base& noskipws(ios_base&);
ios_base& uppercase(ios_base&);
ios_base& nouppercase(ios_base&);
ios_base& internal(ios_base&);
ios_base& left(ios_base&);
ios_base& right(ios_base&);
ios_base& dec(ios_base&);
ios_base& hex(ios_base&);
ios_base& oct(ios_base&);
ios_base& fixed(ios_base&);
ios_base& scientific(ios_base&);
ios_base& unitbuf(ios_base&);
ios_base& nounitbuf(ios_base&);
TYPES
fmtflags
The type fmtflags is a bitmask type. Setting its elements has the
following effects:
showpos Generates a + sign in non-negative generated numeric
output.
showbase Generates a prefix indicating the numeric base of
generated integer output.
uppercase Replaces certain lowercase letters with their uppercase
equivalents in generated output.
showpoint Generates a decimal-point character unconditionally in
generated floating-point output.
boolalpha Inserts and extracts bool type in alphabetic format.
unitbuf Flushes output after each output operation.
internal Adds fill characters at a designated internal point
in certain generated output, or identical to right if
no such point is designated.
left Adds fill characters on the right (final positions) of
certain generated output.
right Adds fill characters on the left (initial positions) of
certain generated output.
dec Converts integer input or generates integer output in decimal
base.
hex Converts integer input or generates integer output in
hexadecimal base.
oct Converts integer input or generates integer output in octal
base.
fixed Generates floating-point output in fixed-point notation.
scientific Generates floating-point output in scientific notation.
skipws Skips leading white space before certain input operation.
iostate
The type iostate is a bitmask type. Setting its elements has the
following effects:
badbit Indicates a loss of integrity in an input or output
sequence.
eofbit Indicates that an input operation reached the end of an
input sequence.
failbit Indicates that an input operation failed to read the
expected characters, or that an output operation failed
to generate the desired characters.
openmode
The type openmode is a bitmask type. Setting its elements has the
following effects:
app Seeks to the end before writing.
ate Opens and seek to end immediately after opening.
binary Performs input and output in binary mode.
in Opens for input.
out Opens for output.
trunc Truncates an existing stream when opening.
seekdir
The type seekdir is a bitmask type. Setting its elements has the
following effects:
beg Requests a seek relative to the beginning of the stream.
cur Requests a seek relative to the current position within the
sequence.
end Requests a seek relative to the current end of the sequence.
event_callback
The type event_callback is the type of the callback function used
as a parameter in the function register_callback. These
functions allow you to use the iword, pword mechanism in an
exception-safe environment.
PUBLIC CONSTRUCTOR
ios_base();
The ios_base members have an indeterminate value after
construction.
PUBLIC DESTRUCTOR
~ios_base();
Destroys an object of class ios_base. Calls each registered
callback pair (fn, index) as (*fn)(erase_event,*this, index) at
such a time that any ios_base member function called from
within fn has well-defined results.
PUBLIC MEMBER FUNCTIONS
ios_base&
copyfmt(const ios_base& rhs);
Assigns to the member objects of *this the corresponding member
objects of rhs. The content of the union pointed at by pword and
iword is copied, not the pointers itself. Before copying any
parts of rhs, calls each registered callback pair (fn,index) as
(*fn)(erase_even,*this, index). After all parts have been
replaced, calls each callback pair that was copied from rhs as
(*fn)(copy_event,*this,index).
fmtflags
flags() const;
Returns the format control information for both input and output
fmtflags
flags(fmtflags fmtfl);
Saves the format control information, then sets it to fmtfl and
returns the previously saved value.
locale
getloc() const;
Returns the imbued locale, to be used to perform locale-dependent
input and output operations. The default locale,
locale::locale(), is used if no other locale object has been
imbued in the stream by a call to the imbue function.
locale
imbue(const locale& loc);
Saves the value returned by getloc() then assigns loc to a
private variable and calls each registered callback pair
(fn, index) as (*fn)(imbue_event,*this, index). It then returns
the previously saved value.
bool
is_sync();
Returns true if the C++ standard streams and the standard C
streams are synchronized, otherwise returns false. This function
is not part of the C++ standard.
long&
iword(int idx);
Returns userwords_[idx].lword. If userwords_ is a null pointer,
allocates a union of long and void* of unspecified size and
stores a pointer to its first element in userwords_. The
function then extends the union pointed at by userwords_
as necessary to include the element userwords_[idx]. Each newly
allocated element of the union is initialized to zero. The
reference returned may become invalid after another call to the
object's iword or pword member with a different index, after
a call to its copyfmt member, or when the object is destroyed.
streamsize
precision() const;
Returns the precision (number of digits after the decimal point)
to generate on certain output conversions.
streamsize
precision(streamsize prec);
Saves the precision then sets it to prec and returns the
previously saved value.
void*&
pword(int idx);
Returns userword_[idx].pword. If userwords_ is a null pointer,
allocates a union of long and void* of unspecified size and
stores a pointer to its first element in userwords_. The
function then extends the union pointed at by userwords_
as necessary to include the element userwords_[idx]. Each newly
allocated element of the array is initialized to zero. The
reference returned may become invalid after another call to the
object's pword or iword member with different index, after a
call to its copyfmt member, or when the object is destroyed.
void
register_callback(event_callback fn, int index);
Registers the pair (fn, index) such that during calls to
imbue(),copyfmt(), or ~ios_base(), the function fn is called with
argument index. Functions registered are called when an event
occurs, in opposite order of registration. Functions
registered while a callback function is active are not called
until the next event. Identical pairs are not merged; a function
registered twice is called twice per event.
fmtflags
setf(fmtflags fmtfl);
Saves the format control information, then sets it to fmtfl and
returns the previously saved value.
fmtflags
setf(fmtflags fmtfl, fmtflags mask);
Saves the control information, then clears mask in
flags(),sets fmtfl & mask in flags() and returns the previously
saved value.
bool
sync_with_stdio(bool sync = true);
Called with a false argument, it allows the C++ standard streams
to operate independently of the standard C streams, which will
greatly improve performance when using the C++ standard streams.
Called with a true argument it restores the default
synchronization. The return value of the function is the
status of the synchronization at the time of the call.
void
unsetf(fmtflags mask);
Clears mask in flags().
streamsize
width() const;
Returns the field width (number of characters) to generate on
certain output conversions.
streamsize
width(streamsize wide);
Saves the field width then sets it to wide and returns the
previously saved value.
static int
xalloc();
Returns the next static index that can be used with pword and
iword. This is useful if you want to share data between several
stream objects.
THE CLASS FAILURE
The class failure defines the base class for the types of all
objects thrown as exceptions, by functions in the iostreams library,
to report errors detected during stream buffer operations.
explicit failure(const string& msg);
Constructs an object of class failure, initializing the base
class with exception(msg).
const char*
what() const;
Returns the message msg with which the exception was created.
CLASS INIT
The class Init describes an object whose construction ensures the
construction of the eight objects declared in <iostream>
that associate file stream buffers with the standard C streams.
NON-MEMBER FUNCTIONS
ios_base&
boolalpha(ios_base& str);
Calls str.setf(ios_base::boolalpha) and returns str.
ios_base&
dec(ios_base& str);
Calls str.setf(ios_base::dec, ios_base::basefield) and returns
str.
ios_base&
fixed(ios_base& str);
Calls str.setf(ios_base::fixed, ios_base::floatfield) and returns
str.
ios_base&
hex(ios_base& str);
Calls str.setf(ios_base::hex, ios_base::basefield) and returns str.
ios_base&
internal(ios_base& str);
Calls str.setf(ios_base::internal, ios_base::adjustfield) and
returns str.
ios_base&
left(ios_base& str);
Calls str.setf(ios_base::left, ios_base::adjustfield) and returns
str.
ios_base&
noboolalpha(ios_base& str);
Calls str.unsetf(ios_base::boolalpha) and returns str.
ios_base&
noshowbase(ios_base& str);
Calls str.unsetf(ios_base::showbase) and returns str.
ios_base&
noshowpoint(ios_base& str);
Calls str.unsetf(ios_base::showpoint) and returns str.
ios_base&
noshowpos(ios_base& str);
Calls str.unsetf(ios_base::showpos) and returns str.
ios_base&
noskipws(ios_base& str);
Calls str.unsetf(ios_base::skipws) and returns str.
ios_base&
nounitbuf(ios_base& str);
Calls str.unsetf(ios_base::unitbuf) and returns str.
ios_base&
nouppercase(ios_base& str);
Calls str.unsetf(ios_base::uppercase) and returns str.
ios_base&
oct(ios_base& str);
Calls str.setf(ios_base::oct, ios_base::basefield) and returns str.
ios_base&
right(ios_base& str);
Calls str.setf(ios_base::right, ios_base::adjustfield) and returns
str.
ios_base&
scientific(ios_base& str);
Calls str.setf(ios_base::scientific, ios_base::floatfield) and
returns str.
ios_base&
showbase(ios_base& str);
Calls str.setf(ios_base::showbase) and returns str.
ios_base&
showpoint(ios_base& str);
Calls str.setf(ios_base::showpoint) and returns str.
ios_base&
showpos(ios_base& str);
Calls str.setf(ios_base::showpos) and returns str.
ios_base&
skipws(ios_base& str);
Calls str.setf(ios_base::skipws) and returns str.
ios_base&
unitbuf(ios_base& str);
Calls str.setf(ios_base::unitbuf) and returns str.
ios_base&
uppercase(ios_base& str);
Calls str.setf(ios_base::uppercase) and returns str.
SEE ALSO
basic_ios, basic_istream, basic_ostream,
char_traits
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.4.3
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
istringstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_istringstream
SYNOPSIS
#include <sstream>
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
class basic_istringstream
: public basic_istream<charT, traits>
DESCRIPTION
The template class basic_istringstream<charT,traits,Allocator>
provides functionality to read from an array in memory. It
supports reading objects of class
basic_string<charT,traits,Allocator>. It uses a basic_stringbuf
object to control the associated storage. It inherits from
basic_istream and therefore can use all the formatted and
unformatted input functions.
INTERFACE
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
class basic_istringstream
: public basic_istream<charT, traits> {
public:
typedef basic_stringbuf<charT, traits, Allocator> sb_type;
typedef basic_ios<charT, traits> ios_type;
typedef basic_string<charT, traits, Allocator> string_type;
typedef traits traits_type;
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_istringstream(ios_base::openmode which =
ios_base::in);
explicit basic_istringstream(const string_type& str,
ios_base::openmode which =
ios_base::in);
virtual ~basic_istringstream();
basic_stringbuf<charT,traits,Allocator> *rdbuf() const;
string_type str() const;
void str(const string_type& str);
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
ios_type
The type ios_type is an instantiation of class basic_ios on type
charT.
istringstream
The type istringstream is an instantiation of class
basic_istringstream on type char:
typedef basic_istringstream<char> istringstream;
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.
sb_type
The type sb_type is an instantiation of class basic_stringbuf on
type charT.
string_type
The type string_type is an instantiation of class basic_string on
type charT.
traits_type
The type traits_type is a synonym for the template parameter traits.
wistringstream
The type wistringstream is an instantiation of class
basic_istringstream on type wchar_t:
typedef basic_istringstream<wchar_t> wistringstream;
CONSTRUCTORS
explicit basic_istringstream(ios_base::openmode which =
ios_base::in);
Constructs an object of class basic_istringstream,
initializing the base class basic_istream with the
associated string buffer. The string buffer is ini-
tialized by calling the basic_stringbuf constructor
basic_stringbuf<charT,traits,Allocator>(which).
explicit basic_istringstream(const string_type& str,
ios_base::openmode which =
ios_base::in);
Constructs an object of class basic_istringstream,
initializing the base class basic_istream with the
associated string buffer. The string buffer is ini-
tialized by calling the basic_stringbuf constructor
basic_stringbuf<charT,traits,Allocator>(str,which).
DESTRUCTOR
virtual ~basic_istringstream();
Destroys an object of class basic_istringstream.
MEMBER FUNCTIONS
basic_stringbuf<charT,traits,Allocator>*
rdbuf() const;
Returns a pointer to the basic_stringbuf associated with the
stream.
string_type
str() const;
Returns a string object of type string_type, which contains a
copy of the underlying buffer contents.
void
str(const string_type& str);
Clears the string buffer and copies the string object str into
it. If the opening mode is in, initialize the input
sequence to point at the first character of the buffer. If
the opening mode is out, initialize the output sequence to
point at the first character of the buffer. If the opening
mode is out | app, initialize the output sequence to point at
the last character of the buffer.
EXAMPLES
//
// stdlib/examples/manual/istringstream.cpp
//
#include<iostream>
#include<sstream>
#include<string>
#include<iomanip>
void main ( )
{
using namespace std;
long l= 20;
wchar_t *ntbs=L"Il avait l'air heureux";
wchar_t c;
wchar_t buf[50];
// create a read/write string-stream object on wide char
// and attach it to an wistringstream object
wistringstream in(ios_base::in | ios_base::out);
// tie the ostream object to the wistringstream object
wostream out(in.rdbuf());
// output ntbs in out
out << ntbs;
// output each word on a separate line
while ( in.get(c) )
{
if ( c == L' ' )
wcout << endl;
else
wcout << c;
}
wcout << endl << endl;
// move back the input sequence to the beginning
in.seekg(0);
// clear the state flags
in.clear();
// does the same thing as the previous code
// output each word on a separate line
while ( in >> buf )
wcout << buf << endl;
wcout << endl << endl;
// create a tiny string object
string test_string("Il dormait pour l'eternite");
// create a read/write string-stream object on char
// and attach it to an istringstream object
istringstream in_bis(ios_base:: in | ios_base::out |
ios_base::app );
// create an ostream object
ostream out_bis(in_bis.rdbuf());
// initialize the string buffer with test_string
in_bis.str(test_string);
out_bis << endl;
// output the base info before each integer
out_bis << showbase;
ostream::pos_type pos= out_bis.tellp();
// output l in hex with a field with of 20
out_bis << hex << setw(20) << l << endl;
// output l in oct with a field with of 20
out_bis << oct << setw(20) << l << endl;
// output l in dec with a field with of 20
out_bis << dec << setw(20) << l << endl;
// output the all buffer
cout << in_bis.rdbuf();
// seek the input sequence to pos
in_bis.seekg(pos);
int a,b,d;
// read the previous outputted integer
in_bis >> a >> b >> d;
// output 3 times 20
cout << a << endl << b << endl << d << endl;
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_stringbuf, basic_string,
basic_ostringstream, basic_stringstream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.7.2
STANDARDS CONFORMANC
ANSI X3J16/ISO WG21 Joint C++ Committee
istrstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
istrstream
SYNOPSIS
#include <strstream>
class istrstream
: public basic_istream<char>
DESCRIPTION
The class istrstream provides functionality to read characters from
an array in memory. It uses a private strstreambuf object to
control the associated array object. It inherits from
basic_istream<char> and therefore can use all the formatted
and unformatted input functions.
INTERFACE
class istrstream : public basic_istream<char> {
public:
typedef char_traits<char> traits;
typedef char char_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
explicit istrstream(const char *s);
istrstream(const char *s, streamsize n);
explicit istrstream(char *s);
istrstream(char *s, streamsize n);
virtual ~istrstream();
strstreambuf *rdbuf() const;
char *str();
};
TYPES
char_type
The type char_type is a synonym of type char.
int_type
The type int_type is a synonym of type traits::in_type.
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.
traits
The type traits is a synonym of type char_traits<char>.
CONSTRUCTORS
explicit istrstream(const char* s);
explicit istrstream(char* s);
Constructs an object of class istrstream, initializing the base
class basic_istream<char> with the associated strstreambuf
object. The strstreambuf object is initialized by calling
strstreambuf(s,0), where s shall designate the first element of
an NTBS.
explicit istrstream(const char* s, streamsize n);
explicit istrstream(char* s, streamsize n);
Constructs an object of class istrstream, initializing the base
class basic_istream<char> with the associated strstreambuf
object. The strstreambuf object is initialized by calling
strstreambuf(s,n), where s shall designate the first element of
an array whose length is n elements, and n shall be
greater than zero.
DESTRUCTORS
virtual ~istrstream();
Destroys an object of class istrstream.
MEMBER FUNCTIONS
char*
str();
Returns a pointer to the underlying array object which may
be null.
strstreambuf*
rdbuf() const;
Returns a pointer to the private strstreambuf object associated
with the stream.
EXAMPLES
//
// stdlib/examples/manual/istrstream.cpp
//
#include<iostream>
#include<strstream>
void main ( )
{
using namespace std;
const char* p="C'est pas l'homme qui prend la mer, ";
char* s="c'est la mer qui prend l'homme";
// create an istrstream object and initialize
// the underlying strstreambuf with p
istrstream in_first(p);
// create an istrstream object and initialize
// the underlying strstreambuf with s
istrstream in_next(s);
// create an ostrstream object
ostrstream out;
// output the content of in_first and
// in_next to out
out << in_first.rdbuf() << in_next.str();
// output the content of out to stdout
cout << endl << out.rdbuf() << endl;
// output the content of in_first to stdout
cout << endl << in_first.str();
// output the content of in_next to stdout
cout << endl << in_next.rdbuf() << endl;
}
SEE ALSO
char_traits, ios_base, basic_ios,
strstreambuf, ostrstream, strstream(3c++)
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Annex D
Compatibility features Section D.6.2
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
ofstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_ofstream,ofstream
This page describes the -ANSI basic_ofstream class. If you would
like information on the pre-ANSI ofstream class, use the command:
help cxxl
SYNOPSIS
#include <fstream>
template<class charT, class traits = char_traits<charT> >
class basic_ofstream
: public basic_ostream<charT, traits>
DESCRIPTION
The template class basic_ofstream<charT,traits> supports writing
into named files or other devices associated with a file
descriptor. It uses a basic_filebuf object to control the
associated sequences. It inherits from basic_ostream and
can therefore use all the formatted and unformatted output
functions.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_ofstream
: public basic_ostream<charT, traits> {
public:
typedef basic_ios<charT, traits> ios_type;
typedef charT char_type;
typedef traits traits_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
basic_ofstream();
explicit basic_ofstream(const char *s,
ios_base::openmode mode =
ios_base::out,
long protection = 0666);
explicit basic_ofstream(int fd);
basic_ofstream(int fd, char_type* buf, int len);
virtual ~basic_ofstream();
basic_filebuf<charT, traits> *rdbuf() const;
bool is_open();
void open(const char *s, ios_base::openmode mode =
ios_type::out, long protection = 0666);
void close();
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
off_type
The type off_type is a synonym of type traits::off_type.
ofstream
The type ofstream is an instantiation of class basic_ofstream on
type char:
typedef basic_ofstream<char> ofstream;
int_type
The type int_type is a synonym of type traits::in_type.
ios_type
The type ios_type is an instantiation of class basic_ios on type
charT.
pos_type
The type pos_type is a synonym of type traits::pos_type.
traits_type
The type traits_type is a synonym for the template parameter traits.
wofstream
The type wofstream is an instantiation of class basic_ofstream on
type wchar_t:
typedef basic_ofstream<wchar_t> wofstream;
CONSTRUCTORS
basic_ofstream();
Constructs an object of class basic_ofstream<charT,traits>,
initializing the base class basic_ostream with the associated
file buffer, which is initialized by calling the basic_filebuf
constructor basic_filebuf<charT,traits>(). After construction a
file can be attached to the basic_oftream object using the
open member function.
basic_ofstream(const char* s,
ios_base::openmode mode= ios_base::in,
long protection= 0666);
Constructs an object of class
basic_ofstream<charT,traits>, initializing the base class
basic_ostream with the associated file buffer, which is
initialized by calling the basic_filebuf constructor
basic_filebuf<charT,traits>(). The constructor then calls
the open function open(s,mode,protection) in order to
attach the file whose name is pointed at by s, to the
basic_oftream object. The third argument, protection, is
used as the file permissions. It does not appear in the
Standard C++ description and is provided as an extension.
It determines the file read/write/execute permissions
under UNIX. It is more limited under DOS since files are
always readable and do not have special execute permis-
sion.
explicit basic_ofstream(int fd);
Constructs an object of class basic_ofstream<charT,traits>,
initializing the base class basic_ostream with the
associated file buffer, which is initialized by calling the
basic_filebuf constructor basic_filebuf<charT,traits>(). The
constructor then calls the basic_filebuf open function
open(fd) in order to attach the file descriptor fd to the
basic_oftream object. This constructor is not described in
the C++ standard, and is provided as an extension in order
to manipulate pipes, sockets or other UNIX devices, that can be
accessed through file descriptors. If the function fails, it sets
ios_base::failbit.
basic_ofstream(int fd, char_type* buf,int len);
Constructs an object of class basic_ofstream<charT,traits>,
initializing the base class basic_ostream with the
associated file buffer, which is initialized by calling the
basic_filebuf constructor basic_filebuf<charT,traits>(). The
constructor then calls the basic_filebuf open function
open(fd) in order to attach the file descriptor fd to the
basic_oftream object. The underlying buffer is then
replaced by calling the basic_filebuf member function setbuf
with parameters buf and len. This constructor is not described
in the C++ standard, and is provided as an extension in order
to manipulate pipes, sockets or other UNIX devices, that can
be accessed through file descriptors. It also maintains
compatibility with the old iostreams library. If the function
fails, it sets ios_base::failbit.
DESTRUCTOR
virtual ~basic_ofstream();
Destroys an object of class basic_ofstream.
MEMBER FUNCTIONS
void
close();
Calls the associated basic_filebuf function close() and if this
function fails, it calls the basic_ios member function
setstate(failbit).
bool
is_open();
Calls the associated basic_filebuf function is_open() and return
its result.
void
open(const char* s,ios_base::openmode =
ios_base::out, long protection = 0666);
Calls the associated basic_filebuf function
open(s,mode,protection) and, if this function fails opening the
file, calls the basic_ios member function setstate(failbit). The
third argument, protection, is used as the file permis-
sions. It does not appear in the Standard C++ description and is
provided as an extension. It determines the file
read/write/execute permissions under UNIX, and is more limited
under DOS since files are always readable and do not have spe-
cial execute permission.
basic_filebuf<charT,traits>*
rdbuf() const;
Returns a pointer to the basic_filebuf associated with the stream.
EXAMPLES
See basic_fstream, basic_ifstream and basic_filebuf examples.
SEE ALSO
char_traits, ios_base, basic_ios,
basic_filebuf, basic_ifstream, basic_fstream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.8.1.8
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
ostream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_ostream
SYNOPSIS
#include <ostream>
template<class charT, class traits = char_traits<charT> >
class basic_ostream
: virtual public basic_ios<charT, traits>
DESCRIPTION
The class basic_ostream defines a number of member function
signatures that assist in formatting and writing output to sequences
controlled by a stream buffer.
Two groups of member function signatures share common properties:
the formatted output functions (or insertors) and the
unformatted output functions. Both groups of functions
insert characters by calling basic_streambuf member functions. They
both begin by constructing an object of class basic_ostream::sentry
and, if this object is in good state after construction,
the function tries to perform the requested output. The sen-
try object performs exception-safe initialization, such as
controlling the status of the stream or locking it in multithread
environment.
Some formatted output functions generate the requested output by
converting a value from some scalar to text form and inserting
the converted text in the output sequence. The conversion behavior
is locale dependent, and directly depend on the locale object
imbued in the stream.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_ostream
:virtual public basic_ios<charT, traits> {
public:
typedef basic_ostream<charT, traits> ostream_type;
typedef basic_ios<charT, traits> ios_type;
typedef traits traits_type;
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_ostream(basic_streambuf<charT, traits> *sb);
virtual ~basic_ostream();
class sentry {
public:
explicit sentry(basic_ostream<charT,traits>&);
~sentry();
operator bool ();
};
ostream_type& operator<<(ostream_type& (*pf)(ostream_type&));
ostream_type& operator<<(ios_base& (*pf)(ios_base&));
ostream_type& operator<<(ios_type& (*pf)(ios_type&));
ostream_type& operator<<(bool n);
ostream_type& operator<<(short n);
ostream_type& operator<<(unsigned short n);
ostream_type& operator<<(int n);
ostream_type& operator<<(unsigned int n);
ostream_type& operator<<(long n);
ostream_type& operator<<(unsigned long n);
ostream_type& operator<<(float f);
ostream_type& operator<<(double f);
ostream_type& operator<<(long double f);
ostream_type& operator<<(void *p);
ostream_type& operator<<(basic_streambuf<char_type, traits>& sb);
ostream_type& operator<<(basic_streambuf<char_type, traits> *sb);
ostream_type& put(char_type c);
ostream_type& write(const char_type *s, streamsize n);
ostream_type& flush();
ostream_type& seekp(pos_type );
ostream_type& seekp(off_type , ios_base::seekdir );
pos_type tellp();
protected:
basic_ostream();
};
//global functions
template <class charT, class traits>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>&, charT);
template <class charT, class traits>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>&, char);
template <class traits>
basic_ostream<char,traits>&
operator<<(basic_ostream<char,traits>&, char);
template <class charT, class traits>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>&, const charT*);
template <class charT, class traits>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>&, const char*);
template <class traits>
basic_ostream<char,traits>&
operator<<(basic_ostream<char,traits>&, const char*);
template <class traits>
basic_ostream<char,traits>&
operator<<(basic_ostream<char,traits>&, unsigned char);
template <class traits>
basic_ostream<char,traits>&
operator<<(basic_ostream<char,traits>&, signed char);
template <class traits>
basic_ostream<char,traits>&
operator<<(basic_ostream<char,traits>&, const unsigned char*);
template <class traits>
basic_ostream<char,traits>&
operator<<(basic_ostream<char,traits>&, const signed char*);
template<class charT, class traits>
basic_ostream<charT, traits>&
endl(basic_ostream<charT, traits>& os);
template<class charT, class traits>
basic_ostream<charT, traits>&
ends(basic_ostream<charT, traits>& os);
template<class charT, class traits>
basic_ostream<charT, traits>&
flush(basic_ostream<charT, traits>& os);
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
ios_type
The type ios_type is a synonym for basic_ios<charT, traits>.
off_type
The type off_type is a synonym of type traits::off_type.
ostream
The type ostream is an instantiation of class basic_ostream on type
char:
typedef basic_ostream<char> ostream;
ostream_type
The type ostream_type is a synonym for basic_ostream<charT, traits>.
pos_type
The type pos_type is a synonym of type traits::pos_type.
traits_type
The type traits_type is a synonym for the template parameter traits.
wostream
The type wostream is an instantiation of class basic_ostream on type
wchar_t:
typedef basic_ostream<wchar_t> wostream;
CONSTRUCTOR
explicit basic_ostream(basic_streambuf<charT, traits>* sb);
Constructs an object of class basic_ostream, assigning initial
values to the base class by calling
basic_ios<charT,traits>::init(sb).
DESTRUCTOR
virtual ~basic_ostream();
Destroys an object of class basic_ostream.
SENTRY CLASS
explicit sentry(basic_ostream<charT,traits>&);
Prepares for formatted or unformatted output. First if the
basic_ios member function tie() is not a null pointer, the
function synchronizes the output sequence with any associated
stream. If after any preparation is completed the
basic_ios member function good() is true, the sentry conversion
function operator bool () will return true. Otherwise it will
return false. In multithread environment the sentry object
constructor is responsible for locking the stream and the
stream buffer associated with the stream.
~sentry();
Destroys an object of class sentry. If the ios_base member
function flags() & unitbuf == true, then flush the buffer.
In multithread environment the sentry object destructor is
responsible for unlocking the stream and the stream buffer
associated with the stream.
operator bool();
If after any preparation is completed the ios_base member
function good() is true, the sentry conversion function
operator bool() will return true else it will return false.
INSERTORS
ostream_type&
operator<<(ostream_type& (*pf) (ostream_type&));
Calls pf(*this), then return *this. See, for example, the
function signature endl(basic_ostream&).
ostream_type&
operator<<(ios_type& (*pf) (ios_type&));
Calls pf(*this), then return *this.
ostream_type&
operator<<(ios_base& (*pf) (ios_base&));
Calls pf(*this), then return *this. See, for example, the
function signature dec(ios_base&).
ostream_type&
operator<<(bool n);
Converts the boolean value n, and outputs it into the
basic_ostream object's buffer. If the ios_base member function
flag() & ios_base::boolalpha is false it tries to write an
integer value, which must be 0 or 1. If the boolalpha flag is
true, it writes characters according to the locale function
numpunct<>::truename() or numpunct<>::falsename().
ostream_type&
operator<<(short n);
Converts the signed short integer n, and output it into the
stream buffer, then return *this.
ostream_type&
operator<<(unsigned short n);
Converts the unsigned short integer n, and output it into the
stream buffer, then return *this.
ostream_type&
operator<<(int n);
Converts the signed integer n, and output it into the stream
buffer, then return *this.
ostream_type&
operator<<(unsigned int n);
Converts the unsigned integer n, and output it into the stream
buffer, then return *this.
ostream_type&
operator<<(long n);
Converts the signed long integer n, and output it into the stream
buffer, then return *this.
ostream_type&
operator<<(unsigned long n);
Converts the unsigned long integer n, and output it into the
stream buffer, then return *this.
ostream_type&
operator<<(float f);
Converts the float f and output it into the stream buffer, then
return *this.
ostream_type&
operator<<(double f);
Converts the double f and output it into the stream buffer, then
return *this.
ostream_type&
operator<<(long double f);
Converts the long double f and output it into the stream buffer,
then return *this.
ostream_type&
operator<<(void *p);
Converts the pointer p, and output it into the stream buffer,
then return *this.
ostream_type&
operator<<(basic_streambuf<charT,traits> *sb);
If sb is null calls the basic_ios member function
setstate(badbit). Otherwise gets characters from sb and
inserts them into the stream buffer until any of the
following occurs:
+ end-of-file occurs on the input sequence.
+ inserting in the output sequence fails
+ an exception occurs while getting a character from sb
If the function inserts no characters or if it stopped because an
exception was thrown while extracting a character, it calls
the basic_ios member function setstate(failbit). If an
exception was thrown while extracting a character it is
rethrown.
ostream_type&
operator<<(basic_streambuf<charT,traits>& sb);
Gets characters from sb and inserts them into the stream buffer
until any of the following occurs:
+ end-of-file occurs on the input sequence.
+ inserting in the output sequence fails
+ an exception occurs while getting a character from sb
If the function inserts no characters or if it stopped because an
exception was thrown while extracting a character, it calls
the basic_ios member function setstate(failbit). If an
exception was thrown while extracting a character it is
rethrown.
UNFORMATTED FUNCTIONS
ostream_type&
flush();
If rdbuf() is not a null pointer, calls rdbuf()->pubsync() and
returns *this. If that function returns -1 calls
setstate(badbit).
ostream_type&
put(char_type c);
Inserts the character c. If the operation fails, calls the
basic_ios member function setstate(badbit).
ostream_type&
seekp(pos_type pos);
If the basic_ios member function fail() returns false, executes
rdbuf()->pubseekpos(pos), which will position the current pointer
of the output sequence at the position designated by pos.
ostream_type&
seekp(off_type off, ios_base::seekdir dir);
If the basic_ios member function fail() returns false, executes
rdbuf()->pubseekpos(off,dir), which will position the current
pointer of the output sequence at the position designated by
off and dir.
pos_type
tellp();
If the basic_ios member function fail() returns true, tellp()
returns pos_type(off_type(-1)) to indicate failure. Otherwise it
returns the current position of the output sequence by
calling rdbuf()-> pubseekoff(0,cur, out).
ostream_type&
write(const char_type* s, streamsize n);
Obtains characters to insert from successive locations of an
array whose first element is designated by s. Characters are
inserted until either of the following occurs:
+ n characters are inserted
+ inserting in the output sequence fails
In the second case the function calls the basic_ios member
function setstate(badbit). The function returns *this.
NON MEMBER FUNCTIONS
template<class charT, class traits>
basic_ostream<charT, traits>&
endl(basic_ostream<charT, traits>& os);
Outputs a newline character and flush the buffer, then returns
os.
template<class charT, class traits>
basic_ostream<charT, traits>&
ends(basic_ostream<charT, traits>& os);
Inserts a null character into the output sequence, then returns os.
template<class charT, class traits>
basic_ostream<charT, traits>&
flush(basic_ostream<charT, traits>& os);
Flushes the buffer, then returns os.
template<class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os, charT c);
Outputs the character c of type charT into the basic_ostream
object's buffer. Both the stream and the stream buffer are
instantiated on type charT. Padding is not ignored.
template<class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os, char c);
Outputs the character c of type char into the basic_ostream
object's buffer. Both the stream and the stream buffer are
instantiated on type charT. Conversion from characters of type
char to characters of type charT is performed by the
basic_ios member function widen. padding is not ignored.
template<class traits>
basic_ostream<char, traits>&
operator<<(basic_ostream<char, traits>& os, char c);
Outputs the character c of type char into the basic_ostream
object's buffer. Both the stream and the stream buffer are
instantiated on type char. Padding is not ignored.
template<class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os, const charT* s);
Outputs the null-terminated-byte-string s of type charT* into the
basic_ostream object's buffer. Both the stream and the stream
buffer are instantiated on type charT.
template<class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& os, const char* s);
Outputs the null-terminated-byte-string s of type char* into the
basic_ostream object's buffer. Both the stream and the stream
buffer are instantiated on type charT. Conversion from characters
of type char to characters of type charT is performed by the
basic_ios member function widen.
template<class traits>
basic_ostream<char, traits>&
operator<<(basic_ostream<char, traits>& os, const char* s);
Outputs the null-terminated-byte-string s of type char* into the
basic_ostream object's buffer. Both the stream and the stream
buffer are instantiated on type char.
template<class traits>
basic_ostream<char, traits>&
operator<<(basic_ostream<char, traits>& os, unsigned char c);
Returns os << (char)c.
template<class traits>
basic_ostream<char, traits>&
operator<<(basic_ostream<char, traits>& os, signed char c);
Returns os << (char)c.
template<class traits>
basic_ostream<char, traits>&
operator<<(basic_ostream<char, traits>& os, unsigned char* c);
Returns os << (char*)c.
template<class traits>
basic_ostream<char, traits>&
operator<<(basic_ostream<char, traits>& os, signed char* c);
Returns os << (char*)c.
FORMATTING
The formatting is done through member functions or manipulators.
Manipulators Member Functions
showpos setf(ios_base::showpos)
noshowpos unsetf(ios_base::showpos)
showbase setf(ios_base::showbase)
noshowbase unsetf(ios_base::showbase)
uppercase setf(ios_base::uppercase)
nouppercase unsetf(ios_base::uppercase)
showpoint setf(ios_base::showpoint)
noshowpoint unsetf(ios_base::showpoint)
boolalpha setf(ios_base::boolalpha)
noboolalpha unsetf(ios_base::boolalpha)
unitbuf setf(ios_base::unitbuf)
nounitbuf unsetf(ios_base::unitbuf)
internal setf(ios_base::internal,
ios_base::adjustfield)
left setf(ios_base::left,
ios_base::adjustfield)
right setf(ios_base::right,
ios_base::adjustfield)
dec setf(ios_base::dec,
ios_base::basefield)
hex setf(ios_base::hex,
ios_base::basefield)
oct setf(ios_base::oct,
ios_base::basefield)
fixed setf(ios_base::fixed,
ios_base::floatfield)
scientific setf(ios_base::scientific,
ios_base::floatfield)
resetiosflags
(ios_base::fmtflags flag) setf(0,flag)
setiosflags
(ios_base::fmtflags flag) setf(flag)
setbase(int base) See above
setfill(char_type c) fill(c)
setprecision(int n) precision(n)
setw(int n) width(n)
DESCRIPTION
showpos Generates a + sign in non-negative generated numeric output
showbase Generates a prefix indicating the numeric base of generated
integer output
uppercase Replaces certain lowercase letters with their uppercase
equivalents in generated output
showpoint Generates a decimal-point character unconditionally in
generated floating-point output
boolalpha Insert and extract bool type in alphabetic format
unitbuf Flushes output after each output operation
internal Adds fill characters at a designated internal point in
certain generated output, or identical to right if no such
point is designated
left Adds fill characters on the right (final positions) of certain
generated output
right Adds fill characters on the left (initial positions) of certain
generated output
dec Converts integer input or generates integer output in decimal
base
hex Converts integer input or generates integer output in hexadecimal
base
oct Converts integer input or generates integer output in octal base
fixed Generates floating-point output in fixed-point notation
scientific Generates floating-point output in scientific notation
resetiosflagss
(ios_base::fmtflags flag) Resets the fmtflags field flag
setiosflags
(ios_base::fmtflags flag) Set up the flag flag
setbase(int base) Converts integer input or generates integer output
in base base. The parameter base can be 8, 10
or 16.
setfill(char_type c) Set the character used to pad (fill) an output
conversion to the specified field width
setprecision(int n) Set the precision (number of digits after the
decimal point) to generate on certain output
conversions
setw(int n) Set the field with (number of characters) to generate on
certain output conversions
EXAMPLES
//
// stdlib/examples/manual/ostream1.cpp
//
#include<iostream>
#include<ostream>
#include<sstream>
#include<iomanip>
void main ( )
{
using namespace std;
float f= 3.14159;
int i= 22;
char* s= "Randy is the king of stdlib";
// create a read/write stringbuf object on tiny char
// and attach it to an istringstream object
istringstream in( ios_base::in | ios_base::out );
// tie the ostream object to the istringstream object
ostream out(in.rdbuf());
out << "test beginning !" << endl;
// output i in hexadecimal
out << hex << i <<endl;
// set the field width to 10
// set the padding character to '@'
// and output i in octal
out << setw(10) << oct << setfill('@') << i << endl;
// set the precision to 2 digits after the separator
// output f
out << setprecision(3) << f << endl;
// output the 17 first characters of s
out.write(s,17);
// output a newline character
out.put('0);
// output s
out << s << endl;
// output the all buffer to standard output
cout << in.rdbuf();
}
//
// stdlib/examples/manual/ostream2.cpp
//
#include<iostream>
#include<ostream>
#include<sstream>
void main ( )
{
using namespace std;
float f= 3.14159;
wchar_t* s= L"Kenavo !";
// create a read/write stringbuf object on wide char
// and attach it to an wistringstream object
wistringstream in( ios_base::in | ios_base::out );
// tie the wostream object to the wistringstream object
wostream out(in.rdbuf());
out << L"test beginning !" << endl;
// output f in scientific format
out << scientific << f <<endl;
// store the current put-pointer position
wostream::pos_type pos = out.tellp();
// output s
out << s << endl;
// output the all buffer to standard output
wcout << in.rdbuf() << endl;
// position the get-pointer
in.seekg(pos);
// output s
wcout << in.rdbuf() << endl;
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_streambuf, basic_iostream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.6.2.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
ostringstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_ostringstream
SYNOPSIS
#include <sstream>
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
class basic_ostringstream
: public basic_ostream<charT, traits>
DESCRIPTION
The template class basic_ostringstream<charT,traits,Allocator>
provides functionality to write to an array in memory. It
supports writing objects of class
basic_string<charT,traits,Allocator>. It uses a basic_stringbuf
object to control the associated storage. It inherits from
basic_ostream and therefore can use all the formatted and
unformatted output functions.
INTERFACE
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
class basic_ostringstream
: public basic_ostream<charT, traits> {
public:
typedef basic_stringbuf<charT, traits, Allocator> sb_type;
typedef basic_ios<charT, traits> ios_type;
typedef basic_string<charT, traits, Allocator> string_type;
typedef traits traits_type;
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_ostringstream(ios_base::openmode which =
ios_base::out);
explicit basic_ostringstream(const string_type& str,
ios_base::openmode which =
ios_base::out);
virtual ~basic_ostringstream();
basic_stringbuf<charT,traits,Allocator> *rdbuf() const;
string_type str() const;
void str(const string_type& str);
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
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.
ostringstream
The type ostringstream is an instantiation of class
basic_ostringstream on type char:
typedef basic_ostringstream<char> ostringstream;
pos_type
The type pos_type is a synonym of type traits::pos_type.
sb_type
The type sb_type is an instantiation of class basic_stringbuf
on type charT.
string_type
The type string_type is an instantiation of class basic_string
on type charT.
traits_type
The type traits_type is a synonym for the template parameter
traits.
wostringstream
The type wostringstream is an instantiation of class
basic_ostringstream on type wchar_t:
typedef basic_ostringstream<wchar_t> wostringstream;
CONSTRUCTORS
explicit basic_ostringstream(ios_base::openmode which =
ios_base::out);
Constructs an object of class
basic_ostringstream, initializing the base
class basic_ostream with the associated
string buffer. The string buffer is initial-
ized by calling the basic_stringbuf con-
structor
basic_stringbuf<charT,traits,Allocator>(which).
explicit basic_ostringstream(const string_type& str,
ios_base::openmode which =
ios_base::out);
Constructs an object of class
basic_ostringstream, initializing the base
class basic_ostream with the associated
string buffer. The string buffer is initial-
ized by calling the basic_stringbuf con-
structor
basic_stringbuf<charT,traits,Allocator>(str,which).
DESTRUCTOR
virtual ~basic_ostringstream();
Destroys an object of class basic_ostringstream.
MEMBER FUNCTIONS
basic_stringbuf<charT,traits,Allocator>*
rdbuf() const;
Returns a pointer to the basic_stringbuf associated with the
stream.
string_type
str() const;
Returns a string object of type string_type whose contents is a
copy of the underlying buffer contents.
void
str(const string_type& str);
Clears the underlying string buffer and copies the string object
str into it. If the opening mode is in, initialize the input
sequence to point at the first character of the buffer. If
the opening mode is out, initialize the output sequence to
point at the first character of the buffer. If the opening
mode is out | app, initialize the output sequence to
point at the last character of the buffer.
EXAMPLES
See basic_stringstream, basic_istringstream and basic_stringbuf
examples.
SEE ALSO
char_traits, ios_base, basic_ios,
basic_stringbuf, basic_string,
basic_istringstream, basic_stringstream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.7.2.3
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
ostrstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
ostrstream
SYNOPSIS
#include <strstream>
class ostrstream
: public basic_ostream<char>
DESCRIPTION
The class ostrstream provides functionality to write to an array in
memory. It uses a private strstreambuf object to control the
associated array object. It inherits from basic_ostream<char> and
therefore can use all the formatted and unformatted output
functions.
INTERFACE
class ostrstream
: public basic_ostream<char> {
public:
typedef char_traits<char> traits;
typedef char char_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
ostrstream();
ostrstream(char *s, int n,
ios_base::openmode = ios_base::out);
virtual ~ostrstream();
strstreambuf *rdbuf() const;
void freeze(int freezefl = 1);
char *str();
int pcount() const;
};
TYPES
char_type
The type char_type is a synonym of type char.
int_type
The type int_type is a synonym of type traits::in_type.
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.
traits
The type traits is a synonym of type char_traits<char>.
CONSTRUCTORS
ostrstream();
Constructs an object of class ostrstream, initializing the base
class basic_ostream<char> with the associated strstreambuf
object. The strstreambuf object is initialized by calling its
default constructor strstreambuf().
ostrstream(char* s,int n, ios_base::openmode
mode = ios_base::out);
Constructs an object of class ostrstream, initializing the base
class basic_ostream<char> with the associated strstreambuf
object. The strstreambuf object is initialized by calling one of
two constructors:
+ if mode & app == 0 calls strstreambuf(s,n,s)
+ Otherwise calls strstreambuf(s,n,s + ::strlen(s))
DESTRUCTOR
virtual ~ostrstream();
Destroys an object of class ostrstream.
MEMBER FUNCTIONS
void
freeze(bool freezefl = 1);
If the mode is dynamic, alters the freeze status of the dynamic
array object as follows:
+ If freezefl is false, the function sets the freeze status
to frozen.
+ Otherwise, it clears the freeze status.
int
pcount() const;
Returns the size of the output sequence.
strstreambuf*
rdbuf() const;
Returns a pointer to the private strstreambuf object associated
with the stream.
char*
str();
Returns a pointer to the underlying array object which may be null.
EXAMPLES
See strstream, istrstream and strstreambuf examples.
SEE ALSO
char_traits, ios_base, basic_ios,
strstreambuf, istrstream, strstream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Annex D
Compatibility features Section D.6.3
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
smanip
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
smanip, smanip_fill
SYNOPSIS
#include <iomanip>
template<class T> class smanip;
template<class T, class traits> class smanip_fill;
DESCRIPTION
The template classes smanip and smanip_fill are helper classes used
to implement parameterized manipulators. The class smanip is
used as the return type for manipulators that do not need to
carry information about the character type of the stream they are
applied to. This is the case for resetiosflags, setiosflags,
setbase, setprecision and setw. The class smanip_fill is used as
the return type for manipulators that do need to carry
information about the character type of the stream they are
applied to. This is the case for setfill.
INTERFACE
template<class T>
class smanip {
public:
smanip(ios_base& (*pf) (ios_base&, T), T manarg);
};
template<class T, class traits>
class smanip_fill {
public:
smanip_fill(basic_ios<T, traits>& (*pf) (basic_ios<T, traits>&,
T), T manarg);
};
// parameterized manipulators
smanip<ios_base::fmtflags> resetiosflag(ios_base::fmtflags mask);
smanip<ios_base::fmtflags> setiosflag(ios_base::fmtflags mask);
smanip<int> setbase(int base);
smanip<int> setprecision(int n);
smanip<int> setw(int n);
template <class charT>
smanip_fill<charT, char_traits<charT> > setfill(charT c);
// overloaded extractors
template <class charT, class traits, class T>
basic_istream<charT,traits>&
operator>>(basic_istream<charT,traits>& is, const smanip<T>& a);
template <class charT, class traits>
basic_istream<charT,traits>&
operator>>(basic_istream<charT,traits>& is,
const smanip_fill<charT,char_traits<charT> >& a);
// overloaded insertors
template <class charT, class traits, class T>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>& is, const smanip<T>& a);
template <class charT, class traits>
basic_ostream<charT,traits>&
operator>>(basic_ostream<charT,traits>& is,
const smanip_fill<charT,char_traits<charT> >& a);
CLASS SMANIP CONSTRUCTOR
smanip(ios_base& (*pf) (ios_base&, T), T manarg);
Constructs an object of class smanip that stores a function
pointer pf, that will be called with argument manarg, in order
to perform the manipulator task. The call to pf is performed in
the insertor or extractor overloaded on type smanip.
CLASS SMANIP_FILL CONSTRUCTOR
smanip_fill(basic_ios<T, traits>& (*pf) (basic_ios<T, traits>&,T), T
manarg);
Constructs an object of class smanip_fill that stores a function
pointer pf, that will be called with argument manarg, in order to
perform the manipulator task. The call to pf is performed in
the insertor or extractor overloaded on type smanip_fill.
MANIPULATORS
smanip<ios_base::fmtflags>
resetiosflag(ios_base::fmtflags mask);
Resets the ios_base::fmtflags designated by mask in the stream to
which it is applied.
smanip<int>
setbase(int base);
Sets the base for the output or input of integer values in the
stream to which it is applied. The valid values for mask are
8, 10, 16.
template <class charT>
smanip_fill<charT, char_traits<charT> >
setfill(charT c);
Sets the fill character in the stream it is applied to.
smanip<ios_base::fmtflags>
setiosflag(ios_base::fmtflags mask);
Sets the ios_base::fmtflags designated by mask in the stream it
is applied to.
smanip<int>
setprecision(int n);
Sets the precision for the output of floating point values in the
stream to which it is applied.
smanip<int>
setw(int n);
Set the field width in the stream to which it is applied.
EXTRACTORS
template <class charT, class traits, class T>
basic_istream<charT,traits>&
operator>>(basic_istream<charT,traits>& is, const smanip<T>& a);
Applies the function stored in the parameter of type smanip<T>,
on the stream is.
template <class charT, class traits>
basic_istream<charT,traits>&
operator>>(basic_istream<charT,traits>& is,
const smanip_fill<charT,char_traits<charT> >& a);
Applies the function stored in the parameter of type
smanip_fill<charT, char_traits<charT> >, on the stream is.
INSERTORS
template <class charT, class traits, class T>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>& os, const smanip<T>& a);
Applies the function stored in the parameter of type smanip<T>,
on the stream os.
template <class charT, class traits>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>& os,
const smanip_fill<charT,char_traits<charT> >& a);
Applies the function stored in the parameter of type
smanip_fill<charT, char_traits<charT> >, on the stream os.
SEE ALSO
ios_base, basic_ios, basic_istream,
basic_ostream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.6.3
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
smanip_fill
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
smanip, smanip_fill
SYNOPSIS
#include <iomanip>
template<class T> class smanip;
template<class T, class traits> class smanip_fill;
DESCRIPTION
The template classes smanip and smanip_fill are helper classes used
to implement parameterized manipulators. The class smanip is
used as the return type for manipulators that do not need to
carry information about the character type of the stream they are
applied to. This is the case for resetiosflags, setiosflags,
setbase, setprecision and setw. The class smanip_fill is used as
the return type for manipulators that do need to carry
information about the character type of the stream they are
applied to. This is the case for setfill.
INTERFACE
template<class T>
class smanip {
public:
smanip(ios_base& (*pf) (ios_base&, T), T manarg);
};
template<class T, class traits>
class smanip_fill {
public:
smanip_fill(basic_ios<T, traits>& (*pf) (basic_ios<T, traits>&,
T), T manarg);
};
// parameterized manipulators
smanip<ios_base::fmtflags> resetiosflag(ios_base::fmtflags mask);
smanip<ios_base::fmtflags> setiosflag(ios_base::fmtflags mask);
smanip<int> setbase(int base);
smanip<int> setprecision(int n);
smanip<int> setw(int n);
template <class charT>
smanip_fill<charT, char_traits<charT> > setfill(charT c);
// overloaded extractors
template <class charT, class traits, class T>
basic_istream<charT,traits>&
operator>>(basic_istream<charT,traits>& is, const smanip<T>& a);
template <class charT, class traits>
basic_istream<charT,traits>&
operator>>(basic_istream<charT,traits>& is,
const smanip_fill<charT,char_traits<charT> >& a);
// overloaded insertors
template <class charT, class traits, class T>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>& is, const smanip<T>& a);
template <class charT, class traits>
basic_ostream<charT,traits>&
operator>>(basic_ostream<charT,traits>& is,
const smanip_fill<charT,char_traits<charT> >& a);
CLASS SMANIP CONSTRUCTOR
smanip(ios_base& (*pf) (ios_base&, T), T manarg);
Constructs an object of class smanip that stores a function
pointer pf, that will be called with argument manarg, in order
to perform the manipulator task. The call to pf is performed in
the insertor or extractor overloaded on type smanip.
CLASS SMANIP_FILL CONSTRUCTOR
smanip_fill(basic_ios<T, traits>& (*pf) (basic_ios<T, traits>&,T), T
manarg);
Constructs an object of class smanip_fill that stores a function
pointer pf, that will be called with argument manarg, in order to
perform the manipulator task. The call to pf is performed in
the insertor or extractor overloaded on type smanip_fill.
MANIPULATORS
smanip<ios_base::fmtflags>
resetiosflag(ios_base::fmtflags mask);
Resets the ios_base::fmtflags designated by mask in the stream to
which it is applied.
smanip<int>
setbase(int base);
Sets the base for the output or input of integer values in the
stream to which it is applied. The valid values for mask are
8, 10, 16.
template <class charT>
smanip_fill<charT, char_traits<charT> >
setfill(charT c);
Sets the fill character in the stream it is applied to.
smanip<ios_base::fmtflags>
setiosflag(ios_base::fmtflags mask);
Sets the ios_base::fmtflags designated by mask in the stream it
is applied to.
smanip<int>
setprecision(int n);
Sets the precision for the output of floating point values in the
stream to which it is applied.
smanip<int>
setw(int n);
Set the field width in the stream to which it is applied.
EXTRACTORS
template <class charT, class traits, class T>
basic_istream<charT,traits>&
operator>>(basic_istream<charT,traits>& is, const smanip<T>& a);
Applies the function stored in the parameter of type smanip<T>,
on the stream is.
template <class charT, class traits>
basic_istream<charT,traits>&
operator>>(basic_istream<charT,traits>& is,
const smanip_fill<charT,char_traits<charT> >& a);
Applies the function stored in the parameter of type
smanip_fill<charT, char_traits<charT> >, on the stream is.
INSERTORS
template <class charT, class traits, class T>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>& os, const smanip<T>& a);
Applies the function stored in the parameter of type smanip<T>,
on the stream os.
template <class charT, class traits>
basic_ostream<charT,traits>&
operator<<(basic_ostream<charT,traits>& os,
const smanip_fill<charT,char_traits<charT> >& a);
Applies the function stored in the parameter of type
smanip_fill<charT, char_traits<charT> >, on the stream os.
SEE ALSO
ios_base, basic_ios, basic_istream,
basic_ostream
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.6.3
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
streambuf
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_streambuf,streambuf
This page describes the ANSI streambuf class. If you would like
information on the pre-ANSI streambuf class, use the
command:
help cxxl
SYNOPSIS
#include <streambuf>
template<class charT, class traits = char_traits<charT> >
class basic_streambuf;
DESCRIPTION
The class template basic_streambuf<charT,traits> serves as an
abstract base class for deriving various stream buffers whose
objects each control two character sequences:
+ A character input sequence;
+ A character output sequence.
Each sequence is characterized by three pointers which, if non-null,
all point into the same charT array object. The array object
represents, at any moment, a subsequence of characters from the
sequence. Operations performed on a sequence alter the values
stored in these pointers, perform reads and writes directly
to or from associated sequences, and alter "the stream position" and
conversion state as needed to maintain this subsequence rela-
tionship. The three pointers are:
+ The beginning pointer, or lowest element address in the array;
+ The next pointer, or next element address that is a current
candidate for reading or writing;
+ The end pointer, or first element address beyond the end of the
array.
Stream buffers can impose various constraints on the sequences they
control, including:
+ The controlled input sequence may be unreadable;
+ The controlled output sequence may be unwritable;
+ The controlled sequences can be associated with the contents of
other representations for character sequences, such as external
files;
+ The controlled sequences can impose limitations on how the
program can read characters from a sequence, write characters to
a sequence, put characters back into an input sequence, or alter
the stream position.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_streambuf {
public:
typedef charT char_type;
typedef traits traits_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
virtual ~basic_streambuf();
locale pubimbue( const locale& loc);
locale getloc() const;
basic_streambuf<char_type, traits> *
pubsetbuf(char_type *s, streamsize n);
pos_type pubseekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
pos_type pubseekpos(pos_type sp, ios_base::openmode which =
ios_base::in | ios_base::out);
int pubsync();
ios_base::openmode which_open_mode();
streamsize in_avail();
int_type snextc();
int_type sbumpc();
int_type sgetc();
streamsize sgetn(char_type *s, streamsize n);
int_type sputbackc(char_type c);
int sungetc();
int_type sputc(char_type c);
streamsize sputn(const char_type *s, streamsize n);
protected:
basic_streambuf();
char_type *eback() const;
char_type *gptr() const;
char_type *egptr() const;
void gbump(int n);
void setg(char_type *gbeg_arg,char_type *gnext_arg,
char_type *gend_arg);
char_type *pbase() const;
char_type *pptr() const;
char_type *epptr() const;
void pbump(int n);
void setp(char_type *pbeg_arg,char_type *pend_arg);
virtual void imbue( const locale& loc);
virtual int_type overflow(int_type c = traits::eof());
virtual int_type pbackfail(int_type c = traits::eof());
virtual int showmanyc();
virtual int_type underflow();
virtual int_type uflow();
virtual streamsize xsgetn(char_type *s, streamsize n);
virtual streamsize xsputn(const 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 basic_streambuf<charT, traits>*
setbuf(char_type *s, streamsize n);
virtual int sync();
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
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.
streambuf
The type streambuf is an instantiation of class basic_streambuf
on type char:
typedef basic_streambuf<char> streambuf;
traits_type
The type traits_type is a synonym for the template parameter traits.
wstreambuf
The type wstreambuf is an instantiation of class basic_streambuf on
type wchar_t:
typedef basic_streambuf<wchar_t> wstreambuf;
PUBLIC CONSTRUCTOR
basic_streambuf();
Constructs an object of class basic_streambuf and initializes all
its pointer member objects to null pointers and the getloc()
member function to return the value of locale::locale().
PUBLIC DESTRUCTOR
virtual ~basic_streambuf();
Destroys an object of class basic_streambuf.
PUBLIC MEMBER FUNCTIONS
locale
getloc() const;
If pubimbue() has ever been called, returns the last value of loc
supplied, otherwise, the default locale locale::locale() in
effect at the time of construction.
streamsize
in_avail();
If a read position is available, returns the number of available
character in the input sequence. Otherwise calls the protected
function showmanyc().
locale
pubimbue(const locale& loc);
Calls the protected function imbue(loc).
pos_type
pubseekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out );
Calls the protected function seekoff(off,way,which).
pos_type
pubseekpos(pos_type sp, ios_base::openmode which=
ios_base::in | ios_base::out );
Calls the protected function seekpos(sp,which).
basic_streambuf<char_type,traits>*
pubsetbuf(char_type* s,streamsize n);
Calls the protected function setbuf(s,n) .
int
pubsync();
Calls the protected function sync().
int_type
sbumpc();
If the input sequence read position is not available, calls the
function uflow(), otherwise returns *gptr() and increments
the next pointer for the input sequence.
int_type
sgetc();
If the input sequence read position is not available, calls the
protected function underflow(), otherwise returns *gptr() .
streamsize
sgetn(char_type* s, streamsize n);
Calls the protected function xsgetn(s,n).
int_type
snextc();
Calls the function sbumpc() and if it returns traits::eof(),
returns traits::eof(); otherwise calls the function sgetc() .
int_type
sputbackc(char_type c);
If the input sequence putback position is not available, or if
traits::eq(c,gptr() [-1]) returns false, calls the protected
function pbackfail(c), otherwise decrements the next
pointer for the input sequence and returns *gptr().
int_type
sputc(char_type c);
If the output sequence write position is not available, calls the
protected function overflow(traits::to_int_type( c )).
Otherwise, stores c at the next pointer for the output
sequence, increments the pointer, and returns *pptr() .
streamsize
sputn(const char_type* s, streamsize n);
Calls the protected function xsputn(s,n).
int_type
sungetc();
If the input sequence putback position is not available, calls
the protected function pbackfail(). Otherwise decrements
the next pointer for the input sequence and returns *gptr().
ios_base::openmode
which_open_mode();
Returns the mode in which the stream buffer is opened. This
function is not described in the C++ standard.
PROTECTED MEMBER FUNCTIONS
char_type*
eback() const;
Returns the beginning pointer for the input sequence.
char_type*
egptr() const;
Returns the end pointer for the input sequence.
char_type*
epptr() const;
Returns the end pointer for the output sequence.
void
gbump(int n);
Advances the next pointer for the input sequence by n.
char_type*
gptr() const;
Returns the next pointer for the input sequence.
void
imbue(const locale&);
Changes any translations based on locale. The default behavior is
to do nothing, this function has to be overloaded in the
classes derived from basic_streambuf. The purpose of this
function is to allow the derived class to be informed of changes
in locale at the time they occur. The new imbued locale object
is only used by the stream buffer, it does not affect the stream
itself.
int_type
overflow(int_type c = traits::eof() );
The member functions sputc() and sputn() call this function in
case that not enough room can be found in the put buffer to
accommodate the argument character sequence. The function
returns traits::eof() if it fails to make more room
available, or to empty the buffer by writing the characters
to their output device.
int_type
pbackfail(int_type c = traits::eof() );
If c is equal to traits::eof(), gptr() is moved back one position
otherwise c is prepended. The function returns traits::eof() to
indicate failure.
char_type*
pbase() const;
Returns the beginning pointer for the output sequence.
void
pbump(int n);
Advances the next pointer for the output sequence by n.
char_type*
pptr() const;
Returns the next pointer for the output sequence.
pos_type
seekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out );
Alters the stream positions within one or more of the
controlled sequences in a way that is defined separately for each
class derived from basic_streambuf. The default behavior is to
return an object of type pos_type that stores an invalid stream
position.
pos_type
seekpos(pos_type sp, ios_base::openmode which=
ios_base::in | ios_base::out );
Alters the stream positions within one or more of the
controlled sequences in a way that is defined separately for each
class derived from basic_streambuf. The default behavior is to
return an object of class pos_type that stores an invalid stream
position.
basic_streambuf*
setbuf(char_type* s, streamsize n);
Performs an operation that is defined separately for each class
derived from basic_streambuf. The purpose of this function is to
allow the user to provide his own buffer, or to resize the
current buffer.
void
setg(char_type* gbeg, char_type* gnext, char_type* gend);
Sets up private member for the following to be true:
eback() == gbeg, gptr() == gnext and egptr() == gend
void
setp(char_type* pbeg, char_type* pend);
Sets up private member for the following to be true:
pbase() == pbeg, pptr() == pbeg and epptr() == pend
int
showmanyc();
Returns the number of characters available in the internal
buffer, or -1.
int
sync();
Synchronizes the controlled sequences with the internal buffer,
in a way that is defined separately for each class derived
from basic_streambuf. The default behavior is to do nothing. On
failure the return value is -1.
int_type
underflow();
The public members of basic_streambuf call this function only if
gptr() is null or gptr() >= egptr(). This function returns the
character pointed at by gptr() if gptr() is not null and if
gptr() < egptr(). Otherwise the function try to read
character into the buffer, and if it fails return traits::eof().
int_type
uflow();
Calls underflow() and if underflow() returns traits::eof(),
returns traits::eof(). Otherwise, does gbump(1) and returns the
value of *gptr().
streamsize
xsgetn(char_type* s, streamsize n);
Assigns up to n characters to successive elements of the array
whose first element is designated by s. The characters are read
from the input sequence. Assigning stops when either n
characters have been assigned or a call to sbumpc() would
return traits::eof(). The function returns the number of
characters read.
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. Writing stops when either n
characters have been written or a call to sputc() would return
traits::eof(). The function returns the number of characters
written.
SEE ALSO
char_traits, basic_filebuf, basic_stringbuf,
strstreambuf
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.5
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
stringbuf
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_stringbuf
SYNOPSIS
#include <sstream>
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
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
character sequences:
+ A character input sequence;
+ A character output sequence.
Note: see basic_streambuf.
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 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<void> >
class basic_stringbuf
: public basic_streambuf<charT, traits> {
public:
typedef basic_ios<charT, traits> ios_type;
typedef basic_string<charT, traits,
Allocator> string_type;
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 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 overflow(int_type c = traits::eof());
virtual int_type pbackfail(int_type c = traits::eof());
virtual int_type underflow();
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 parameter 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 parameter 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, initializing
the base class with basic_streambuf(), and initializing 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, initializing
the base class with basic_streambuf(), and initializing the
open mode with which. The string object str is copied to
the underlying buffer. If the opening mode is in, initialize the
input sequence to point at the first character of the buffer. If
the opening mode is out, it initializes the output sequence to
point at the first character of the buffer. If the opening
mode is out | app, it initializes the output sequence to
point at the last character of the buffer.
DESTRUCTOR
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 functions 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 parameters off (displacement)
and way (reference point). 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.
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);
If the string buffer object is opened in output mode, proceed as
follows:
if s is not a null pointer and n is greater than the content of
the current buffer, replace it (copy its contents) by the
buffer of size n pointed at by s. In the case where s is a
null pointer and n is greater than the content of the current
buffer, resize it to size n. If the function fails, it
returns a null pointer.
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 at the first character of the buffer. If
the opening mode is out, the function initializes the output
sequence to point at the first character of the buffer. If
the opening mode is out | app, it initializes the output
sequence to point at the last character 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.
EXAMPLES
//
// 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 at by in_2 to the one
// pointed at 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, ios_base, basic_ios,
basic_streambuf, basic_string,
basic_istringstream, basic_ostringstream,
basic_stringstream
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
stringstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_stringstream
SYNOPSIS
#include <sstream>
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
class basic_stringstream
: public basic_iostream<charT, traits>
DESCRIPTION
The template class basic_stringstream<charT,traits,Allocator>
provides functionality to read and write to an array in
memory. It supports writing and reading objects of class
basic_string<charT,traits,Alocator>. It uses a basic_stringbuf
object to control the associated storage. It inherits from
basic_iostream and therefore can use all the formatted and
unformatted output and input functions.
INTERFACE
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<void> >
class basic_stringstream
: public basic_iostream<charT, traits> {
public:
typedef basic_stringbuf<charT, traits, Allocator> sb_type;
typedef basic_ios<charT, traits> ios_type;
typedef basic_string<charT, traits, Allocator> string_type;
typedef traits traits_type;
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_stringstream(ios_base::openmode which =
ios_base::out | ios_base::in);
explicit basic_stringstream(const string_type& str,
ios_base::openmode which =
ios_base::out | ios_base::in);
virtual ~basic_stringstream();
basic_stringbuf<charT,traits,Allocator> *rdbuf() const;
string_type str() const;
void str(const string_type& str);
};
TYPES
char_type
The type char_type is a synonym for the template parameter charT.
int_type
The type int_type is a synonym of type traits::in_type.
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.
sb_type
The type sb_type is an instantiation of class basic_stringbuf on
type charT.
string_type
The type string_type is an instantiation of class basic_string on
type charT.
stringstream
The type stringstream is an instantiation of class basic_stringstream
on type char:
typedef basic_stringstream<char> stringstream;
traits_type
The type traits_type is a synonym for the template parameter traits.
wstringstream
The type wstringstream is an instantiation of class
basic_stringstream on type wchar_t:
typedef basic_stringstream<wchar_t> wstringstream;
CONSTRUCTORS
explicit basic_stringstream(ios_base::openmode which =
ios_base::in | ios_base::out);
Constructs an object of class basic_stringstream, initializing
the base class basic_iostream with the associated string
buffer. The string buffer is initialized by calling the
basic_stringbuf constructor
basic_stringbuf<charT,traits,Allocator>(which).
explicit basic_stringstream(const string_type& str,
ios_base::openmode which =
ios_base::in | ios_base::out);
Constructs an object of class basic_stringstream, initializing
the base class basic_iostream with the associated string
buffer. The string buffer is initialized by calling the
basic_stringbuf constructor
basic_stringbuf<charT,traits,Allocator>(str,which).
DESTRUCTOR
virtual ~basic_stringstream();
Destroys an object of class basic_stringstream.
MEMBER FUNCTIONS
basic_stringbuf<charT,traits,Allocator>*
rdbuf() const;
Returns a pointer to the basic_stringbuf associated with the stream.
string_type
str() const;
Returns a string object of type string_type whose contents is a
copy of the underlying buffer contents.
void
str(const string_type& str);
Clears the string buffer and copies the string object str into
it. If the opening mode is in, initializes the input
sequence to point at the first character of the buffer. If
the opening mode is out, initializes the output sequence to
point at the first character of the buffer. If the opening mode
is out | app, initializes the output sequence to point at the
last character of the buffer.
EXAMPLES
//
// stdlib/examples/manual/stringstream.cpp
//
#include<iostream>
#include<sstream>
void main ( )
{
using namespace std;
// create a bi-directional wstringstream object
wstringstream inout;
// output characters
inout << L"Das ist die rede von einem man" << endl;
inout << L"C'est l'histoire d'un home" << endl;
inout << L"This is the story of a man" << endl;
wchar_t p[100];
// extract the first line
inout.getline(p,100);
// output the first line to stdout
wcout << endl << L"Deutch :" << endl;
wcout << p;
// extract the seconf line
inout.getline(p,100);
// output the second line to stdout
wcout << endl << L"Francais :" << endl;
wcout << p;
// extract the third line
inout.getline(p,100);
// output the third line to stdout
wcout << endl << L"English :" << endl;
wcout << p;
// output the all content of the
//wstringstream object to stdout
wcout << endl << endl << inout.str();
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_stringbuf, basic_string,
basic_istringstream, basic_ostringstream(3c++)
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.7.3
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
strstream
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
strstream
This page describes the ANSI strstream class. If you would like
information on the pre-ANSI strstream class, use the
command:
help cxxl
SYNOPSIS
#include <strstream>
class strstream
: public basic_iostream<char>
DESCRIPTION
The class strstream provides functionality to read and write to an
array in memory. It uses a private strstreambuf object to
control the associated array. It inherits from basic_iostream<char>
and therefore can use all the formatted and unformatted output and
input functions.
INTERFACE
class strstream
: public basic_iostream<char> {
public:
typedef char_traits<char> traits;
typedef char char_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
strstream();
strstream(char *s, int n,
ios_base::openmode = ios_base::out | ios_base::in);
void freeze(int freezefl = 1);
int pcount() const;
virtual ~strstream();
strstreambuf *rdbuf() const;
char *str();
};
TYPES
char_type
The type char_type is a synonym of type char.
int_type
The type int_type is a synonym of type traits::in_type.
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.
traits
The type traits is a synonym of type char_traits<char>.
CONSTRUCTORS
strstream();
Constructs an object of class strstream, initializing the base
class basic_iostream<char> with the associated strstreambuf
object. The strstreambuf object is initialized by calling its
default constructor strstreambuf().
strstream(char* s,int n, ios_base::openmode
mode = ios_base::out | ios_base::in);
Constructs an object of class strstream, initializing the base
class basic_iostream<char> with the associated strstreambuf
object. The strstreambuf object is initialized by calling one of
two constructors:
+ if mode & app == 0 calls strstreambuf(s,n,s)
+ Otherwise calls strstreambuf(s,n,s + ::strlen(s))
DESTRUCTORS
virtual ~strstream();
Destroys an object of class strstream.
MEMBER FUNCTIONS
void
freeze(int freezefl = 1);
If the mode is dynamic, alters the freeze status of the dynamic
array object as follows:
+ If freezefl is false, the function sets the freeze status to
frozen.
+ Otherwise, it clears the freeze status.
int
pcount() const;
Returns the size of the output sequence.
strstreambuf*
rdbuf() const;
Returns a pointer to the strstreambuf object associated with the
stream.
char*
str();
Returns a pointer to the underlying array object which may be null.
EXAMPLES
//
// stdlib/examples/manual/strstream.cpp
//
#include<strstream>
void main ( )
{
using namespace std;
// create a bi-directional strstream object
strstream inout;
// output characters
inout << "Das ist die rede von einem man" << endl;
inout << "C'est l'histoire d'un home" << endl;
inout << "This is the story of a man" << endl;
char p[100];
// extract the first line
inout.getline(p,100);
// output the first line to stdout
cout << endl << "Deutch :" << endl;
cout << p;
// extract the seconf line
inout.getline(p,100);
// output the second line to stdout
cout << endl << "Francais :" << endl;
cout << p;
// extract the third line
inout.getline(p,100);
// output the third line to stdout
cout << endl << "English :" << endl;
cout << p;
// output the all content of the
// strstream object to stdout
cout << endl << endl << inout.str();
}
SEE ALSO
char_traits, ios_base, basic_ios,
strstreambuf, istrstream, ostrstream(3c++)
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Annex D
Compatibility features Section D.6.4
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
strstreambuf
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
strstreambuf
This page describes the ANSI strstreambuf class. If you would like
information on the pre-ANSI strstreambuf class, use the command:
help cxxl
SYNOPSIS
#include <strstream>
class strstreambuf
: public basic_streambuf<char>
DESCRIPTION
The class strstreambuf is derived from basic_streambuf specialized
on type char to associate possibly the input sequence and
possibly the output sequence with a tiny character array, whose
elements store arbitrary values.
Each object of type strstreambuf controls two character sequences:
+ A character input sequence;
+ A character output sequence.
Note: see basic_streambuf.
The two sequences are related to each other, but are manipulated
separately. This means that you can read and write characters at
different positions in objects of type strstreambuf without any
conflict (in opposition to the basic_filebuf objects).
The underlying array has several attributes:
+ allocated, set when a dynamic array has been allocated, and
hence should be freed by the destructor of the strstreambuf
object.
+ constant, set when the array has const elements, so the output
sequence cannot be written.
+ dynamic, set when the array object is allocated
(or reallocated) as necessary to hold a character sequence that
can change in length.
+ frozen, set when the program has requested that the array will
not be altered, reallocated, or freed.
INTERFACE
class strstreambuf
: public basic_streambuf<char> {
public:
typedef char_traits<char> traits;
typedef basic_ios<char, traits> ios_type;
typedef char char_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
explicit strstreambuf(streamsize alsize = 0);
strstreambuf(void *(*palloc)(size_t), void (*pfree)(void *));
strstreambuf(char *gnext, streamsize n, char *pbeg = 0);
strstreambuf(unsigned char *gnext, streamsize n,
unsigned char *pbeg = 0);
strstreambuf(signed char *gnext, streamsize n,
signed char *pbeg = 0);
strstreambuf(const char *gnext, streamsize n);
strstreambuf(const unsigned char *gnext, streamsize n);
strstreambuf(const signed char *gnext, streamsize n);
virtual ~strstreambuf();
void freeze(bool f = 1);
char *str();
int pcount() const;
protected:
virtual int_type overflow(int_type c = traits::eof());
virtual int_type pbackfail(int_type c = traits::eof());
virtual int_type underflow();
virtual pos_type seekoff(off_type, ios_type::seekdir way,
ios_type::openmode which =
ios_type::in | ios_type::out);
virtual pos_type seekpos(pos_type sp, ios_type::openmode which =
ios_type::in | ios_type::out);
virtual streambuf* setbuf(char *s, streamsize n);
virtual streamsize xsputn(const char_type* s, streamsize n);
};
TYPES
char_type
The type char_type is a synonym of type char.
int_type
The type int_type is a synonym of type traits::in_type.
ios_type
The type ios_type is an instantiation of class basic_ios on type char.
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.
traits
The type traits is a synonym of type char_traits<char>.
CONSTRUCTORS
explicit strstreambuf(streamsize alsize = 0);
Constructs an object of class strstreambuf, initializing the base
class with streambuf(). After initialization the strstreambuf
object is in dynamic mode and its array object has a size of
alsize.
strstreambuf(void* (*palloc)(size_t),
void (*pfree)(void*));
Constructs an object of class strstreambuf, initializing the base
class with streambuf(). After initialization the strstreambuf
object is in dynamic mode. The function used to allocate memory
is pointed at by void* (*palloc)(size_t) and the one used to
free memory is pointed at by void (*pfree)(void*).
strstreambuf(char* gnext, streamsize n,
char* pbeg = 0);
strstreambuf(signed char* gnext, streamsize n,
signed char* pbeg = 0);
strstreambuf(unsigned char* gnext, streamsize n,
unsigned char* pbeg = 0);
Constructs an object of class strstreambuf, initializing the base
class with streambuf(). The argument gnext point to the first
element of an array object whose number of elements is:
n, if n > 0
::strlen(gnext), if n == 0
INT_MAX, if n < 0
If pbeg is a null pointer set only the input sequence
to gnext, otherwise set also the output sequence to
pbeg.
strstreambuf(const char* gnext, streamsize n);
strstreambuf(const signed char* gnext, streamsize n);
strstreambuf(const unsigned char* gnext, streamsize n);
Constructs an object of class strstreambuf, initializing the base
class with streambuf(). The argument gnext point to the first
element of an array object whose number of elements is:
n, if n > 0
::strlen(gnext), if n == 0
INT_MAX, if n < 0
Set the input sequence to gnext and the mode to constant.
DESTRUCTORS
virtual ~strstreambuf();
Destroys an object of class strstreambuf. The function frees the
dynamically allocated array object only if allocated is set and
frozen is not set.
MEMBER FUNCTIONS
void
freeze(bool freezefl = 1);
If the mode is dynamic, alters the freeze status of the dynamic
array as follows:
+ If freezefl is false, the function sets the freeze status
to frozen.
+ Otherwise, it clears the freeze status.
int_type
overflow( int_type c = traits::eof() );
If the output sequence has a put position available, and c is not
traits::eof(), then write c into it. If there is no position
available, the function grow the size of the array object by
allocating more memory and then write c at the new current put
position. If dynamic is not set or if frozen is set the operation
fails. The function returns traits::not_eof(c), except if it
fails, in which case it returns traits::eof().
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, move
the input sequence one position backward. If the operation
fails, the function returns traits::eof(). Otherwise it returns
traits::not_eof(c).
int
pcount() const;
Returns the size of the output sequence.
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, alters the stream position
of both the input and the output sequence. If the open
mode is in, alters the stream position of only the
input sequence, and if it is out, alters the stream
position of only the output sequence. The new position is
calculated by combining the two parameters off (dis-
placement) and way (reference point). 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.
pos_type
seekpos(pos_type sp,ios_base::openmode which =
ios_base::in | ios_base::out);
If the open mode is in | out, alters the stream position
of both the input and the output sequence. If the open
mode is in, alters the stream position of only the
input sequence, and if it is out, alters the stream
position of only the output sequence. 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.
strstreambuf*
setbuf(char* s, streamsize n);
If dynamic is set and freeze is not, proceed as follows:
If s is not a null pointer and n is greater than the number of
characters already in the current array, replaces it (copy its
contents) by the array of size n pointed at by s.
char*
str();
Calls freeze(), then returns the beginning pointer for the input
sequence.
int_type
underflow();
If the input sequence has a read position available, returns the
content of this position. Otherwise 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.
In the case where s is a null pointer and n is greater than the
number of characters already in the current array, resize it to
size n.
If the function fails, it returns a null pointer.
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.
EXAMPLES
//
// stdlib/examples/manual/strstreambuf.cpp
//
#include<iostream>
#include<strstream>
#include<iomanip>
void main ( )
{
using namespace std;
// create a read/write strstream object
// and attach it to an ostrstream object
ostrstream out;
// tie the istream object to the ostrstream object
istream in(out.rdbuf());
// output to out
out << "anticonstitutionellement is a big word !!!";
// create a NTBS
char *p ="Le rat des villes et le rat des champs";
// output the NTBS
out << p << endl;
// resize the buffer
if ( out.rdbuf()->pubsetbuf(0,5000) )
cout << endl << "Success in allocating the buffer" << endl;
// output the all buffer to stdout
cout << in.rdbuf( );
// output the decimal conversion of 100 in hex
// with right padding and a width field of 200
out << dec << setfill('!') << setw(200) << 0x100 << endl;
// output the content of the input sequence to stdout
cout << in.rdbuf( ) << endl;
// number of elements in the output sequence
cout << out.rdbuf()->pcount() << endl;
// resize the buffer to a minimum size
if ( out.rdbuf()->pubsetbuf(0,out.rdbuf()->pcount()) )
cout << endl << "Success in resizing the buffer" << endl;
// output the content of the all array object
cout << out.rdbuf()->str() << endl;
}
SEE ALSO
char_traits, ios_base, basic_ios,
basic_streambuf, istrstream(3c++), ostrstream,
strstream(3c++)
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Annex D
Compatibility features Section D.5
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
wcerr
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
wcerr
SYNOPSIS
#include <iostream>
extern wostream wcerr;
DESCRIPTION
wostream wcerr;
The object wcerr controls output to an unbuffered stream buffer
associated with the object stderr declared in <cstdio>. By
default the standard C and C++ streams are synchronized,
but you can improve performance by using the ios_base member
function synch_with_stdio to desynchronize them.
wcerr uses the locale codecvt facet to convert the wide
characters it receives to the tiny characters it outputs to
stderr.
FORMATTING
The formatting is done through member functions or manipulators. See
cout, wcout or basic_ostream for details.
EXAMPLES
//
// wcerr example
//
#include<iostream>
#include<fstream>
void main ( )
{
using namespace std;
// open the file "file_name.txt"
// for reading
wifstream in("file_name.txt");
// output the all file to stdout
if ( in )
wcout << in.rdbuf();
else
// if the wifstream object is in a bad state
// output an error message to stderr
wcerr << L"Error while opening the file" << endl;
}
SEE ALSO
basic_ostream, iostream, basic_filebuf,
cout, cin, cerr, clog, wcin,
wcout, wclog, iomanip, ios_base,
basic_ios
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.3.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
wcin
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
wcin
SYNOPSIS
#include <iostream>
extern wistream wcin;
DESCRIPTION
wistream wcin;
The object wcin controls input from a stream buffer associated
with the object stdin declared in <cstdio>. By default the
standard C and C++ streams are synchronized, but performance
improvement can be achieved by using the ios_base member
function synch_with_stdio to desynchronize them.
After the object wcin is initialized, wcin.tie() returns &wcout,
which implies that wcin and wcout are synchronized. wcin uses
the locale codecvt facet to convert the tiny characters extracted
from stdin to the wide characters stored in the wcin
buffer.
EXAMPLES
//
// wcin example one
//
#include <iostream>
void main ( )
{
using namespace std;
int i;
float f;
wchar_t c;
//read an integer, a float and a wide character from stdin
wcin >> i >> f >> c;
// output i, f and c to stdout
wcout << i << endl << f << endl << c << endl;
}
//
// wcin example two
//
#include <iostream>
void main ( )
{
using namespace std;
wchar_t p[50];
// remove all the white spaces
wcin >> ws;
// read characters from stdin until a newline
// or 49 characters have been read
wcin.getline(p,50);
// output the result to stdout
wcout << p;
}
When inputting " Grendel the monster" (newline) in the previous
test, the output will be "Grendel the monster". The manipulator
ws removes spaces.
SEE ALSO
basic_istream, iostream, basic_filebuf,
cin, cout, cerr, clog, wcout,
wcerr, wclog, ios_base, basic_ios
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.3.2
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
wclog
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
wclog
SYNOPSIS
#include <iostream>
extern wostream wclog;
DESCRIPTION
wostream wclog;
The object wclog controls output to a stream buffer associated
with the object stderr declared in <cstdio>. The difference
between wclog and wcerr is that wclog is buffered, but wcerr
isn't . Therefore, commands like wclog << L"ERROR !!"; and
fprintf(stderr,"ERROR !!"); are not synchronized. wclog
uses the locale codecvt facet to convert the wide characters
it receives to the tiny characters it outputs to stderr.
FORMATTING
The formatting is done through member functions or manipulators. See
cout, wcout or basic_ostream for details.
EXAMPLES
//
// wclog example
//
#include<iostream>
#include<fstream>
void main ( )
{
using namespace std;
// open the file "file_name.txt"
// for reading
wifstream in("file_name.txt");
// output the all file to stdout
if ( in )
wcout << in.rdbuf();
else
// if the wifstream object is in a bad state
// output an error message to stderr
wclog << L"Error while opening the file" << endl;
}
WARNINGS
wclog can be used to redirect some of the errors to another
recipient. For example, you might want to redirect them to a file
named my_err:
wofstream out("my_err");
if ( out )
wclog.rdbuf(out.rdbuf());
else
cerr << "Error while opening the file" << endl;
Then when you are doing something like wclog << L"error number x";
the error message is output to the file my_err. Obviously, you
can use the same scheme to redirect wclog to other devices.
SEE ALSO
basic_ostream, iostream, basic_filebuf,
cout, cin, cerr, clog, wcin,
wcout, wcerr, iomanip, ios_base,
basic_ios
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.3.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
wcout
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
wcout
SYNOPSIS
#include <iostream>
extern wostream wcout;
DESCRIPTION
wostream wcout;
The object wcout controls output to a stream buffer associated
with the object stdout declared in <cstdio>. By default the
standard C and C++ streams are synchronized, but performance
can be improved by using the ios_base member function
synch_with_stdio to desynchronize them.
After the object wcin is initialized, wcin.tie() returns &wcout,
which implies that wcin and wcout are synchronized. wcout uses
the locale codecvt facet to convert the wide characters it
receives to the tiny characters it outputs to stdout.
FORMATTING
The formatting is done through member functions or manipulators.
Manipulators Member Functions
showpos setf(ios_base::showpos)
noshowpos unsetf(ios_base::showpos)
showbase setf(ios_base::showbase)
noshowbase unsetf(ios_base::showbase)
uppercase setf(ios_base::uppercase)
nouppercase unsetf(ios_base::uppercase)
showpoint setf(ios_base::showpoint)
noshowpoint unsetf(ios_base::showpoint)
boolalpha setf(ios_base::boolalpha)
noboolalpha unsetf(ios_base::boolalpha)
unitbuf setf(ios_base::unitbuf)
nounitbuf unsetf(ios_base::unitbuf)
internal setf(ios_base::internal,
ios_base::adjustfield)
left setf(ios_base::left,
ios_base::adjustfield)
right setf(ios_base::right,
ios_base::adjustfield)
dec setf(ios_base::dec,
ios_base::basefield)
hex setf(ios_base::hex,
ios_base::basefield)
oct setf(ios_base::oct,
ios_base::basefield)
fixed setf(ios_base::fixed,
ios_base::floatfield)
scientific setf(ios_base::scientific,
ios_base::floatfield)
resetiosflags
(ios_base::fmtflags flag) setf(0,flag)
setiosflags
(ios_base::fmtflags flag) setf(flag)
setbase(int base) See above
setfill(char_type c) fill(c)
setprecision(int n) precision(n)
setw(int n) width(n)
endl
ends
flush flush( )
DESCRIPTION
showpos Generates a + sign in non-negative generated numeric output.
showbase Generates a prefix indicating the numeric base of generated
integer output.
uppercase Replaces certain lowercase letters with their uppercase
equivalents in generated output.
showpoint Generates a decimal-point character unconditionally in
generated floating-point output.
boolalpha Inserts and extracts bool type in alphabetic format.
unitbuf Flushes output after each output operation.
internal Adds fill characters at a designated internal point in
certain generated output, or identical to right if no such
point is designated.
left Adds fill characters on the right (final positions) of certain
generated output.
right Adds fill characters on the left (initial positions) of certain
generated output.
dec Converts integer input or generates integer output in decimal
base.
hex Converts integer input or generates integer output in hexadecimal
base.
oct Converts integer input or generates integer output in octal base.
fixed Generates floating-point output in fixed-point notation.
scientific Generates floating-point output in scientific notation.
resetiosflagss
(ios_base::fmtflags flag) Resets the fmtflags field flag
setiosflags
(ios_base::fmtflags flag) Sets up the flag flag
setbase(int base) Converts integer input or generates integer output
in base base. The parameter base can be 8,
10 or 16.
setfill(char_type c) Sets the character used to pad (fill) an output
conversion to the specified field width.
setprecision(int n) Sets the precision (number of digits after the
decimal point) to generate on certain output
conversions.
setw(int n) Sets the field with (number of characters) to generate on
certain output conversions.
endl Inserts a newline character into the output sequence and flush
the output buffer.
ends Inserts a null character into the output sequence.
flush Flushes the output buffer.
DEFAULT VALUES
precision() 6
width() 0
fill() the space character
flags() skipws | dec
getloc() locale::locale()
EXAMPLES
//
// wcout example one
//
#include<iostream>
#include<iomanip>
void main ( )
{
using namespace std;
int i;
float f;
// read an integer and a float from stdin
cin >> i >> f;
// output the integer and goes at the line
wcout << i << endl;
// output the float and goes at the line
wcout << f << endl;
// output i in hexa
wcout << hex << i << endl;
// output i in octal and then in decimal
wcout << oct << i << dec << i << endl;
// output i preceded by its sign
wcout << showpos << i << endl;
// output i in hexa
wcout << setbase(16) << i << endl;
// output i in dec and pad to the left with character
// @ until a width of 20
// if you input 45 it outputs 45@@@@@@@@@@@@@@@@@@
wcout << setfill(L'@') << setw(20) << left << dec << i;
wcout << endl;
// output the same result as the code just above
// but uses member functions rather than manipulators
wcout.fill('@');
wcout.width(20);
wcout.setf(ios_base::left, ios_base::adjustfield);
wcout.setf(ios_base::dec, ios_base::basefield);
wcout << i << endl;
// outputs f in scientific notation with
// a precision of 10 digits
wcout << scientific << setprecision(10) << f << endl;
// change the precision to 6 digits
// equivalents to wcout << setprecision(6);
wcout.precision(6);
// output f and goes back to fixed notation
wcout << f << fixed << endl;
}
//
// wcout example two
//
#include <iostream>
void main ( )
{
using namespace std;
wchar_t p[50];
wcin.getline(p,50);
wcout << p;
}
//
// wcout example three
//
#include <iostream>
#include <fstream>
void main ( )
{
using namespace std;
// open the file "file_name.txt"
// for reading
wifstream in("file_name.txt");
// output the all file to stdout
if ( in )
wcout << in.rdbuf();
else
{
wcout << "Error while opening the file";
wcout << endl;
}
}
WARNINGS
Keep in mind that the manipulator endl flushes the stream buffer.
Therefore it is recommended to use L'0 if your only intent is
to go at the line. It will greatly improve performance when C and
C++ streams are not synchronized.
SEE ALSO
basic_ostream, iostream, basic_filebuf,
cin, cout, cerr, clog, wcin,
wcerr, wclog, iomanip, ios_base,
basic_ios
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section 27.3.1
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
wstring
Standard C++ Library
Copyright 1996, Rogue Wave Software, Inc.
NAME
basic_string,string - A templated class for handling sequences of
character-like entities. string and wstring are specialized
versions of basic_string for chars and wchar_ts, respectively.
This page describes the ANSI basic_string class. If you would like
information on the pre-ANSI string class, use the command:
help cxxl
typedef basic_string <char> string;
typedef basic_string <wchar_t> wstring;
SYNOPSIS
#include <string>
template <class charT,
class traits = char_traits<charT>,
class Allocator = allocator<charT> >
class basic_string;
DESCRIPTION
basic_string<charT, traits, Allocator> is a homogeneous collection
of character-like entities. It provides general string
functionality such as compare, append, assign, insert, remove, and
replace , along with various searches. basic_string also functions
as an STL sequence container, providing random access
iterators. This allows some of the generic algorithms to apply
to strings.
Any underlying character-like type may be used as long as an
appropriate string_char_traits class is provided or the default
traits class is applicable.
INTERFACE
template <class charT,
class traits = char_traits<charT>,
class Allocator = allocator<charT> >
class basic_string {
public:
// Types
typedef traits traits_type;
typedef typename traits::char_type value_type;
typedef Allocator allocator_type;
typename size_type;
typename difference_type;
typename reference;
typename const_reference;
typename pointer;
typename const_pointer;
typename iterator;
typename const_iterator;
typename const_reverse_iterator;
typename reverse_iterator;
static const size_type npos = -1;
// Constructors/Destructors
explicit basic_string(const Allocator& = Allocator());
basic_string (const basic_string<charT, traits, Allocator>&);
basic_string(const basic_string&, size_type, size_type = npos);
basic_string(const charT*, size_type,
const Allocator& = Allocator());
basic_string(const charT*, Allocator& = Allocator());
basic_string(size_type, charT,
const Allocator& = Allocator());
template <class InputIterator>
basic_string(InputIterator, InputIterator,
const Allocator& = Allocator());
~basic_string();
// Assignment operators
basic_string& operator=(const basic_string&);
basic_string& operator=(const charT*);
basic_string& operator=(charT);
// Iterators
iterator begin();
const_iterator begin() const;
iterator end();
const_iterator end() const;
reverse_iterator rbegin();
const_reverse_iterator rbegin() const;
reverse_iterator rend();
const_reverse_iterator rend() const;
// Capacity
size_type size() const;
size_type length() const;
size_type max_size() const;
void resize(size_type, charT);
void resize(size_type);
size_type capacity() const;
void reserve(size_type);
bool empty() const;
// Element access
const_reference operator[](size_type) const;
reference operator[](size_type);
const_reference at(size_type) const;
reference at(size_type);
// Modifiers
basic_string& operator+=(const basic_string&);
basic_string& operator+=(const charT*);
basic_string& operator+=(charT);
basic_string& append(const basic_string&);
basic_string& append(const basic_string&,
size_type, size_type);
basic_string& append(const charT*, size_type);
basic_string& append(const charT*);
basic_string& append(size_type, charT);
template<class InputIterator>
basic_string& append(InputIterator, InputIterator);
basic_string& assign(const basic_string&);
basic_string& assign(const basic_string&,
size_type, size_type);
basic_string& assign(const charT*, size_type);
basic_string& assign(const charT*);
basic_string& assign(size_type, charT);
template<class InputIterator>
basic_string& assign(InputIterator, InputIterator);
basic_string& insert(size_type, const basic_string&);
basic_string& insert(size_type, const basic_string&,
size_type, size_type);
basic_string& insert(size_type, const charT*, size_type);
basic_string& insert(size_type, const charT*);
basic_string& insert(size_type, size_type, charT);
iterator insert(iterator, charT = charT());
void insert(iterator, size_type, charT);
template<class InputIterator>
void insert(iterator, InputIterator,
InputIterator);
basic_string& erase(size_type = 0, size_type= npos);
iterator erase(iterator);
iterator erase(iterator, iterator);
basic_string& replace(size_type, size_type,
const basic_string&);
basic_string& replace(size_type, size_type,
const basic_string&,
size_type, size_type);
basic_string& replace(size_type, size_type,
const charT*, size_type);
basic_string& replace(size_type, size_type,
const charT*);
basic_string& replace(size_type, size_type,
size_type, charT);
basic_string& replace(iterator, iterator,
const basic_string&);
basic_string& replace(iterator, iterator,
const charT*, size_type);
basic_string& replace(iterator, iterator,
const charT*);
basic_string& replace(iterator, iterator,
size_type, charT);
template<class InputIterator>
basic_string& replace(iterator, iterator,
InputIterator, InputIterator);
size_type copy(charT*, size_type, size_type = 0);
void swap(basic_string<charT, traits, Allocator>&);
// String operations
const charT* c_str() const;
const charT* data() const;
const allocator_type& get_allocator() const;
size_type find(const basic_string&,
size_type = 0) const;
size_type find(const charT*,
size_type, size_type) const;
size_type find(const charT*, size_type = 0) const;
size_type find(charT, size_type = 0) const;
size_type rfind(const basic_string&,
size_type = npos) const;
size_type rfind(const charT*,
size_type, size_type) const;
size_type rfind(const charT*,
size_type = npos) const;
size_type rfind(charT, size_type = npos) const;
size_type find_first_of(const basic_string&,
size_type = 0) const;
size_type find_first_of(const charT*,
size_type, size_type) const;
size_type find_first_of(const charT*,
size_type = 0) const;
size_type find_first_of(charT, size_type = 0) const;
size_type find_last_of(const basic_string&,
size_type = npos) const;
size_type find_last_of(const charT*,
size_type, size_type) const;
size_type find_last_of(const charT*, size_type = npos) const;
size_type find_last_of(charT, size_type = npos) const;
size_type find_first_not_of(const basic_string&,
size_type = 0) const;
size_type find_first_not_of(const charT*,
size_type, size_type) const;
size_type find_first_not_of(const charT*, size_type = 0) const;
size_type find_first_not_of(charT, size_type = 0) const;
size_type find_last_not_of(const basic_string&,
size_type = npos) const;
size_type find_last_not_of(const charT*,
size_type, size_type) const;
size_type find_last_not_of(const charT*,
size_type = npos) const;
size_type find_last_not_of(charT, size_type = npos) const;
basic_string substr(size_type = 0, size_type = npos) const;
int compare(const basic_string&) const;
int compare(size_type, size_type, const basic_string&) const;
int compare(size_type, size_type, const basic_string&,
size_type, size_type) const;
int compare(size_type, size_type, charT*) const;
int compare(charT*) const;
int compare(size_type, size_type, const charT*, size_type) const;
};
// Non-member Operators
template <class charT, class traits, class Allocator>
basic_string operator+ (const basic_string&,
const basic_string&);
template <class charT, class traits, class Allocator>
basic_string operator+ (const charT*, const basic_string&);
template <class charT, class traits, class Allocator>
basic_string operator+ (charT, const basic_string&);
template <class charT, class traits, class Allocator>
basic_string operator+ (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
basic_string operator+ (const basic_string&, charT);
template <class charT, class traits, class Allocator>
bool operator== (const basic_string&, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator== (const charT*, const basic_string&);
template <class charT, class traits , class Allocator>
bool operator== (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
bool operator< (const basic_string&, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator< (const charT*, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator< (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
bool operator!= (const basic_string&, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator!= (const charT*, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator!= (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
bool operator> (const basic_&, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator> (const charT*, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator> (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
bool operator<= (const basic_string&, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator<= (const charT*, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator<= (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
bool operator>= (const basic_string&, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator>= (const charT*, const basic_string&);
template <class charT, class traits, class Allocator>
bool operator>= (const basic_string&, const charT*);
template <class charT, class traits, class Allocator>
void swap(basic_string<charT,traits,Allocator>& a,
basic_string<charT,traits,Allocator>& b);
template<class charT, class traits, class Allocator>
istream& operator>> (istream&, basic_string&);
template <class charT, class traits, class Allocator>
ostream& operator<< (ostream&, const basic_string&);
template <class Stream, class charT,
class traits, class Allocator>
Stream& getline (Stream&, basic_string&, charT);
CONSTRUCTORS AND DESTRUCTORS
In all cases, the Allocator parameter will be used for storage
management.
explicit
basic_string (const Allocator& a = Allocator());
The default constructor. Creates a basic_string with the
following effects:
data() a non-null pointer that is copyable and can have 0
added to it
size() 0
capacity() an unspecified value
basic_string (const basic_string<T, traits, Allocator>& str);
Copy constructor. Creates a string that is a copy of str.
basic_string (const basic_string &str, size_type pos,
size_type n= npos);
Creates a string if pos<=size() and determines length rlen
of initial string value as the smaller of n and str.size() - pos.
This has the following effects:
data() points at the first element of an allocated copy
of rlen elements of the string controlled by str
beginning at position pos
size() rlen
capacity() a value at least as large as size()
get_allocator() str.get_allocator()
An out_of_range exception will be thrown if pos>str.size().
basic_string (const charT* s, size_type n,
const Allocator& a = Allocator());
Creates a string that contains the first n characters of s.
s must not be a NULL pointer. The effects of this con-
structor are:
data() points at the first element of an allocated copy
of the array whose first element is pointed at by
s
size() n
capacity() a value at least as large as size()
An out_of_range exception will be thrown if n == npos.
basic_string (const charT * s,
const Allocator& a = Allocator());
Constructs a string containing all characters in s up to,
but not including, a traits::eos() character. s must not be
a null pointer. The effects of this constructor are:
data() points at the first element of an allocated copy
of the array whose first element is pointed at by
s
size() traits::length(s)
capacity() a value at least as large as size()
basic_string (size_type n, charT c,
const Allocator& a = Allocator());
Constructs a string containing n repetitions of c. A
length_error exception is thrown if n == npos. The effects
of this constructor are:
data() points at the first element of an allocated array
of n elements, each storing the initial value c
size() n
capacity() a value at least as large as size()
template <class InputIterator>
basic_string (InputIterator first, InputIterator last,
const Allocator& a = Allocator());
Creates a basic_string of length last - first, filled with all
values obtained by dereferencing the InputIterators on the
range [first, last). The effects of this constructor are:
data() points at the first element of an allocated copy
of the elements in the range [first,last)
size() distance between first and last
capacity() a value at least as large as size()
~basic_string ();
Releases any allocated memory for this basic_string.
OPERATORS
basic_string&
operator= (const basic_string& str);
Assignment operator. Sets the contents of this string to be the
same as str. The effects of operator= are:
data() points at the first element of an allocated copy of the array
whose first element is pointed at by str.size()
size() str.size()
capacity() a value at least as large as size()
basic_string&
operator= (const charT * s);
Assignment operator. Sets the contents of this string to be the
same as s up to, but not including, the traits::eos() character.
basic_string&
operator= (charT c);
Assignment operator. Sets the contents of this string to be equal
to the single charT c.
const_reference
operator[] (size_type pos) const;
reference
operator[] (size_type pos);
If pos < size(), returns the element at position pos in this
string. If pos == size(), the const version returns
traits::eos(), the behavior of the non-const version is
undefined. The reference returned by either version is
invalidated by any call to c_str(), data(), or any non-const
member function for the object.
basic_string&
operator+= (const basic_string& s);
basic_string&
operator+= (const charT* s);
basic_string&
operator+= (charT c);
Concatenates a string onto the current contents of this string.
The second member operator uses traits::length() to determine the
number of elements from s to add. The third member
operator adds the single character c. All return a reference
to this string after completion.
ITERATORS
iterator begin ();
const_iterator begin () const;
Return an iterator initialized to the first element of the
string.
iterator end ();
const_iterator end () const;
Return an iterator initialized to the position after the last
element of the string.
reverse_iterator rbegin ();
const_reverse_iterator rbegin () const;
Returns an iterator equivalent to reverse_iterator(end()).
reverse_iterator rend ();
const_reverse_iterator rend () const;
Returns an iterator equivalent to reverse_iterator(begin()).
ALLOCATOR
const allocator_type get_allocator () const;
Returns a copy of the allocator used by self for storage
management.
MEMBER FUNCTIONS
basic_string&
append (const basic_string& s, size_type pos, size_type npos);
basic_string&
append (const basic_string& s);
basic_string&
append (const charT* s, size_type n);
basic_string&
append (const charT* s);
basic_string&
append (size_type n, charT c );
template<class InputIterator>
basic_string&
append (InputIterator first, InputIterator last);
Append another string to the end of this string. The first two
functions append the lesser of n and s.size() - pos characters of
s, beginning at position pos to this string. The second
member will throw an out_of_range exception if pos
> str.size(). The third member appends n characters of the
array pointed to by s. The fourth variation appends elements
from the array pointed to by s up to, but not including, a
traits::eos() character. The fifth variation appends n
repetitions of c. The final append function appends the
elements specified in the range [first, last).
All functions will throw a length_error exception if the
resulting length will exceed max_size(). All return a
reference to this string after completion.
basic_string&
assign (const basic_string& s);
basic_string&
assign (const basic_string& s,
size_type pos, size_type n);
basic_string&
assign (const charT* s, size_type n);
basic_string&
assign (const charT* s);
basic_string&
assign (size_type n, charT c );
template<class InputIterator>
basic_string&
assign (InputIterator first, InputIterator last);
Replace the value of this string with the value of another.
All versions of the function assign values to this string. The
first two variations assign the lesser of n and s.size() - pos
characters of s, beginning at position pos. The second
variation throws an out_of_range exception if pos > str.size().
The third version of the function assigns n characters of
the array pointed to by s. The fourth version assigns elements
from the array pointed to by s up to, but not including, a
traits::eos() character. The fifth assigns one or n
repetitions of c. The last variation assigns the members
specified by the range [first, last).
All functions will throw a length_error exception if the
resulting length will exceed max_size(). All return a
reference to this string after completion.
const_reference
at (size_type pos) const;
reference
at (size_type pos);
If pos < size(), returns the element at position pos in this
string. Otherwise, an out_of_range exception is thrown.
size_type
capacity () const;
Returns the current storage capacity of the string. This is
guaranteed to be at least as large as size().
int
compare (const basic_string& str);
Returns the result of a lexicographical comparison between
elements of this string and elements of str. The return value
is:
<0 if size() < str.size()
0 if size() == str.size()
>0 if size() > str.size()
int
compare (size_type pos1, size_type n1,
const basic_string& str) const;
int
compare (size_type pos1, size_type n1, const basic_string& str,
size_type pos2, size_type n2) const;
int
compare (charT* s) const;
int
compare (size_type pos, size_type n1, charT* s) const;
int
compare (size_type pos, size_type n1, charT* s,
size_type n2) const;
Return the result of a lexicographical comparison between ele-
ments of this string and a given comparison string. The members
return, respectively:
compare (str)
compare (basic_string (str, pos2, n2))
compare (basic_string(s))
compare (basic_string(s, npos))
compare (basic_string (s,n2))
size_type
copy (charT* s, size_type n, size_type pos = 0) const;
Replaces elements in memory with copies of elements from this
string. An out_of_range exception will be thrown if pos > size().
The lesser of n and size() - pos elements of this string,
starting at position pos are copied into the array pointed
to by s. No terminating null is appended to s.
const charT*
c_str () const;
const charT*
data () const;
Return a pointer to the initial element of an array whose first
size() elements are copies of the elements in this string. A
traits::eos() element is appended to the end. The elements of
the array may not be altered, and the returned pointer is only
valid until a non-const member function of this string is
called. If size() is zero, the data() function returns a
NULL pointer.
bool empty () const;
Returns size() == 0.
basic_string&
erase (size_type pos = 0, size_type n = npos);
iterator
erase (iterator p);
iterator
erase (iterator first, iterator last);
This function removes elements from the string, collapsing the
remaining elements, as necessary, to remove any space left
empty. The first version of the function removes the smaller
of n and size() - pos starting at position pos. An
out_of_range exception will be thrown if pos > size(). The
second version requires that p is a valid iterator on this
string, and removes the character referred to by p. The last
version of erase requires that both first and last are valid
iterators on this string, and removes the characters defined by
the range [first, last). The destructors for all removed
characters are called. All versions of erase return a
reference to this string after completion.
size_type
find (const basic_string& str, size_type pos = 0) const;
Searches for the first occurrence of the substring specified by
str in this string, starting at position pos. If found, it
returns the index of the first character of the matching
substring. If not found, returns npos. Equality is defined by
traits::eq().
size_type
find (const charT* s, size_type pos, size_type n) const;
size_type
find (const charT* s, size_type pos = 0) const;
size_type
find (charT c, size_type pos = 0) const;
Search for the first sequence of characters in this string that
match a specified string. The variations of this function
return, respectively:
find(basic_string(s,n), pos)
find(basic_string(s), pos)
find(basic_string(1, c), pos)
size_type
find_first_not_of (const basic_string& str,
size_type pos = 0) const;
Searches for the first element of this string at or after
position pos that is not equal to any element of str. If found,
find_first_not_of returns the index of the non-matching
character. If all of the characters match, the function returns
npos. Equality is defined by traits::eq().
size_type
find_first_not_of (const charT* s,
size_type pos, size_type n) const;
size_type
find_first_not_of (const charT* s,
size_type pos = 0) const;
size_type
find_first_not_of (charT c, size_type pos = 0) const;
Search for the first element in this string at or after position
pos that is not equal to any element of a given set of
characters. The members return, respectively:
find_first_not_of(basic_string(s,n), pos)
find_first_not_of(basic_string(s), pos)
find_first_not_of(basic_string(1, c), pos)
size_type
find_first_of(const basic_string& str,
size_type pos = 0) const;
Searches for the first occurrence at or after position pos
of any element of str in this string. If found, the index
of this matching character is returned. If not found, npos
is returned. Equality is defined by traits::eq().
size_type
find_first_of(const charT* s, size_type pos,
size_type n) const;
size_type
find_first_of(const charT* s, size_type pos = 0) const;
size_type
find_first_of (charT c, size_type pos = 0) const;
Search for the first occurrence in this string of any element in
a specified string. The find_first_of variations return,
respectively:
find_first_of(basic_string(s,n), pos)
find_first_of(basic_string(s), pos)
find_first_of(basic_string(1, c), pos)
size_type
find_last_not_of(const basic_string& str,
size_type pos = npos) const;
Searches for the last element of this string at or before
position pos that is not equal to any element of str. If
find_last_not_of finds a non-matching element, it returns the
index of the character. If all the elements match, the
function returns npos. Equality is defined by traits::eq().
size_type
find_last_not_of(const charT* s,
size_type pos, size_type n) const;
size_type
find_last_not_of(const charT* s, size_type pos = npos) const;
size_type
find_last_not_of(charT c, size_type pos = npos) const;
Search for the last element in this string at or before position pos
that is not equal to any element of a given set of characters. The
members return, respectively:
find_last_not_of(basic_string(s,n), pos)
find_last_not_of(basic_string(s), pos)
find_last_not_of(basic_string(1, c), pos)
size_type
find_last_of(const basic_string& str,
size_type pos = npos) const;
Searches for the last occurrence of any element of str at or
before position pos in this string. If found, find_last_of
returns the index of the matching character. If not found
find_last_of returns npos. Equality is defined by traits::eq().
size_type
find_last_of(const charT* s, size_type pos,
size_type n) const;
size_type
find_last_of(const charT* s, size_type pos = npos) const;
size_type
find_last_of(charT c, size_type pos = npos) const;
Search for the last occurrence in this string of any element in a
specified string. The members return, respectively:
find_last_of(basic_string(s,n), pos)
find_last_of(basic_string(s), pos)
find_last_of(basic_string(1, c), pos)
basic_string&
insert(size_type pos1, const basic_string& s);
basic_string&
insert(size_type pos, const basic_string& s,
size_type pos2 = 0, size_type n = npos);
basic_string&
insert(size_type pos, const charT* s, size_type n);
basic_string&
insert(size_type pos, const charT* s);
basic_string&
insert(size_type pos, size_type n, charT c);
Insert additional elements at position pos in this string. All
of the variants of this function will throw an out_of_range
exception if pos > size(). All variants will also throw a
length_error if the resulting string will exceed max_size().
Elements of this string will be moved apart as necessary to
accommodate the inserted elements. All return a reference to
this string after completion.
The second variation of this function inserts the lesser of n and
s.size() - pos2 characters of s, beginning at position pos2 in
this string. This version will throw an out_of_range
exception if pos2 > s.size(). The third version inserts n
characters of the array pointed to by s. The fourth inserts
elements from the array pointed to by s up to, but not
including, a traits::eos() character. Finally, the fifth
variation inserts n repetitions of c.
iterator
insert(iterator p, charT c = charT());
void
insert(iterator p, size_type n, charT c);
template<class InputIterator>
void
insert(iterator p, InputIterator first, InputIterator last);
Insert additional elements in this string immediately before
the character referred to by p. All of these versions
of insert require that p is a valid iterator on this
string. The first version inserts a copy of c. The second
version inserts n repetitions of c. The third version
inserts characters in the range [first, last). The first version
returns p.
size_type
length() const;
Return the number of elements contained in this string.
size_type
max_size() const;
Returns the maximum possible size of the string.
size_type
rfind (const basic_string& str, size_type pos = npos) const;
Searches for the last occurrence of the substring specified by
str in this string, starting at position pos. Note that only the
first character of the substring must be <= pos; the
remaining characters may extend beyond pos. If found, the index
of the first character of that matches substring is returned. If
not found, npos is returned. Equality is defined by
traits::eq().
size_type
rfind(const charT* s, size_type pos, size_type n) const;
size_type
rfind(const charT* s, size_type pos = npos) const;
size_type
rfind(charT c, size_type pos = npos) const;
Searches for the last sequence of characters in this string
matching a specified string. The rfind variations return,
respectively:
rfind(basic_string(s,n), pos)
rfind(basic_string(s), pos)
rfind(basic_string(1, c), pos)
basic_string&
replace(size_type pos, size_type n1, const basic_string& s);
basic_string&
replace(size_type pos1, size_type n1, const basic_string& str,
size_type pos2, size_type n2);
basic_string&
replace(size_type pos, size_type n1, const charT* s,
size_type n2);
basic_string&
replace(size_type pos, size_type n1, const charT* s);
basic_string&
replace(size_type pos, size_type n1, size_type n2, charT c);
The replace function replaces selected elements of this string
with an alternate set of elements. All of these versions insert
the new elements in place of n1 elements in this string,
starting at position pos. They each throw an out_of_range
exception if pos1 > size()and a length_error exception if the
resulting string size exceeds max_size().
The second version replaces elements of the original string with
n2 characters from string s starting at position pos2. It
will throw the out_of_range exception if pos2 > s.size(). The
third variation of the function replaces elements in the
original string with n2 elements from the array pointed to by
s. The fourth version replaces elements in the string with
elements from the array pointed to by s, up to, but not
including, a traits::eos() character. The fifth replaces n
elements with n2 repetitions of character c.
basic_string&
replace(iterator i1, iterator i2,
const basic_string& str);
basic_string&
replace(iterator i1, iterator i2, const charT* s,
size_type n);
basic_string&
replace(iterator i1, iterator i2, const charT* s);
basic_string&
replace(iterator i1, iterator i2, size_type n,
charT c);
template<class InputIterator>
basic_string&
replace(iterator i1, iterator i2,
InputIterator j1, InputIterator j2);
Replace selected elements of this string with an alternative set
of elements. All of these versions of replace require
iterators i1 and i2 to be valid iterators on this string. The
elements specified by the range [i1,i2) are replaced by
the new elements.
The first version shown here replaces with all members in
str. The second version starts at position i1, and replaces the
next n characters with n characters of the array pointed to by
s. The third variation replaces string elements with elements
from the array pointed to by s up to, but not including, a
traits::eos() character. The fourth version replaces string
elements with n repetitions of c. The last variation
shown here replaces string elements with the members
specified in the range [j1, j2).
void
reserve(size_type res_arg);
Assures that the storage capacity is at least res_arg.
void
resize(size_type n, charT c);
void
resize(size_type n);
Changes the capacity of this string to n. If the new capacity is
smaller than the current size of the string, then it is
truncated. If the capacity is larger, then the string is padded
with c characters. The latter resize member pads the string
with default characters specified by traits::eos().
size type
size() const;
Return the number of elements contained in this string.
basic_string
substr(size_type pos = 0, size_type n = npos) const;
Returns a string composed of copies of the lesser of n and size()
characters in this string starting at index pos. Throws an
out_of_range exception if pos <= size().
void
swap(basic_string& s);
Swaps the contents of this string with the contents of s.
NON-MEMBER OPERATORS
template<class charT, class traits, class Allocator>
basic_string
operator+(const basic_string& lhs, const basic_string& rhs);
Returns a string of length lhs.size() + rhs.size(), where the
first lhs.size() elements are copies of the elements of lhs,
and the next rhs.size() elements are copies of the elements of
rhs.
template<class charT, class traits, class Allocator>
basic_string
operator+(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
basic_string
operator+(charT lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
basic_string
operator+(const basic_string& lhs, const charT* rhs);
template<class charT, class traits, class Allocator>
basic_string
operator+(const basic_string& lhs, charT rhs);
Returns a string that represents the concatenation of two
string-like entities. These functions return, respectively:
basic_string(lhs) + rhs
basic_string(1, lhs) + rhs
lhs + basic_string(rhs)
lhs + basic_string(1, rhs)
template<class charT, class traits, class Allocator>
bool
operator==(const basic_string& lhs, const basic_string& rhs);
Returns a boolean value of true if lhs and rhs are equal, and
false if they are not. Equality is defined by the
compare() member function.
template<class charT, class traits, class Allocator>
bool
operator==(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
bool
operator==(const basic_string& lhs, const charT* rhs);
Returns a boolean value indicating whether lhs and rhs are equal.
Equality is defined by the compare() member function. These
functions return, respectively:
basic_string(lhs) == rhs
lhs == basic_string(rhs)
template<class charT, class traits, class Allocator>
bool
operator!=(const basic_string& lhs,
const basic_string& rhs);
Returns a boolean value representing the inequality of lhs and
rhs. Inequality is defined by the compare() member function.
template<class charT, class traits, class Allocator>
bool
operator!=(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
bool
operator!=(const basic_string& lhs, const charT* rhs);
Returns a boolean value representing the inequality of lhs and
rhs. Inequality is defined by the compare() member function.
The functions return, respectively:
basic_string(lhs) != rhs
lhs != basic_string(rhs)
template<class charT, class traits, class Allocator>
bool
operator<(const basic_string& lhs, const basic_string& rhs);
Returns a boolean value representing the lexicographical
less-than relationship of lhs and rhs. Less-than is defined
by the compare() member.
template<class charT, class traits, class Allocator>
bool
operator<(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
bool
operator<(const basic_string& lhs, const charT* rhs);
Returns a boolean value representing the lexicographical
less-than relationship of lhs and rhs. Less-than is defined
by the compare() member function. These functions return,
respectively:
basic_string(lhs) < rhs
lhs < basic_string(rhs)
template<class charT, class traits, class Allocator>
bool
operator>(const basic_string& lhs, const basic_string& rhs);
Returns a boolean value representing the lexicographical
greater-than relationship of lhs and rhs. Greater-than is
defined by the compare() member function.
template<class charT, class traits, class Allocator>
bool
operator>(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
bool
operator>(const basic_string& lhs, const charT* rhs);
Returns a boolean value representing the lexicographical
greater-than relationship of lhs and rhs. Greater-than is
defined by the compare() member. The functions return,
respectively:
basic_string(lhs) > rhs
lhs > basic_string(rhs)
template<class charT, class traits, class Allocator>
bool
operator<=(const basic_string& lhs,
const basic_string& rhs);
Returns a boolean value representing the lexicographical
less-than-or-equal relationship of lhs and rhs. Less-than-
or-equal is defined by the compare() member function.
template<class charT, class traits, class Allocator>
bool
operator<=(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
bool
operator<=(const basic_string& lhs, const charT* rhs);
Returns a boolean value representing the lexicographical
less-than-or-equal relationship of lhs and rhs.
Less-than-or-equal is defined by the compare() member function.
These functions return, respectively:
basic_string(lhs) <= rhs
lhs <= basic_string(rhs)
template<class charT, class traits, class Allocator>
bool
operator>=(const basic_string& lhs, const basic_string& rhs);
Returns a boolean value representing the lexicographical
greater-than- or-equal relationship of lhs and rhs.
Greater-than-or-equal is defined by the compare() member
function.
template<class charT, class traits, class Allocator>
bool
operator>=(const charT* lhs, const basic_string& rhs);
template<class charT, class traits, class Allocator>
bool
operator>=(const basic_string& lhs, const charT* rhs);
Returns a boolean value representing the lexicographical
greater-than- or-equal relationship of lhs and rhs.
Greater-than-or-equal is defined by the compare() member.
The functions return, respectively:
basic_string(lhs) >= rhs
lhs >= basic_string(rhs)
template <class charT, class traits, class Allocator>
void swap(basic_string<charT,traits,Allocator>& a,
basic_string<charT,traits,Allocator>& b);
Swaps the contents of a and b by calling a's swap function on b.
template<class charT, class traits, class Allocator>
istream&
operator>>(istream& is, basic_string& str);
Reads str from is using traits::char_in until a
traits::is_del() element is read. All elements read, except
the delimiter, are placed in str. After the read, the function
returns is.
template<class charT, class traits, class Allocator>
ostream&
operator<<(ostream& os, const basic_string& str);
Writes all elements of str to os in order from first to last,
using traits::char_out(). After the write, the function
returns os.
NON-MEMBER FUNCTION
template <class Stream, class charT, class traits,
class Allocator>
Stream&
getline(Stream& is, basic_string& str, charT delim);
An unformatted input function that extracts characters from is
into str until npos - 1 characters are read, the end of
the input sequence is reached, or the character read is
delim. The characters are read using traits::char_in().
EXAMPLE
//
// string.cpp
//
#include<string>
#include <iostream.h>
int main()
{
string test;
//Type in a string over five characters long
while(test.empty() || test.size() <= 5)
{
cout << "Type a string between 5 and 100 characters long. "
<< endl;
cin >> test;
}
//Test operator[] access
cout << "Changing the third character from " << test[2] <<
" to * " << endl;
test[2] = '*';
cout << "now its: " << test << endl << endl;
//Try the insertion member function
cout << "Identifying the middle: ";
test.insert(test.size() / 2, "(the middle is here!)");
cout << test << endl << endl;
//Try replacement
cout << "I didn't like the word 'middle',so instead,I'll say:"
<< endl;
test.replace(test.find("middle",0), 6, "center");
cout << test << endl;
return 0;
}
Output :
Type a string between 5 and 100 characters long.
roguewave
Changing the third character from g to *
now its: ro*uewave
Identifying the middle: ro*u(the middle is here!)ewave
I didn't like the word 'middle', so instead, I'll say:
ro*u(the center is here!)ewave
SEE ALSO
Allocators, string, wstring
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
