basic_istream Class

Article
01/02/2018

The latest version of this topic can be found at basic_istream Class.

Describes an object that controls extraction of elements and encoded objects from a stream buffer with elements of type Elem, also known as char_type, whose character traits are determined by the class Tr, also known as traits_type.

Syntax

template <class Elem, class Tr = char_traits<Elem>>  
class basic_istream       : virtual public basic_ios<Elem, Tr>

Remarks

Most of the member functions that overload operator>> are formatted input functions. They follow the pattern:

iostate state = goodbit;  
const sentry ok(*this);

if (ok)  
 {try  
 {<extract elements and convert  
    accumulate flags in state  
    store a successful conversion> }  
    catch (...)  
 {try  
 {setstate(badbit);

}  
    catch (...)  
 {}  
    if ((exceptions()& badbit) != 0)  
    throw; }}  
setstate(state);

return (*this);

Many other member functions are unformatted input functions. They follow the pattern:

iostate state = goodbit;  
count = 0;    // the value returned by gcount  
const sentry ok(*this, true);

if (ok)  
 {try  
 {<extract elements and deliver  
    count extracted elements in count  
    accumulate flags in state> }  
    catch (...)  
 {try  
 {setstate(badbit);

}  
    catch (...)  
 {}  
    if ((exceptions()& badbit) != 0)  
    throw; }}  
setstate(state);

Both groups of functions call setstate( eofbit) if they encounter end of file while extracting elements.

An object of class basic_istream< Elem, Tr> stores:

A virtual public base object of class basic_ios< Elem, Tr> .
An extraction count for the last unformatted input operation (called count in the previous code).

Example

See the example for basic_ifstream Class to learn more about input streams.

Constructors

basic_istream Constructs an object of type basic_istream.

Member Functions

gcount	Returns the number of characters read during the last unformatted input.
get	Reads one or more characters from the input stream.
getline	Reads a line from the input stream.
ignore	Causes a number of elements to be skipped from the current read position.
peek	Returns the next character to be read.
putback	Puts a specified character into the stream.
read	Reads a specified number of characters from the stream and stores them in an array.
readsome	Read from buffer only.
seekg	Moves the read position in a stream.
sentry	The nested class describes an object whose declaration structures the formatted input functions and the unformatted input functions.
swap	Exchanges this `basic_istream` object for the provided `basic_istream` object parameter.
sync	Synchronizes the input device associated with the stream with the stream's buffer.
tellg	Reports the current read position in the stream.
unget	Puts the most recently read character back into the stream.

Operators

operator>>	Calls a function on the input stream or reads formatted data from the input stream.
operator=	Assigns the `basic_istream` on the right side of the operator to this object. This is a move assignment involving an `rvalue` reference that does not leave a copy behind.

Requirements

Header: <istream>

Namespace: std

basic_istream::basic_istream

Constructs an object of type basic_istream.

explicit basic_istream(
    basic_streambuf<Elem, Tr>* strbuf,  
    bool _Isstd = false);

basic_istream(basic_istream&& right);

Parameters

strbuf
An object of type basic_streambuf.

_Isstd
true if this is a standard stream; otherwise, false.

right
A basic_istream object to copy.

Remarks

The first constructor initializes the base class by calling init(_S trbuf). It also stores zero in the extraction count. For more information about this extraction count, see the Remarks section of the basic_istream Class overview topic.

The second constructor initializes the base class by calling move``( right). It also stores _R ight.gcount() in the extraction count and stores zero in the extraction count for _R ight.

Example

See the example for basic_ifstream::basic_ifstream to learn more about input streams.

basic_istream::gcount

Returns the number of characters read during the last unformatted input.

streamsize gcount() const;

Return Value

The extraction count.

Remarks

Use basic_istream::get to read unformatted characters.

Example

// basic_istream_gcount.cpp  
// compile with: /EHsc  
#include <iostream>  
using namespace std;  
  
int main( )   
{  
   cout << "Type the letter 'a': ";  
  
   ws( cin );  
   char c[10];  
  
   cin.get( &c[0],9 );  
   cout << c << endl;  
  
   cout << cin.gcount( ) << endl;  
}

  
      aType the letter 'a':  
a  
1

basic_istream::get

Reads one or more characters from the input stream.

int_type get();

basic_istream<Elem, Tr>& get(
    Elem& _Ch);

basic_istream<Elem, Tr>& get(
    Elem* str,  
    streamsize count);

basic_istream<Elem, Tr>& get(
    Elem* str,  
    streamsize count,  
    Elem _Delim);

