libstdc++
std::basic_istringstream Class Reference
Inheritance diagram for std::basic_istringstream:

List of all members.

Public Types

Public Member Functions

Arithmetic Extractors

All the operator>> functions (aka formatted input functions) have some common behavior. Each starts by constructing a temporary object of type std::basic_istream::sentry with the second argument (noskipws) set to false. This has several effects, concluding with the setting of a status flag; see the sentry documentation for more.

If the sentry status is good, the function tries to extract whatever data is appropriate for the type of the argument.

If an exception is thrown during extraction, ios_base::badbit will be turned on in the stream's error state without causing an ios_base::failure to be thrown. The original exception will then be rethrown.

Unformatted Input Functions

All the unformatted input functions have some common behavior. Each starts by constructing a temporary object of type std::basic_istream::sentry with the second argument (noskipws) set to true. This has several effects, concluding with the setting of a status flag; see the sentry documentation for more.

If the sentry status is good, the function tries to extract whatever data is appropriate for the type of the argument.

The number of characters extracted is stored for later retrieval by gcount().

If an exception is thrown during extraction, ios_base::badbit will be turned on in the stream's error state without causing an ios_base::failure to be thrown. The original exception will then be rethrown.

Protected Member Functions

Protected Attributes

Friends


Detailed Description

Controlling input for std::string.

This class supports reading from objects of type std::basic_string, using the inherited functions from std::basic_istream. To control the associated sequence, an instance of std::basic_stringbuf is used, which this page refers to as sb.


Constructor & Destructor Documentation

std::basic_istringstream::basic_istringstream ( ios_base::openmode  __mode = ios_base::in) [inline, explicit]

Default constructor starts with an empty string buffer.

Parameters:
modeWhether the buffer can read, or write, or both.

ios_base::in is automatically included in mode.

Initializes sb using mode|in, and passes &sb to the base class initializer. Does not allocate any buffer.

That's a lie. We initialize the base class with NULL, because the string class does its own memory management.

Definition at line 299 of file sstream.

std::basic_istringstream::basic_istringstream ( const __string_type __str,
ios_base::openmode  __mode = ios_base::in 
) [inline, explicit]

Starts with an existing string buffer.

Parameters:
strA string to copy as a starting buffer.
modeWhether the buffer can read, or write, or both.

ios_base::in is automatically included in mode.

Initializes sb using str and mode|in, and passes &sb to the base class initializer.

That's a lie. We initialize the base class with NULL, because the string class does its own memory management.

Definition at line 317 of file sstream.

std::basic_istringstream::~basic_istringstream ( ) [inline]

The destructor does nothing.

The buffer is deallocated by the stringbuf object, not the formatting stream.

Definition at line 328 of file sstream.


Member Function Documentation

streamsize std::basic_istream::gcount ( ) const [inline, inherited]

Character counting.

Returns:
The number of characters extracted by the previous unformatted input function dispatched for this stream.

Definition at line 251 of file istream.

int_type std::basic_istream::get ( void  ) [inherited]

Simple extraction.

Returns:
A character, or eof().

Tries to extract a character. If none are available, sets failbit and returns traits::eof().

__istream_type& std::basic_istream::get ( char_type __c) [inherited]

Simple extraction.

Parameters:
cThe character in which to store data.
Returns:
*this

Tries to extract a character and store it in c. If none are available, sets failbit and returns traits::eof().

Note:
This function is not overloaded on signed char and unsigned char.
__istream_type& std::basic_istream::get ( char_type __s,
streamsize  __n,
char_type  __delim 
) [inherited]

Simple multiple-character extraction.

Parameters:
sPointer to an array.
nMaximum number of characters to store in s.
delimA "stop" character.
Returns:
*this

Characters are extracted and stored into s until one of the following happens:

  • n-1 characters are stored
  • the input sequence reaches EOF
  • the next character equals delim, in which case the character is not extracted

If no characters are stored, failbit is set in the stream's error state.

In any case, a null character is stored into the next location in the array.

Note:
This function is not overloaded on signed char and unsigned char.
__istream_type& std::basic_istream::get ( char_type __s,
streamsize  __n 
) [inline, inherited]

Simple multiple-character extraction.

Parameters:
sPointer to an array.
nMaximum number of characters to store in s.
Returns:
*this

Returns get(s,n,widen('\n')).

Definition at line 335 of file istream.

__istream_type& std::basic_istream::get ( __streambuf_type __sb,
char_type  __delim 
) [inherited]

Extraction into another streambuf.

Parameters:
sbA streambuf in which to store data.
delimA "stop" character.
Returns:
*this

Characters are extracted and inserted into sb until one of the following happens:

  • the input sequence reaches EOF
  • insertion into the output buffer fails (in this case, the character that would have been inserted is not extracted)
  • the next character equals delim (in this case, the character is not extracted)
  • an exception occurs (and in this case is caught)

If no characters are stored, failbit is set in the stream's error state.

__istream_type& std::basic_istream::get ( __streambuf_type __sb) [inline, inherited]

Extraction into another streambuf.

Parameters:
sbA streambuf in which to store data.
Returns:
*this

