Library: Input/output
basic_istreambasic_ios
Class that assists in reading and interpreting sequences of characters controlled by a stream buffer
#include <istream>
namespace std {
template<class charT, class traits = char_traits<charT> >
class basic_istream;
}
The class basic_istream assists in reading and interpreting sequences of characters controlled by a stream buffer. Two groups of functions share common properties, the formatted functions and the unformatted functions.
Both groups of functions obtain (or extract) input characters from basic_streambuf. They both begin by constructing an object of class basic_istream::sentry and, if this object returns true when converted to bool after construction, the function obtains the requested input. The sentry object performs exception-safe initialization, such as controlling the status of the stream or locking it in a 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 depends directly on the locale object being imbued in the stream.
namespace std {
template <class charT, class traits = char_traits<charT> >
class basic_istream : virtual public basic_ios<charT,traits>
{
public:
typedef charT char_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
typedef traits traits_type;
explicit basic_istream(basic_streambuf<char_type,
traits_type>*);
virtual ~basic_istream();
class sentry;
basic_istream& operator>>(basic_istream&(*)(basic_istream&))
basic_istream& operator>>
(basic_ios<char_type,traits_type>& (*)(basic_ios<char_type,
traits_type>&))
basic_istream& operator>>(ios_base& (*pf)(ios_base&))
basic_istream& operator>>(bool&);
basic_istream& operator>>(short&);
basic_istream& operator>>(unsigned short&);
basic_istream& operator>>(int&);
basic_istream& operator>>(unsigned int&);
basic_istream& operator>>(long&);
basic_istream& operator>>(unsigned long&);
basic_istream& operator>>(float&);
basic_istream& operator>>(double&);
basic_istream& operator>>(long double&);
basic_istream& operator>>(void*&);
basic_istream& operator>>(basic_streambuf<char_type,
traits_type>*);
streamsize gcount() const;
int_type get();
basic_istream& get(char_type&);
basic_istream& get(char_type*, streamsize);
basic_istream& get(char_type*, streamsize, char_type);
basic_istream& get(basic_streambuf<char_type,traits>&);
basic_istream& get(basic_streambuf<char_type,traits>&,
char_type);
basic_istream& getline(char_type*, streamsize);
basic_istream& getline(char_type*, streamsize, char_type);
basic_istream& ignore(streamsize = 1,
int_type = traits::eof());
int_type peek();
basic_istream& read(char_type*, streamsize);
streamsize readsome(char_type*, streamsize);
basic_istream& putback(char_type);
basic_istream& unget();
int sync();
pos_type tellg();
basic_istream& seekg(pos_type);
basic_istream& seekg(off_type, ios_base::seekdir);
};
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 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*);
}
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.
traits_type
The type traits_type is a synonym for the template parameter traits.
istream
The type istream is a specialization of class basic_istream on type char:
typedef basic_istream<char> istream;
wistream
The type wistream is a specialization of class basic_istream on type wchar_t:
typedef basic_istream<wchar_t> wistream;
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).
virtual ~basic_istream();
Destroys an object of class basic_istream.
Interface
namespace std {
template <class charT,class traits = char_traits<charT> >
class basic_istream<charT,traits>::sentry
{
public:
explicit sentry(basic_istream<charT,traits>&, bool = false);
~sentry();
operator bool() const;
private:
sentry(const sentry&); // undefined
sentry& operator=(const sentry&); // undefined
};
}
Constructor
explicit sentry(basic_istream<charT,traits> &is,
bool noskipws = 0);
Prepares for formatted or unformatted input. If is.tie() does not return a null pointer, the function synchronizes the output sequence with any associated stream by calling is.tie()->flush(). 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, is.good() returns true, the sentry conversion function operator bool() returns true. Otherwise it returns false. In a multithread environment, the sentry object constructor is responsible for locking the stream and the stream buffer associated with the stream.
Destructor
~sentry();
Destroys an object of class sentry. In a multithread environment, the sentry object destructor is responsible for unlocking the stream and the stream buffer associated with the stream.
Operator
operator bool();
If after any preparation is completed, is.good() returns true, the sentry conversion function operator bool() returns true. Otherwise, it returns false.
basic_istream& operator>>(basic_istream& (*pf)(basic_istream&));
Calls pf(*this), then returns *this.
basic_istream&
operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT,
traits>&));
Calls pf(*this), then returns *this.
basic_istream& operator>>(ios_base& (*pf)(ios_base&));
Calls pf(*this), then returns *this.
basic_istream& 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 must be 0 or 1, if found. 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.
basic_istream& operator>>(short& n);
Converts a signed short integer, if one is available, and stores it in n, then returns *this.
basic_istream& operator>>(unsigned short& n);
Converts an unsigned short integer, if one is available, and stores it in n, then returns *this.
basic_istream& operator>>(int& n);
Converts a signed integer, if one is available, and stores it in n, then returns *this.
basic_istream& operator>>(unsigned int& n);
Converts an unsigned integer, if one is available, and stores it in n, then returns *this.
basic_istream& operator>>(long& n);
Converts a signed long integer, if one is available, and stores it in n, then returns *this.
basic_istream& operator>>(unsigned long& n);
Converts an unsigned long integer, if one is available, and stores it in n, then returns *this.
basic_istream& operator>>(float& f);
Converts a float, if one is available, and stores it in f, then returns *this.
basic_istream& operator>>(double& f);
Converts a double, if one is available, and stores it in f, then returns *this.
basic_istream& operator>>(long double& f);
Converts a long double, if one is available, and stores it in f, then returns *this.
basic_istream& operator>>(void*& p);
Extracts a void pointer, if one is available, and stores it in p, then returns *this.
basic_istream& operator>>(basic_streambuf<charT, traits>* 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:
an end-of-file on the input sequence
a failure when inserting in the output sequence
an exception
If the function stores no characters, it calls the basic_ios member function setstate(failbit), which may throw ios_base::failure. If failure is due to catching an exception thrown while extracting characters from sb, and failbit is on in exception(), the caught exception is rethrown.
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 returns traits::eof(), if none is available.
basic_istream& 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.
basic_istream& 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
an end-of-file on the input sequence is reached
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. If failure is due to catching an exception thrown while extracting characters from sb and failbit is on in exception(), the caught exception is rethrown.
basic_istream& get(char_type* s, streamsize n);
Calls get(s,n,widen('\n')).
basic_istream&
get(basic_streambuf<char_type, traits_type>& sb,
char_type delim);
Extracts characters and inserts them into the output sequence controlled by sb. Characters are extracted and inserted until any of the following occurs:
an end-of-file on the input sequence
a failure when inserting in the output sequence
the next available input character == delim.
an exception
If the function stores no characters, it calls the basic_ios member function setstate(failbit), which may throw ios_base::failure. If failure is due to catching an exception thrown while extracting characters from sb, and failbit is on in exception(), the caught exception is rethrown.
basic_istream& get(basic_streambuf<char_type, traits_type>& sb);
Calls get(sb, widen ('\n')).
basic_istream& 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:
an end-of-file on the input sequence
the next available input character == delim
n - 1 characters are stored. In this case, the function calls setstate(failbit)).
The conditions are tested in the order shown so that the function can exactly fill the buffer without setting failbit. 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.
basic_istream& getline(char_type* s, streamsize n);
Calls getline(s,n,widen('\n')).
basic_istream& ignore(streamsize n = 1, int_type delim = traits_type::eof());
Extracts characters and discards them. Characters are extracted until any of the following occurs:
n characters are extracted.
an end-of-file on the input sequence is reached
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.
basic_istream& putback(char_type c);
If rdbuf () returns non-null, inserts c in the putback sequence by calling rdbuf()->sputbackc(). Otherwise, or if sputback() fails, calls the basic_ios member function setstate(badbit).
basic_istream& 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.
An end-of-file on the input sequence is reached. In this case, the function calls setstate (failbit | eofbit), 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.
basic_istream& seekg(pos_type pos);
If the basic_ios member function fail() returns false, executes rdbuf()->pubseekpos(pos), which positions the current pointer of the input sequence at the position designated by pos. If positioning fails, calls the basic_ios member function setstate(failbit).
istream_type& seekg(off_type& off, ios_base::seekdir dir);
If the basic_ios member function fail() returns false, and executes rdbuf()->pubseekpos(off,dir), which positions the current pointer of the input sequence at the position designated by off and dir. If positioning fails, calls the basic_ios member function setstate(failbit).
int sync();
If rdbuf() is a null pointer, returns -1. Otherwise, calls rdbuf()->pubsync(); if that function returns -1, calls the basic_ios member function setstate(badbit) and returns -1. 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).
basic_istream& 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).
template<class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, charT& c); template<class traits> basic_istream<char, traits>& operator>>(basic_istream<char, traits>& is, unsigned char &c); template<class traits> basic_istream<char, traits>& operator>>(basic_istream<char, traits>& is, signed char &c)
Extracts a character, if one is available, and stores it in c. Otherwise, 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); template<class traits> basic_istream<char, traits>& operator>>(basic_istream<char, traits>& is, unsigned char *s); template<class traits> basic_istream<char, traits>& operator>>(basic_istream<char, traits>& is, signed char *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.width()>0, is.width()-1 characters are extracted
an end-of-file on the input sequence is reached
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 charT, class traits> basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);
Skips any white space in the input sequence and returns is.
//
// istream1.cpp
//
#include <iostream> // for basic_istream, cout, endl, flush
#include <fstream> // for basic_ofstream
#include <stdio.h> // for tmpnam () and remove ()
int main ( )
{
// typedefs for convenience
typedef std::basic_istream<char, std::char_traits<char> > Input;
typedef std::basic_ofstream<Input::char_type, Input::traits_type> Output;
Input::char_type s [200];
// create a temporary filename
const char *fname = tmpnam (0);
if (!fname)
return 1;
// open a file for read and write operations
Output out (fname, std::ios::in | std::ios::out | std::ios::trunc);
// tie the istream object to the ofstream filebuf
Input in (out.rdbuf ());
float f = 3.14159;
int i = 3;
// output to the file
out << "He lifted his head and pondered.\n"
<< f << std::endl << i << std::endl;
// seek to the beginning of the file
in.seekg (0);
f = i = 0;
// read from the file using formatted functions
in.getline (s, sizeof s);
in >> f >> i;
// seek to the beginning of the file
in.seekg (0, std::ios::beg);
// output the all file to the standard output
std::cout << in.rdbuf ();
// seek to the beginning of the file
in.seekg (0);
// read the first line in the file
// "He lifted his head and pondered."
in.getline (s, sizeof s / 2);
std::cout << s << std::endl;
// read the second line in the file
in.getline (s, sizeof s / 2);
std::cout << s << std::endl;
// seek to the beginning of the file
in.seekg (0);
// read the first line in the file
// "He lifted his head and pondered."
in.get (s, sizeof s / 2);
// remove the newline character
in.ignore ();
std::cout << s << std::endl;
// read the second line in the file
// 3.14159
in.get (s, sizeof s / 2);
std::cout << s << std::endl;
// remove the newline character
in.ignore ();
// store the current file position
const Input::pos_type position = in.tellg ();
out << std::endl << "replace the int" << std::endl;
// move back to the previous saved position
in.seekg (position);
// for convenience
const Input::int_type eof = Input::traits_type::eof ();
// output the remainder of the file
// this is equivalent to "std::cout << in.rdbuf ();"
while (!Input::traits_type::eq_int_type (in.peek (), eof))
std::cout << Input::traits_type::to_char_type (in.get ());
std::cout << "\n\n\n" << std::flush;
// remove temporary file
remove (fname);
return 0;
}
Program Output:
He lifted his head and pondered. 3.14159 3 He lifted his head and pondered. 3.14159 He lifted his head and pondered. 3.14159 replace the int
char_traits, ios_base, basic_ios, basic_streambuf, basic_iostream
ISO/IEC 14882:1998 -- International Standard for Information Systems --Programming Language C++, Section 27.6.1.1