basic_istream<Elem, Tr>& get(
    basic_streambuf<Elem, Tr>& strbuf);

basic_istream<Elem, Tr>& get(
    basic_streambuf<Elem, Tr>& strbuf,  
    Elem _Delim);

Parameters

count
The number of characters to read from strbuf.

_Delim
The character that should terminate the read if it is encountered before count.

str
A string in which to write.

_Ch
A character to get.

strbuf
A buffer in which to write.

Return Value

The parameterless form of get returns the element read as an integer or end of file. The remaining forms return the stream (* this).

Remarks

The first of these unformatted input functions extracts an element, if possible, as if by returning rdbuf-> sbumpc. Otherwise, it returns traits_type::eof. If the function extracts no element, it calls setstate( failbit).

The second function extracts the int_type element meta the same way. If meta compares equal to traits_type::eof, the function calls setstate( failbit). Otherwise, it stores traits_type::to_char_type( meta) in _Ch. The function returns *this.

The third function returns get(_ Str, count, widen('\ n')).

The fourth function extracts up to count - 1 elements and stores them in the array beginning at _ Str. It always stores char_type after any extracted elements it stores. In order of testing, extraction stops:

At end of file.
After the function extracts an element that compares equal to _Delim, in which case the element is put back to the controlled sequence.
After the function extracts count - 1 elements.

If the function extracts no elements, it calls setstate( failbit). In any case, it returns *this.

The fifth function returns get( strbuf, widen('\ n')).

The sixth function extracts elements and inserts them in strbuf. Extraction stops on end-of-file or on an element that compares equal to _ Delim, which is not extracted. It also stops, without extracting the element in question, if an insertion fails or throws an exception (which is caught but not rethrown). If the function extracts no elements, it calls setstate( failbit). In any case, the function returns *this.

Example

// basic_istream_get.cpp  
// compile with: /EHsc  
#include <iostream>  
using namespace std;  
  
int main( )   
{  
   char c[10];  
  
   c[0] = cin.get( );  
   cin.get( c[1] );  
   cin.get( &c[2],3 );  
   cin.get( &c[4], 4, '7' );  
  
   cout << c << endl;  
}

basic_istream::getline

Gets a line from the input stream.

basic_istream<Elem, Tr>& getline(
    char_type* str,   
    streamsize count);

basic_istream<Elem, Tr>& getline(
    char_type* str,   
    streamsize count,   
    char_type _Delim);

Parameters

count
The number of characters to read from strbuf.

_Delim
The character that should terminate the read if it is encountered before count.

str
A string in which to write.

Return Value

The stream ( *this).

Remarks

The first of these unformatted input functions returns getline(_ Str, count, widen(' \n')).

The second function extracts up to count - 1 elements and stores them in the array beginning at _ Str. It always stores the string termination character after any extracted elements it stores. In order of testing, extraction stops:

At end of file.
After the function extracts an element that compares equal to _Delim, in which case the element is neither put back nor appended to the controlled sequence.
After the function extracts count - 1 elements.

If the function extracts no elements or count - 1 elements, it calls setstate( failbit). In any case, it returns *this.

Example

// basic_istream_getline.cpp  
// compile with: /EHsc  
#include <iostream>  
using namespace std;  
  
int main( )   
{  
   char c[10];  
  
   cin.getline( &c[0], 5, '2' );  
   cout << c << endl;  
}

basic_istream::ignore

Causes a number of elements to be skipped from the current read position.

basic_istream<Elem, Tr>& ignore(
    streamsize count = 1,  
    int_type _Delim = traits_type::eof());

Parameters

count
The number of elements to skip from the current read position.

_Delim
The element that, if encountered before count, causes ignore to return and allowing all elements after _Delim to be read.

Return Value

The stream ( *this).

Remarks

The unformatted input function extracts up to count elements and discards them. If count equals numeric_limits<int>::max, however, it is taken as arbitrarily large. Extraction stops early on end of file or on an element _Ch such that traits_type::to_int_type( _Ch) compares equal to _ Delim (which is also extracted). The function returns *this.

Example

// basic_istream_ignore.cpp  
// compile with: /EHsc  
#include <iostream>  
int main( )   
{  
   using namespace std;  
   char chararray[10];  
   cout << "Type 'abcdef': ";  
   cin.ignore( 5, 'c' );  
   cin >> chararray;  
   cout << chararray;  
}

abcdef

abcdefdef

basic_istream::operator>>

Calls a function on the input stream or reads formatted data from the input stream.

basic_istream& operator>>(
    basic_istream& (* _Pfn)(basic_istream&));