Returns get(sb,widen('\n')).

Definition at line 368 of file istream.

__istream_type& std::basic_istream::getline ( char_type __s,
streamsize  __n,
char_type  __delim 
) [inherited]

String extraction.

Parameters:
sA character array in which to store the data.
nMaximum number of characters to extract.
delimA "stop" character.
Returns:
*this

Extracts and stores characters into s until one of the following happens. Note that these criteria are required to be tested in the order listed here, to allow an input line to exactly fill the s array without setting failbit.

  1. the input sequence reaches end-of-file, in which case eofbit is set in the stream error state
  2. the next character equals delim, in which case the character is extracted (and therefore counted in gcount()) but not stored
  3. n-1 characters are stored, in which case failbit is set in the stream error state

If no characters are extracted, failbit is set. (An empty line of input should therefore not cause failbit to be set.)

In any case, a null character is stored in the next location in the array.

__istream_type& std::basic_istream::getline ( char_type __s,
streamsize  __n 
) [inline, inherited]

String extraction.

Parameters:
sA character array in which to store the data.
nMaximum number of characters to extract.
Returns:
*this

Returns getline(s,n,widen('\n')).

Definition at line 408 of file istream.

__istream_type& std::basic_istream::ignore ( void  ) [inherited]

Discarding characters.

Parameters:
nNumber of characters to discard.
delimA "stop" character.
Returns:
*this

Extracts characters and throws them away until one of the following happens:

  • if n != std::numeric_limits<int>::max(), n characters are extracted
  • the input sequence reaches end-of-file
  • the next character equals delim (in this case, the character is extracted); note that this condition will never occur if delim equals traits::eof().

NB: Provide three overloads, instead of the single function (with defaults) mandated by the Standard: this leads to a better performing implementation, while still conforming to the Standard.

__istream_type& std::basic_istream::ignore ( streamsize  __n) [inherited]

Simple extraction.

Returns:
A character, or eof().

Tries to extract a character. If none are available, sets failbit and returns traits::eof().

__istream_type& std::basic_istream::ignore ( streamsize  __n,
int_type  __delim 
) [inherited]

Simple extraction.

Returns:
A character, or eof().

Tries to extract a character. If none are available, sets failbit and returns traits::eof().

__istream_type& std::basic_istream::operator>> ( __istream_type &(*)(__istream_type &)  __pf) [inline, inherited]

Interface for manipulators.

Manipulators such as std::ws and std::dec use these functions in constructs like std::cin >> std::ws. For more information, see the iomanip header.

Definition at line 122 of file istream.

__istream_type& std::basic_istream::operator>> ( __ios_type &(*)(__ios_type &)  __pf) [inline, inherited]

Interface for manipulators.

Manipulators such as std::ws and std::dec use these functions in constructs like std::cin >> std::ws. For more information, see the iomanip header.

Definition at line 126 of file istream.

__istream_type& std::basic_istream::operator>> ( ios_base &(*)(ios_base &)  __pf) [inline, inherited]

Interface for manipulators.

Manipulators such as std::ws and std::dec use these functions in constructs like std::cin >> std::ws. For more information, see the iomanip header.

Definition at line 133 of file istream.