basic_istream& operator>>(
    ios_base& (* _Pfn)(ios_base&));

basic_istream& operator>>(
    basic_ios<Elem, Tr>& (* _Pfn)(basic_ios<Elem, Tr>&))  
;  
basic_istream& operator>>(
    basic_streambuf<Elem, Tr>* strbuf);

basic_istream& operator>>(
    bool& val);

basic_istream& operator>>(
    short& val);

basic_istream& operator>>(
    unsigned short& val);

basic_istream& operator>>(
    int& val);

basic_istream& operator>>(
    unsigned int& val);

basic_istream& operator>>(
    long& val);

basic_istream& operator>>(
    unsigned long& val);

basic_istream& operator>>(
    long long& val);

basic_istream& operator>>(
    unsigned long long& val);

basic_istream& operator>>(
    void *& val);

basic_istream& operator>>(
    float& val);

basic_istream& operator>>(
    double& val);

basic_istream& operator>>(
    long double& val);

Parameters

_Pfn
A function pointer.

strbuf
An object of type stream_buf.

val
The value to read from the stream.

Return Value

The stream ( *this).

Remarks

The <istream> header also defines several global extraction operators. For more information, see operator>> (<istream>).

The first member function ensures that an expression of the form istr >> ws calls ws( istr), and then returns *this. The second and third functions ensure that other manipulators, such as hex, behave similarly. The remaining functions constitute the formatted input functions.

The function:

basic_istream& operator>>(
    basic_streambuf<Elem, Tr>* strbuf);

extracts elements, if _ Strbuf is not a null pointer, and inserts them in strbuf. Extraction stops on end of file. It also stops without extracting the element in question, if an insertion fails or throws an exception (which is caught but not rethrown). If the function extracts no elements, it calls setstate( failbit). In any case, the function returns *this.

The function:

basic_istream& operator>>(bool& val);

extracts a field and converts it to a Boolean value by calling use_facet < num_get< Elem, InIt>( getloc). get( InIt( rdbuf), Init(0), *this, getloc, val). Here, InIt is defined as istreambuf_iterator< Elem, Tr>. The function returns *this.

The functions:

basic_istream& operator>>(short& val);

basic_istream& operator>>(unsigned short& val);

basic_istream& operator>>(int& val);

basic_istream& operator>>(unsigned int& val);

basic_istream& operator>>(long& val);

basic_istream& operator>>(unsigned long& val);

 
basic_istream& operator>>(long long& val);

basic_istream& operator>>(unsigned long long& val);

 
basic_istream& operator>>(void *& val);

each extract a field and convert it to a numeric value by calling use_facet< num_get< Elem, InIt>( getloc). get( InIt( rdbuf), Init(0), *this, getloc, val). Here, InIt is defined as istreambuf_iterator< Elem, Tr>, and val has type long,unsigned long, or void * as needed.

If the converted value cannot be represented as the type of val, the function calls setstate( failbit). In any case, the function returns *this.

The functions:

basic_istream& operator>>(float& val);

basic_istream& operator>>(double& val);

basic_istream& operator>>(long double& val);

each extract a field and convert it to a numeric value by calling use_facet< num_get< Elem, InIt>( getloc). get( InIt( rdbuf), Init(0), *this, getloc, val). Here, InIt is defined as istreambuf_iterator< Elem, Tr>, and val has type double or long double as needed.

If the converted value cannot be represented as the type of val, the function calls setstate( failbit). In any case, it returns *this.

Example

// istream_basic_istream_op_is.cpp  
// compile with: /EHsc  
#include <iostream>  
  
using namespace std;  
  
ios_base& hex2( ios_base& ib )   
{  
   ib.unsetf( ios_base::dec );  
   ib.setf( ios_base::hex );  
   return ib;  
}  
  
basic_istream<char, char_traits<char> >& somefunc(basic_istream<char, char_traits<char> > &i)  
{  
   if ( i == cin )   
   {  
      cerr << "i is cin" << endl;  
   }  
   return i;  
}  
  
int main( )   
{  
   int i = 0;  
   cin >> somefunc;  
   cin >> i;  
   cout << i << endl;  
   cin >> hex2;  
   cin >> i;  
   cout << i << endl;  
}

basic_istream::operator=

Assigns the basic_istream on the right side of the operator to this object. This is a move assignment involving an rvalue reference that does not leave a copy behind.

basic_istream& operator=(basic_istream&& right);

Parameters

right
An rvalue reference to a basic_ifstream object.

Return Value

Returns *this.

Remarks

The member operator calls swap ( right).

basic_istream::peek

Returns the next character to be read.

int_type peek();

Return Value

The next character that will be read.

Remarks

The unformatted input function extracts an element, if possible, as if by returning rdbuf -> sgetc. Otherwise, it returns traits_type::eof.

Example

// basic_istream_peek.cpp  
// compile with: /EHsc  
#include <iostream>  
using namespace std;  
  
int main( )   
{  
   char c[10], c2;  
   cout << "Type 'abcde': ";  
  
   c2 = cin.peek( );  
   cin.getline( &c[0], 9 );  
  
   cout << c2 << " " << c << endl;  
}

  
abcde

  
      abcdeType 'abcde': abcde  
a abcde

basic_istream::putback

Puts a specified character into the stream.

basic_istream<Elem, Tr>& putback(
    char_type _Ch);

Parameters

_Ch
A character to put back into the stream.

Return Value

The stream ( *this).

Remarks

The unformatted input function puts back _Ch, if possible, as if by calling rdbuf->sputbackc. If rdbuf is a null pointer, or if the call to sputbackc returns traits_type::eof, the function calls setstate( badbit). In any case, it returns *this.

Example

// basic_istream_putback.cpp  
// compile with: /EHsc  
#include <iostream>  
using namespace std;  
  
int main( )   
{  
   char c[10], c2, c3;  
  
   c2 = cin.get( );  
   c3 = cin.get( );  
   cin.putback( c2 );  
   cin.getline( &c[0], 9 );  
   cout << c << endl;  
}

qwq

basic_istream::read

Reads a specified number of characters from the stream and stores them in an array.

This method is potentially unsafe, as it relies on the caller to check that the passed values are correct.

basic_istream<Elem, Tr>& read(
    char_type* str,   
    streamsize count);

Parameters

str
The array in which to read the characters.

count
The number of characters to read.

Return Value

The stream ( *this).

Remarks

The unformatted input function extracts up to count elements and stores them in the array beginning at _ Str. Extraction stops early on end of file, in which case the function calls setstate( failbit). In any case, it returns *this.

Example

// basic_istream_read.cpp  
// compile with: /EHsc  
#include <iostream>  
using namespace std;  
  
int main()  
{  
    char c[10];  
    int count = 5;  
  
    cout << "Type 'abcde': ";  
  
    // Note: cin::read is potentially unsafe, consider  
    // using cin::_Read_s instead.  
    cin.read(&c[0], count);  
    c[count] = 0;  
  
    cout << c << endl;  
}

  
abcde

  
      abcdeType 'abcde': abcde  
abcde

basic_istream::readsome

Reads the specified number of character values.

This method is potentially unsafe, as it relies on the caller to check that the passed values are correct.

streamsize readsome(
    char_type* str,  
    streamsize count);

Parameters

str
The array in which readsome stores the characters it reads.

count
The number of characters to read.

Return Value

The number of characters actually read, gcount.

Remarks

This unformatted input function extracts up to count elements from the input stream and stores them in the array str.

This function does not wait for input. It reads whatever data is available.

Example

// basic_istream_readsome.cpp  
// compile with: /EHsc /W3  
#include <iostream>  
using namespace std;  
  
int main( )  
{  
   char c[10];  
   int count = 5;  
  
   cout << "Type 'abcdefgh': ";  
  
   // cin.read blocks until user types input.  
   // Note: cin::read is potentially unsafe, consider  
   // using cin::_Read_s instead.  
   cin.read(&c[0], 2);  
  
   // Note: cin::readsome is potentially unsafe, consider  
   // using cin::_Readsome_s instead.  
   int n = cin.readsome(&c[0], count);  // C4996  
   c[n] = 0;  
   cout << n << " characters read" << endl;  
   cout << c << endl;  
}

basic_istream::seekg

Moves the read position in a stream.

basic_istream<Elem, Tr>& seekg(
    pos_type pos);

basic_istream<Elem, Tr>& seekg(
    off_type off,  
    ios_base::seekdir way);

Parameters

pos
The absolute position in which to move the read pointer.

off
An offset to move the read pointer relative to way.

way
One of the ios_base::seekdir enumerations.

Return Value

The stream ( *this).

Remarks

The first member function performs an absolute seek, the second member function performs a relative seek.

Note

Do not use the second member function with text files, because Standard C++ does not support relative seeks in text files.

If fail is false, the first member function calls newpos = rdbuf -> pubseekpos( pos), for some pos_type temporary object newpos. If fail is false, the second function calls newpos = rdbuf -> pubseekoff( off, way). In either case, if ( off_type) newpos == ( off_type)(-1) (the positioning operation fails), the function calls istr. setstate( failbit). Both functions return *this.

If fail is true, the member functions do nothing.

Example

// basic_istream_seekg.cpp  
// compile with: /EHsc  
#include <iostream>  
#include <fstream>  
  
int main ( )   
{  
   using namespace std;  
   ifstream file;  
   char c, c1;  
  
   file.open( "basic_istream_seekg.txt" );  
   file.seekg(2);   // seek to position 2  
   file >> c;  
   cout << c << endl;  
}

basic_istream::sentry

The nested class describes an object whose declaration structures the formatted and unformatted input functions.

class sentry {
public:
explicit sentry( basic_istream<Elem, Tr>& _Istr,
bool _Noskip = false); operator bool() const; };

Remarks

If _Istr``.good is true, the constructor:

Calls _Istr. tie -> flush if _Istr. tie is not a null pointer
Effectively calls ws( _Istr) if _Istr. flags&skipws is nonzero

If, after any such preparation, _Istr. good is false, the constructor calls _Istr. setstate( failbit). In any case, the constructor stores the value returned by _Istr. good in status. A later call to operator bool delivers this stored value.

basic_istream::swap

Exchanges the contents of two basic_istream objects.

void swap(basic_istream& right);

Parameters

right
An lvalue reference to a basic_istream object.

Remarks

The member function calls basic_ios::swap(`` right``). It also exchanges the extraction count with the extraction count for right.

basic_istream::sync

Synchronizes the input device associated with the stream with the stream's buffer.

int sync();

Return Value

If rdbuf is a null pointer, the function returns -1. Otherwise, it calls rdbuf -> pubsync. If that returns -1, the function calls setstate( badbit) and returns -1. Otherwise, the function returns zero.

basic_istream::tellg

Reports the current read position in the stream.

pos_type tellg();

Return Value

The current position in the stream.

Remarks

If fail is false, the member function returns rdbuf -> pubseekoff(0, cur, in). Otherwise, it returns pos_type(-1).

Example

// basic_istream_tellg.cpp  
// compile with: /EHsc  
#include <iostream>  
#include <fstream>  
  
int main()  
{  
    using namespace std;  
    ifstream file;  
    char c;  
    streamoff i;  
  
    file.open("basic_istream_tellg.txt");  
    i = file.tellg();  
    file >> c;  
    cout << c << " " << i << endl;  
  
    i = file.tellg();  
    file >> c;  
    cout << c << " " << i << endl;  
}

basic_istream::unget

Puts the most recently read character back into the stream.

basic_istream<Elem, Tr>& unget();

Return Value

The stream ( *this).

Remarks

The unformatted input function puts back the previous element in the stream, if possible, as if by calling rdbuf -> sungetc. If rdbuf is a null pointer, or if the call to sungetc returns traits_type::eof, the function calls setstate( badbit). In any case, it returns *this.

For information on how unget might fail, see basic_streambuf::sungetc.

Example

// basic_istream_unget.cpp  
// compile with: /EHsc  
#include <iostream>  
using namespace std;  
  
int main( )   
{  
   char c[10], c2;  
  
   cout << "Type 'abc': ";  
   c2 = cin.get( );  
   cin.unget( );  
   cin.getline( &c[0], 9 );  
   cout << c << endl;  
}

abc

  
      abcType 'abc': abc  
abc

basic_istream Class

Syntax

Remarks

Example

Constructors

Member Functions

Operators

Requirements

basic_istream::basic_istream

Parameters

Remarks

Example

basic_istream::gcount

Return Value

Remarks

Example

basic_istream::get

Parameters

Return Value

Remarks

Example

basic_istream::getline

Parameters

Return Value

Remarks

Example

basic_istream::ignore

Parameters

Return Value

Remarks

Example

basic_istream::operator>>

Parameters

Return Value

Remarks

Example

basic_istream::operator=

Parameters

Return Value

Remarks

basic_istream::peek

Return Value

Remarks

Example

basic_istream::putback

Parameters

Return Value

Remarks

Example

basic_istream::read

Parameters

Return Value

Remarks

Example

basic_istream::readsome

Parameters

Return Value

Remarks

Example

basic_istream::seekg

Parameters

Return Value

Remarks

Example

basic_istream::sentry

Remarks

basic_istream::swap

Parameters

Remarks

basic_istream::sync

Return Value

basic_istream::tellg

Return Value

Remarks

Example

basic_istream::unget

Return Value

Remarks

Example

See Also