__istream_type& std::basic_istream::operator>> ( bool &  __n) [inline, inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

Definition at line 169 of file istream.

__istream_type& std::basic_istream::operator>> ( short &  __n) [inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

__istream_type& std::basic_istream::operator>> ( unsigned short &  __n) [inline, inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

Definition at line 176 of file istream.

__istream_type& std::basic_istream::operator>> ( int &  __n) [inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

__istream_type& std::basic_istream::operator>> ( unsigned int &  __n) [inline, inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

Definition at line 183 of file istream.

__istream_type& std::basic_istream::operator>> ( long &  __n) [inline, inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

Definition at line 187 of file istream.

__istream_type& std::basic_istream::operator>> ( unsigned long &  __n) [inline, inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

Definition at line 191 of file istream.

__istream_type& std::basic_istream::operator>> ( long long &  __n) [inline, inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

Definition at line 196 of file istream.

__istream_type& std::basic_istream::operator>> ( unsigned long long &  __n) [inline, inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

Definition at line 200 of file istream.

__istream_type& std::basic_istream::operator>> ( float &  __f) [inline, inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

Definition at line 205 of file istream.

__istream_type& std::basic_istream::operator>> ( double &  __f) [inline, inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

Definition at line 209 of file istream.

__istream_type& std::basic_istream::operator>> ( long double &  __f) [inline, inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

Definition at line 213 of file istream.

__istream_type& std::basic_istream::operator>> ( void *&  __p) [inline, inherited]

Basic arithmetic extractors.

Parameters:
Avariable of builtin type.
Returns:
*this if successful

These functions use the stream's current locale (specifically, the num_get facet) to parse the input data.

Definition at line 217 of file istream.

__istream_type& std::basic_istream::operator>> ( __streambuf_type __sb) [inherited]

Extracting into another streambuf.

Parameters:
sbA pointer to a streambuf

This function behaves like one of the basic arithmetic extractors, in that it also constructs a sentry object and has the same error handling behavior.

If sb is NULL, the stream will set failbit in its error state.

Characters are extracted from this stream and inserted into the sb streambuf until one of the following occurs:

  • the input stream reaches end-of-file,
  • insertion into the output buffer fails (in this case, the character that would have been inserted is not extracted), or
  • an exception occurs (and in this case is caught)

If the function inserts no characters, failbit is set.

int_type std::basic_istream::peek ( void  ) [inherited]

Looking ahead in the stream.

Returns:
The next character, or eof().

If, after constructing the sentry object, good() is false, returns traits::eof(). Otherwise reads but does not extract the next input character.

__istream_type& std::basic_istream::putback ( char_type  __c) [inherited]

Unextracting a single character.

Parameters:
cThe character to push back into the input stream.
Returns:
*this

If rdbuf() is not null, calls rdbuf()->sputbackc(c).

If rdbuf() is null or if sputbackc() fails, sets badbit in the error state.

Note:
This function first clears eofbit. Since no characters are extracted, the next call to gcount() will return 0, as required by DR 60.
__stringbuf_type* std::basic_istringstream::rdbuf ( ) const [inline]

Accessing the underlying buffer.

Returns:
The current basic_stringbuf buffer.

This hides both signatures of std::basic_ios::rdbuf().

Definition at line 339 of file sstream.

__istream_type& std::basic_istream::read ( char_type __s,
streamsize  __n 
) [inherited]

Extraction without delimiters.

Parameters:
sA character array.
nMaximum number of characters to store.
Returns:
*this

If the stream state is good(), extracts characters and stores them into s until one of the following happens:

  • n characters are stored
  • the input sequence reaches end-of-file, in which case the error state is set to failbit|eofbit.
Note:
This function is not overloaded on signed char and unsigned char.
streamsize std::basic_istream::readsome ( char_type __s,
streamsize  __n 
) [inherited]

Extraction until the buffer is exhausted, but no more.

Parameters:
sA character array.
nMaximum number of characters to store.
Returns:
The number of characters extracted.

Extracts characters and stores them into s depending on the number of characters remaining in the streambuf's buffer, rdbuf()->in_avail(), called A here:

  • if A == -1, sets eofbit and extracts no characters
  • if A == 0, extracts no characters
  • if A > 0, extracts min(A,n)

The goal is to empty the current buffer, and to not request any more from the external input sequence controlled by the streambuf.

__istream_type& std::basic_istream::seekg ( pos_type  ) [inherited]

Changing the current read position.

Parameters:
posA file position object.
Returns:
*this

If fail() is not true, calls rdbuf()->pubseekpos(pos). If that function fails, sets failbit.

Note:
This function first clears eofbit. It does not count the number of characters extracted, if any, and therefore does not affect the next call to gcount().
__istream_type& std::basic_istream::seekg ( off_type  ,
ios_base::seekdir   
) [inherited]

Changing the current read position.

Parameters:
offA file offset object.
dirThe direction in which to seek.
Returns:
*this

If fail() is not true, calls rdbuf()->pubseekoff(off,dir). If that function fails, sets failbit.

Note:
This function first clears eofbit. It does not count the number of characters extracted, if any, and therefore does not affect the next call to gcount().
__string_type std::basic_istringstream::str ( ) const [inline]

Copying out the string buffer.

Returns:
rdbuf()->str()

Definition at line 347 of file sstream.

References std::basic_stringbuf::str().

void std::basic_istringstream::str ( const __string_type __s) [inline]

Setting a new buffer.

Parameters:
sThe string to use as a new sequence.

Calls rdbuf()->str(s).

Definition at line 357 of file sstream.

References std::basic_stringbuf::str().

int std::basic_istream::sync ( void  ) [inherited]

Synchronizing the stream buffer.

Returns:
0 on success, -1 on failure

If rdbuf() is a null pointer, returns -1.

Otherwise, calls rdbuf()->pubsync(), and if that returns -1, sets badbit and returns -1.

Otherwise, returns 0.

Note:
This function does not count the number of characters extracted, if any, and therefore does not affect the next call to gcount().
pos_type std::basic_istream::tellg ( void  ) [inherited]

Getting the current read position.

Returns:
A file position object.

If fail() is not false, returns pos_type(-1) to indicate failure. Otherwise returns rdbuf()->pubseekoff(0,cur,in).

Note:
This function does not count the number of characters extracted, if any, and therefore does not affect the next call to gcount(). At variance with putback, unget and seekg, eofbit is not cleared first.
__istream_type& std::basic_istream::unget ( void  ) [inherited]

Unextracting the previous character.

Returns:
*this

If rdbuf() is not null, calls rdbuf()->sungetc(c).

If rdbuf() is null or if sungetc() fails, sets badbit in the error state.

Note:
This function first clears eofbit. Since no characters are extracted, the next call to gcount() will return 0, as required by DR 60.

Member Data Documentation

streamsize std::basic_istream::_M_gcount [protected, inherited]

The number of characters extracted in the previous unformatted function; see gcount().

Definition at line 81 of file istream.


The documentation for this class was generated from the following file: