istream - Member Functions and Data by Group

Constructors & Destructor

Objects of the istream class can be constructed and destructed.

~istream
public:virtual ~istream()

This is supported on AIX OS/400 z/OS

Destructs an istream object.

istream
Overload 1
public:istream(streambuf*, int sk, ostream* t = 0)

This is supported on AIX OS/400 z/OS

Obsolete. Do not use.

Overload 2
public:istream(streambuf*)

This is supported on AIX OS/400 z/OS

This constructor takes a single argument, a pointer to a streambuf, and creates an istream object that is attached to the streambuf object. The constructor also initializes the format variables to their defaults.

Note: The other istream constructor declarations in iostream.h are obsolete; do not use them.

Overload 3
public:istream(int size, char*, int sk = 1)

This is supported on AIX OS/400 z/OS

Obsolete. Do not use.

Overload 4
public:istream(int fd, int sk = 1, ostream* t = 0)

This is supported on AIX OS/400 z/OS

Obsolete. Do not use.

Overload 5
protected:istream()

This is supported on AIX OS/400 z/OS

Obsolete. Do not use.

Extract Functions

You can use the extract functions to extract characters from a stream buffer as a sequence of bytes. All of these functions call ipfx(1). They only proceed with their processing if ipfx(1) returns a nonzero value.

gcount

Returns the number of characters extracted from the stream buffer by the last call to an unformatted input function. The input operator >> may call unformatted input functions, and thus formatted input may affect the value returned by gcount().

Overload 1
public:int gcount()

This is supported on AIX OS/400 z/OS

AIX and z/OS Considerations

This function returns an int value for 32-bit applications. It is not available for 64-bit applications.

Overload 2
public:long gcount()

This is supported on AIX z/OS

This function returns a long value for 64-bit applications. It is not available for 32-bit applications.

get
Overload 1
public:int get()

This is supported on AIX OS/400 z/OS

Extracts a single character from the stream buffer attached to the istream object and returns it. Returns EOF if EOF is extracted. ios::failbit is never set.

Overload 2
public:istream& get(char*, int lim, char delim = '\n')

This is supported on AIX OS/400 z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the byte array beginning at the location pointed to by the first argument and extending for lim bytes. The default value of the delim argument is '\n'. Extraction stops when either of the following conditions is true:

  • delim or EOF is encountered before lim - 1 characters have been stored in the array. delim is left in the stream buffer and not stored in the array.
  • lim - 1 characters are extracted without delim or EOF being encountered.

get() always stores a terminating null character in the array, even if it does not extract any characters from the stream buffer. ios::failbit is set if EOF is encountered before any characters are stored.

AIX and z/OS Considerations

This function is available for 32-bit applications. The second argument is an int value.

Overload 3
public:istream& get(unsigned char& c)

This is supported on AIX OS/400 z/OS

Extracts a single character from the stream buffer attached to the istream object and stores this character in c.

Overload 4
public:istream& get(signed char* b, int lim, char delim = '\n')

This is supported on AIX OS/400 z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the byte array beginning at the location pointed to by the first argument and extending for lim bytes. The default value of the delim argument is '\n'. Extraction stops when either of the following conditions is true:

  • delim or EOF is encountered before lim - 1 characters have been stored in the array. delim is left in the stream buffer and not stored in the array.
  • lim - 1 characters are extracted without delim or EOF being encountered.

get() always stores a terminating null character in the array, even if it does not extract any characters from the stream buffer. ios::failbit is set if EOF is encountered before any characters are stored.

AIX and z/OS Considerations

This function is available for 32-bit applications. The second argument is an int value.

Overload 5
public:istream& get(streambuf& sb, char delim = '\n')

This is supported on AIX OS/400 z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the streambuf, sb. The default value of the delim argument is '\n'. Extraction stops when any of the following conditions is true:

  • an EOF character is encountered
  • an attempt to store a character in sb fails
  • ios::failbit is set in the error state of the istream object
  • delim is encountered. delim is left in the stream buffer attached to the istream object.
Overload 6
public:istream& get(unsigned char* b, long lim, char delim = '\n')

This is supported on AIX z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the byte array beginning at the location pointed to by the first argument and extending for lim bytes. The default value of the delim argument is '\n'. Extraction stops when either of the following conditions is true:

  • delim or EOF is encountered before lim - 1 characters have been stored in the array. delim is left in the stream buffer and not stored in the array.
  • lim - 1 characters are extracted without delim or EOF being encountered.

get() always stores a terminating null character in the array, even if it does not extract any characters from the stream buffer. ios::failbit is set if EOF is encountered before any characters are stored.

This function is available for 64-bit applications. The second argument is a long value.

Overload 7
public:istream& get(char& c)

This is supported on AIX OS/400 z/OS

Extracts a single character from the stream buffer attached to the istream object and stores this character in c.

Overload 8
public:istream& get(signed char& c)

This is supported on AIX OS/400 z/OS

Extracts a single character from the stream buffer attached to the istream object and stores this character in c.

Overload 9
public:istream& get(wchar_t&)

This is supported on AIX OS/400 z/OS

Extracts a single wchar_t character from the stream buffer attached to the istream object and stores this character in c.

Overload 10
public:istream& get(unsigned char* b, int lim, char delim = '\n')

This is supported on AIX OS/400 z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the byte array beginning at the location pointed to by the first argument and extending for lim bytes. The default value of the delim argument is '\n'. Extraction stops when either of the following conditions is true:

  • delim or EOF is encountered before lim - 1 characters have been stored in the array. delim is left in the stream buffer and not stored in the array.
  • lim - 1 characters are extracted without delim or EOF being encountered.

get() always stores a terminating null character in the array, even if it does not extract any characters from the stream buffer. ios::failbit is set if EOF is encountered before any characters are stored.

AIX and z/OS Considerations

This function is available for 32-bit applications. The second argument is an int value.

Overload 11
public:istream& get(signed char* b, long lim, char delim = '\n')

This is supported on AIX z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the byte array beginning at the location pointed to by the first argument and extending for lim bytes. The default value of the delim argument is '\n'. Extraction stops when either of the following conditions is true:

  • delim or EOF is encountered before lim - 1 characters have been stored in the array. delim is left in the stream buffer and not stored in the array.
  • lim - 1 characters are extracted without delim or EOF being encountered.

get() always stores a terminating null character in the array, even if it does not extract any characters from the stream buffer. ios::failbit is set if EOF is encountered before any characters are stored.

This function is available for 64-bit applications. The second argument is a long value.

Overload 12
public:istream& get(char*, long lim, char delim = '\n')

This is supported on AIX z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the byte array beginning at the location pointed to by the first argument and extending for lim bytes. The default value of the delim argument is '\n'. Extraction stops when either of the following conditions is true:

  • delim or EOF is encountered before lim - 1 characters have been stored in the array. delim is left in the stream buffer and not stored in the array.
  • lim - 1 characters are extracted without delim or EOF being encountered.

get() always stores a terminating null character in the array, even if it does not extract any characters from the stream buffer. ios::failbit is set if EOF is encountered before any characters are stored.

This function is available for 64-bit applications. The second argument is a long value.

get_complicated
Overload 1
public:istream& get_complicated(signed char& c)

This is supported on AIX OS/400 z/OS

Internal function. Do not use.

Overload 2
public:istream& get_complicated(unsigned char& c)

This is supported on AIX OS/400 z/OS

Internal function. Do not use.

Overload 3
public:istream& get_complicated(char& c)

This is supported on AIX OS/400 z/OS

Internal function. Do not use.

getline
Overload 1
public:istream&
  getline( unsigned char* b,
           int lim,
           char delim = '\n' )

This is supported on AIX OS/400 z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the byte array beginning at the location pointed to by the first argument and extending for lim bytes. The default value of the delim argument is '\n'. Extraction stops when either of the following conditions is true:

  • delim or EOF is encountered before lim - 1 characters have been stored in the array. getline() extracts delim from the stream buffer, but it does not store delim in the array.
  • lim - 1 characters are extracted before delim or EOF is encountered.

getline() always stores a terminating null character in the array, even if it does not extract any characters from the stream buffer. ios::failbit is set if EOF is encountered before any characters are stored.

getline() is like get() with three arguments, except that get() does not extract the delim character from the stream buffer, while getline() does.

AIX and z/OS Considerations

This function is available for 32-bit applications. The second argument is an int value.

Overload 2
public:istream&
  getline( unsigned char* b,
           long lim,
           char delim = '\n' )

This is supported on AIX z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the byte array beginning at the location pointed to by the first argument and extending for lim bytes. The default value of the delim argument is '\n'. Extraction stops when either of the following conditions is true:

  • delim or EOF is encountered before lim - 1 characters have been stored in the array. getline() extracts delim from the stream buffer, but it does not store delim in the array.
  • lim - 1 characters are extracted before delim or EOF is encountered.

getline() always stores a terminating null character in the array, even if it does not extract any characters from the stream buffer. ios::failbit is set if EOF is encountered before any characters are stored.

getline() is like get() with three arguments, except that get() does not extract the delim character from the stream buffer, while getline() does.

This function is available for 64-bit applications. The second argument is a long value.

Overload 3
public:istream& getline(char* b, int lim, char delim = '\n')

This is supported on AIX OS/400 z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the byte array beginning at the location pointed to by the first argument and extending for lim bytes. The default value of the delim argument is '\n'. Extraction stops when either of the following conditions is true:

  • delim or EOF is encountered before lim - 1 characters have been stored in the array. getline() extracts delim from the stream buffer, but it does not store delim in the array.
  • lim - 1 characters are extracted before delim or EOF is encountered.

getline() always stores a terminating null character in the array, even if it does not extract any characters from the stream buffer. ios::failbit is set if EOF is encountered before any characters are stored.

getline() is like get() with three arguments, except that get() does not extract the delim character from the stream buffer, while getline() does.

AIX and z/OS Considerations

This function is available for 32-bit applications. The second argument is an int value.

Overload 4
public:istream& getline(char* b, long lim, char delim = '\n')

This is supported on AIX z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the byte array beginning at the location pointed to by the first argument and extending for lim bytes. The default value of the delim argument is '\n'. Extraction stops when either of the following conditions is true:

  • delim or EOF is encountered before lim - 1 characters have been stored in the array. getline() extracts delim from the stream buffer, but it does not store delim in the array.
  • lim - 1 characters are extracted before delim or EOF is encountered.

getline() always stores a terminating null character in the array, even if it does not extract any characters from the stream buffer. ios::failbit is set if EOF is encountered before any characters are stored.

getline() is like get() with three arguments, except that get() does not extract the delim character from the stream buffer, while getline() does.

This function is available for 64-bit applications. The second argument is a long value.

Overload 5
public:istream&
  getline( signed char* b,
           int lim,
           char delim = '\n' )

This is supported on AIX OS/400 z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the byte array beginning at the location pointed to by the first argument and extending for lim bytes. The default value of the delim argument is '\n'. Extraction stops when either of the following conditions is true:

  • delim or EOF is encountered before lim - 1 characters have been stored in the array. getline() extracts delim from the stream buffer, but it does not store delim in the array.
  • lim - 1 characters are extracted before delim or EOF is encountered.

getline() always stores a terminating null character in the array, even if it does not extract any characters from the stream buffer. ios::failbit is set if EOF is encountered before any characters are stored.

getline() is like get() with three arguments, except that get() does not extract the delim character from the stream buffer, while getline() does.

AIX and z/OS Considerations

This function is available for 32-bit applications. The second argument is an int value.

Overload 6
public:istream&
  getline( signed char* b,
           long lim,
           char delim = '\n' )

This is supported on AIX z/OS

Extracts characters from the stream buffer attached to the istream object and stores them in the byte array beginning at the location pointed to by the first argument and extending for lim bytes. The default value of the delim argument is '\n'. Extraction stops when either of the following conditions is true:

  • delim or EOF is encountered before lim - 1 characters have been stored in the array. getline() extracts delim from the stream buffer, but it does not store delim in the array.
  • lim - 1 characters are extracted before delim or EOF is encountered.

getline() always stores a terminating null character in the array, even if it does not extract any characters from the stream buffer. ios::failbit is set if EOF is encountered before any characters are stored.

getline() is like get() with three arguments, except that get() does not extract the delim character from the stream buffer, while getline() does.

This function is available for 64-bit applications. The second argument is a long value.

ignore
public:istream& ignore(int n = 1, int delim = EOF)

This is supported on AIX OS/400 z/OS

Extracts up to n characters from the stream buffer attached to the istream object and discards them. ignore() will extract fewer than n characters if it encounters delim or EOF.

peek
public:int peek()

This is supported on AIX OS/400 z/OS

peek() calls ipfx(1). If ipfx() returns 0, or if no more input is available from the ultimate producer, peek() returns EOF. Otherwise, it returns the next character in the stream buffer without extracting the character.

read
Overload 1
public:istream& read(char* s, long n)

This is supported on AIX z/OS

Extracts n characters from the stream buffer attached to the istream object and stores them in an array beginning at the position pointed to by s. If EOF is encountered before read() extracts n characters, read() sets the ios::failbit in the error state of the istream object. You can determine the number of characters that read() extracted by calling gcount() immediately after the call to read().

This function is available for 64-bit applications. The second argument is a long value.

Overload 2
public:istream& read(signed char* s, int n)

This is supported on AIX OS/400 z/OS

Extracts n characters from the stream buffer attached to the istream object and stores them in an array beginning at the position pointed to by s. If EOF is encountered before read() extracts n characters, read() sets the ios::failbit in the error state of the istream object. You can determine the number of characters that read() extracted by calling gcount() immediately after the call to read().

AIX and z/OS Considerations

This function is available for 32-bit applications. The second argument is an int value.

Overload 3
public:istream& read(unsigned char* s, long n)

This is supported on AIX z/OS

Extracts n characters from the stream buffer attached to the istream object and stores them in an array beginning at the position pointed to by s. If EOF is encountered before read() extracts n characters, read() sets the ios::failbit in the error state of the istream object. You can determine the number of characters that read() extracted by calling gcount() immediately after the call to read().

This function is available for 64-bit applications. The second argument is a long value.

Overload 4
public:istream& read(unsigned char* s, int n)

This is supported on AIX OS/400 z/OS

Extracts n characters from the stream buffer attached to the istream object and stores them in an array beginning at the position pointed to by s. If EOF is encountered before read() extracts n characters, read() sets the ios::failbit in the error state of the istream object. You can determine the number of characters that read() extracted by calling gcount() immediately after the call to read().

AIX and z/OS Considerations

This function is available for 32-bit applications. The second argument is an int value.

Overload 5
public:istream& read(signed char* s, long n)

This is supported on AIX z/OS

Extracts n characters from the stream buffer attached to the istream object and stores them in an array beginning at the position pointed to by s. If EOF is encountered before read() extracts n characters, read() sets the ios::failbit in the error state of the istream object. You can determine the number of characters that read() extracted by calling gcount() immediately after the call to read().

This function is available for 64-bit applications. The second argument is a long value.

Overload 6
public:istream& read(char* s, int n)

This is supported on AIX OS/400 z/OS

Extracts n characters from the stream buffer attached to the istream object and stores them in an array beginning at the position pointed to by s. If EOF is encountered before read() extracts n characters, read() sets the ios::failbit in the error state of the istream object. You can determine the number of characters that read() extracted by calling gcount() immediately after the call to read().

AIX and z/OS Considerations

This function is available for 32-bit applications. The second argument is an int value.

rs_complicated
Overload 1
public:istream& rs_complicated(signed char& c)

This is supported on AIX OS/400 z/OS

Internal function. Do not use.

Overload 2
public:istream& rs_complicated(char& c)

This is supported on AIX OS/400 z/OS

Internal function. Do not use.

Overload 3
public:istream& rs_complicated(unsigned char& c)

This is supported on AIX OS/400 z/OS

Internal function. Do not use.

eatwhite
protected:void eatwhite()

This is supported on AIX OS/400 z/OS

Internal function. Do not use.

Input Operators

Input operators supported by istream objects.

operator >>
Overload 1
public:istream& operator >>(float&)

This is supported on AIX OS/400 z/OS

The input operator converts characters from the stream buffer attached to the input stream according to the C++ lexical conventions.

The following conversions occur for certain string values:

  • If the value consists of the character strings "inf" or "infinity" in any combination of uppercase and lowercase letters, the string is converted to the approprate type's representation of infinity.
  • If the value consists of the character string "nan" in any combination of uppercase and lowercase letters, the string is converted to the appropriate type's representation of a NaN.

Note that if you use thse string values as input in a program compiled with z/OS C/C++, the input operator will not recognize them as floating point numbers and will set ios::badbit in the stream's error state.

The resulting value is stored in the reference location provided. The input operator sets ios::failbit if no digits are available in the stream buffer or if the digits that are available do not begin a floating-point number.

Overload 2
public:istream& operator >>(char*)

This is supported on AIX OS/400 z/OS

The input operator stores characters from the stream buffer attached to the input stream in the array pointed to by the argument. The input operator stores characters until a white-space character is found. This white-space character is left in the stream buffer, and the extraction stops. If ios::x_width does not equal 0, a maximum of ios::x_width - 1 characters are extracted. The input operator calls width(0) to reset the ios::x_width to 0.

The input operator always stores a terminating null character in the array, even if an error occurs.

Overload 3
public:istream& operator >>(int&)

This is supported on AIX OS/400 z/OS

The input operator extracts characters from the stream buffer associated with the input stream and converts them according to the format state of the input stream. The converted characters are then store in the reference location provided. There is no overflow detection on conversion of integral types.

The first character extracted from the stream buffer may be a sign (+ or -). The subsequent characters are converted until a nondigit character is encountered. This nondigit character is left in the stream buffer. Which characters are treated as digits depends on the setting of the following format flags:

  • ios::oct - the characters are converted to an octal value. Characters are extracted from the stream buffer until a character that is not an octal digit (a digit from 0 to 7) is encountered. If ios::oct is set and a signed value is encountered, the value is converted into a decimal value.
  • ios::dec - the characters are converted to a decimal value. Characters are extracted from the stream buffer until a character that is not a decimal digit (a digit from 0 to 9) is encountered.
  • ios::hex - the characters are converted to an hexadecimal value. Characters are extracted from the stream buffer until a character that is not a hexadecimal digit (a digit from 0 to 0 or a letter from "A" to "F", upper or lower case) is encountered. If ios::hex is set and a signed value is encountered, the value is converted into a decimal value.

If none of these format flags is set, the characters are converted according to the C++ lexical conventions. This conversion depends on the characters that follow the optional sign:

  • If these characters are "0x" or "0X", the subsequent characters are converted to a hexadecimal value.
  • If the first character is "0" and the second character is not a "x" or "X", the subsequent characters are converted to an octal value.
  • If neither of these cases is true, the characters are converted to a decimal value.

If no digits are available in the stream buffer (other than the "0" in "0X" or "0x" preceding a hexadecimal value), the input operator sets ios::failbit in the error state of the input stream.

Overload 4
public:istream& operator >>(long double&)

This is supported on AIX OS/400 z/OS

The input operator converts characters from the stream buffer attached to the input stream according to the C++ lexical conventions.

The following conversions occur for certain string values:

  • If the value consists of the character strings "inf" or "infinity" in any combination of uppercase and lowercase letters, the string is converted to the approprate type's representation of infinity.
  • If the value consists of the character string "nan" in any combination of uppercase and lowercase letters, the string is converted to the appropriate type's representation of a NaN.

Note that if you use thse string values as input in a program compiled with z/OS C/C++, the input operator will not recognize them as floating point numbers and will set ios::badbit in the stream's error state.

The resulting value is stored in the reference location provided. The input operator sets ios::failbit if no digits are available in the stream buffer or if the digits that are available do not begin a floating-point number.

Overload 5
public:istream& operator >>(ios & ( * f ) ( ios & ))

This is supported on AIX OS/400 z/OS

The following built-in manipulators are accepted by this input operator:

       ios&   dec(ios&)
       ios&   hex(ios&)
       ios&   oct(ios &)

These manipulators have a specific effect on an istream object beyond extracting their own values. For example, If ins is a reference to an istream object, then this statement sets ios::dec:

       ins >> dec;
Overload 6
public:istream& operator >>(long long&)

This is supported on AIX OS/400 z/OS

The input operator extracts characters from the stream buffer associated with the input stream and converts them according to the format state of the input stream. The converted characters are then store in the reference location provided. There is no overflow detection on conversion of integral types.

The first character extracted from the stream buffer may be a sign (+ or -). The subsequent characters are converted until a nondigit character is encountered. This nondigit character is left in the stream buffer. Which characters are treated as digits depends on the setting of the following format flags:

  • ios::oct - the characters are converted to an octal value. Characters are extracted from the stream buffer until a character that is not an octal digit (a digit from 0 to 7) is encountered. If ios::oct is set and a signed value is encountered, the value is converted into a decimal value.
  • ios::dec - the characters are converted to a decimal value. Characters are extracted from the stream buffer until a character that is not a decimal digit (a digit from 0 to 9) is encountered.
  • ios::hex - the characters are converted to an hexadecimal value. Characters are extracted from the stream buffer until a character that is not a hexadecimal digit (a digit from 0 to 0 or a letter from "A" to "F", upper or lower case) is encountered. If ios::hex is set and a signed value is encountered, the value is converted into a decimal value.

If none of these format flags is set, the characters are converted according to the C++ lexical conventions. This conversion depends on the characters that follow the optional sign:

  • If these characters are "0x" or "0X", the subsequent characters are converted to a hexadecimal value.
  • If the first character is "0" and the second character is not a "x" or "X", the subsequent characters are converted to an octal value.
  • If neither of these cases is true, the characters are converted to a decimal value.

If no digits are available in the stream buffer (other than the "0" in "0X" or "0x" preceding a hexadecimal value), the input operator sets ios::failbit in the error state of the input stream.

Note: The support for long long is controlled by _LONG_LONG, __EXTENDED__, or the -q(no)longlong option.

Overload 7
public:istream& operator >>(long&)

This is supported on AIX OS/400 z/OS

The input operator extracts characters from the stream buffer associated with the input stream and converts them according to the format state of the input stream. The converted characters are then store in the reference location provided. There is no overflow detection on conversion of integral types.

The first character extracted from the stream buffer may be a sign (+ or -). The subsequent characters are converted until a nondigit character is encountered. This nondigit character is left in the stream buffer. Which characters are treated as digits depends on the setting of the following format flags:

  • ios::oct - the characters are converted to an octal value. Characters are extracted from the stream buffer until a character that is not an octal digit (a digit from 0 to 7) is encountered. If ios::oct is set and a signed value is encountered, the value is converted into a decimal value.
  • ios::dec - the characters are converted to a decimal value. Characters are extracted from the stream buffer until a character that is not a decimal digit (a digit from 0 to 9) is encountered.
  • ios::hex - the characters are converted to an hexadecimal value. Characters are extracted from the stream buffer until a character that is not a hexadecimal digit (a digit from 0 to 0 or a letter from "A" to "F", upper or lower case) is encountered. If ios::hex is set and a signed value is encountered, the value is converted into a decimal value.

If none of these format flags is set, the characters are converted according to the C++ lexical conventions. This conversion depends on the characters that follow the optional sign:

  • If these characters are "0x" or "0X", the subsequent characters are converted to a hexadecimal value.
  • If the first character is "0" and the second character is not a "x" or "X", the subsequent characters are converted to an octal value.
  • If neither of these cases is true, the characters are converted to a decimal value.

If no digits are available in the stream buffer (other than the "0" in "0X" or "0x" preceding a hexadecimal value), the input operator sets ios::failbit in the error state of the input stream.

Overload 8
public:istream& operator >>(short&)

This is supported on AIX OS/400 z/OS

The input operator extracts characters from the stream buffer associated with the input stream and converts them according to the format state of the input stream. The converted characters are then store in the reference location provided. There is no overflow detection on conversion of integral types.

The first character extracted from the stream buffer may be a sign (+ or -). The subsequent characters are converted until a nondigit character is encountered. This nondigit character is left in the stream buffer. Which characters are treated as digits depends on the setting of the following format flags:

  • ios::oct - the characters are converted to an octal value. Characters are extracted from the stream buffer until a character that is not an octal digit (a digit from 0 to 7) is encountered. If ios::oct is set and a signed value is encountered, the value is converted into a decimal value.
  • ios::dec - the characters are converted to a decimal value. Characters are extracted from the stream buffer until a character that is not a decimal digit (a digit from 0 to 9) is encountered.
  • ios::hex - the characters are converted to an hexadecimal value. Characters are extracted from the stream buffer until a character that is not a hexadecimal digit (a digit from 0 to 0 or a letter from "A" to "F", upper or lower case) is encountered. If ios::hex is set and a signed value is encountered, the value is converted into a decimal value.

If none of these format flags is set, the characters are converted according to the C++ lexical conventions. This conversion depends on the characters that follow the optional sign:

  • If these characters are "0x" or "0X", the subsequent characters are converted to a hexadecimal value.
  • If the first character is "0" and the second character is not a "x" or "X", the subsequent characters are converted to an octal value.
  • If neither of these cases is true, the characters are converted to a decimal value.

If no digits are available in the stream buffer (other than the "0" in "0X" or "0x" preceding a hexadecimal value), the input operator sets ios::failbit in the error state of the input stream.

Overload 9
public:istream& operator >>(signed char& c)

This is supported on AIX OS/400 z/OS

The input operator extracts a character from the stream buffer attached to the input stream and stores it in c.

Overload 10
public:istream& operator >>(signed char*)

This is supported on AIX OS/400 z/OS

The input operator stores characters from the stream buffer attached to the input stream in the array pointed to by the argument. The input operator stores characters until a white-space character is found. This white-space character is left in the stream buffer, and the extraction stops. If ios::x_width does not equal 0, a maximum of ios::x_width - 1 characters are extracted. The input operator calls width(0) to reset the ios::x_width to 0.

The input operator always stores a terminating null character in the array, even if an error occurs.

Overload 11
public:istream& operator >>(unsigned char*)

This is supported on AIX OS/400 z/OS

The input operator stores characters from the stream buffer attached to the input stream in the array pointed to by the argument. The input operator stores characters until a white-space character is found. This white-space character is left in the stream buffer, and the extraction stops. If ios::x_width does not equal 0, a maximum of ios::x_width - 1 characters are extracted. The input operator calls width(0) to reset the ios::x_width to 0.

The input operator always stores a terminating null character in the array, even if an error occurs.

Overload 12
public:istream& operator >>(streambuf*)

This is supported on AIX OS/400 z/OS

For pointers to streambuf objects, the input operator calls ipfx(0). If ipfx(0) returns a nonzero value, the input operator extracts characters from the stream buffer attached to the istream object and inserts them in the streambuf. Extraction stops when an EOF character is encountered.

The input operator always returns a reference to the istream object.

Overload 13
public:istream& operator >>(unsigned int&)

This is supported on AIX OS/400 z/OS

The input operator extracts characters from the stream buffer associated with the input stream and converts them according to the format state of the input stream. The converted characters are then store in the reference location provided. There is no overflow detection on conversion of integral types.

The first character extracted from the stream buffer may be a sign (+ or -). The subsequent characters are converted until a nondigit character is encountered. This nondigit character is left in the stream buffer. Which characters are treated as digits depends on the setting of the following format flags:

  • ios::oct - the characters are converted to an octal value. Characters are extracted from the stream buffer until a character that is not an octal digit (a digit from 0 to 7) is encountered. If ios::oct is set and a signed value is encountered, the value is converted into a decimal value.
  • ios::dec - the characters are converted to a decimal value. Characters are extracted from the stream buffer until a character that is not a decimal digit (a digit from 0 to 9) is encountered.
  • ios::hex - the characters are converted to an hexadecimal value. Characters are extracted from the stream buffer until a character that is not a hexadecimal digit (a digit from 0 to 0 or a letter from "A" to "F", upper or lower case) is encountered. If ios::hex is set and a signed value is encountered, the value is converted into a decimal value.

If none of these format flags is set, the characters are converted according to the C++ lexical conventions. This conversion depends on the characters that follow the optional sign:

  • If these characters are "0x" or "0X", the subsequent characters are converted to a hexadecimal value.
  • If the first character is "0" and the second character is not a "x" or "X", the subsequent characters are converted to an octal value.
  • If neither of these cases is true, the characters are converted to a decimal value.

If no digits are available in the stream buffer (other than the "0" in "0X" or "0x" preceding a hexadecimal value), the input operator sets ios::failbit in the error state of the input stream.

Overload 14
public:istream& operator >>(unsigned long long&)

This is supported on AIX OS/400 z/OS

The input operator extracts characters from the stream buffer associated with the input stream and converts them according to the format state of the input stream. The converted characters are then store in the reference location provided. There is no overflow detection on conversion of integral types.

The first character extracted from the stream buffer may be a sign (+ or -). The subsequent characters are converted until a nondigit character is encountered. This nondigit character is left in the stream buffer. Which characters are treated as digits depends on the setting of the following format flags:

  • ios::oct - the characters are converted to an octal value. Characters are extracted from the stream buffer until a character that is not an octal digit (a digit from 0 to 7) is encountered. If ios::oct is set and a signed value is encountered, the value is converted into a decimal value.
  • ios::dec - the characters are converted to a decimal value. Characters are extracted from the stream buffer until a character that is not a decimal digit (a digit from 0 to 9) is encountered.
  • ios::hex - the characters are converted to an hexadecimal value. Characters are extracted from the stream buffer until a character that is not a hexadecimal digit (a digit from 0 to 0 or a letter from "A" to "F", upper or lower case) is encountered. If ios::hex is set and a signed value is encountered, the value is converted into a decimal value.

If none of these format flags is set, the characters are converted according to the C++ lexical conventions. This conversion depends on the characters that follow the optional sign:

  • If these characters are "0x" or "0X", the subsequent characters are converted to a hexadecimal value.
  • If the first character is "0" and the second character is not a "x" or "X", the subsequent characters are converted to an octal value.
  • If neither of these cases is true, the characters are converted to a decimal value.

If no digits are available in the stream buffer (other than the "0" in "0X" or "0x" preceding a hexadecimal value), the input operator sets ios::failbit in the error state of the input stream.

Note: The support for long long is controlled by _LONG_LONG, __EXTENDED__, or the -q(no)longlong option.

Overload 15
public:istream& operator >>(unsigned long&)

This is supported on AIX OS/400 z/OS

The input operator extracts characters from the stream buffer associated with the input stream and converts them according to the format state of the input stream. The converted characters are then store in the reference location provided. There is no overflow detection on conversion of integral types.

The first character extracted from the stream buffer may be a sign (+ or -). The subsequent characters are converted until a nondigit character is encountered. This nondigit character is left in the stream buffer. Which characters are treated as digits depends on the setting of the following format flags:

  • ios::oct - the characters are converted to an octal value. Characters are extracted from the stream buffer until a character that is not an octal digit (a digit from 0 to 7) is encountered. If ios::oct is set and a signed value is encountered, the value is converted into a decimal value.
  • ios::dec - the characters are converted to a decimal value. Characters are extracted from the stream buffer until a character that is not a decimal digit (a digit from 0 to 9) is encountered.
  • ios::hex - the characters are converted to an hexadecimal value. Characters are extracted from the stream buffer until a character that is not a hexadecimal digit (a digit from 0 to 0 or a letter from "A" to "F", upper or lower case) is encountered. If ios::hex is set and a signed value is encountered, the value is converted into a decimal value.

If none of these format flags is set, the characters are converted according to the C++ lexical conventions. This conversion depends on the characters that follow the optional sign:

  • If these characters are "0x" or "0X", the subsequent characters are converted to a hexadecimal value.
  • If the first character is "0" and the second character is not a "x" or "X", the subsequent characters are converted to an octal value.
  • If neither of these cases is true, the characters are converted to a decimal value.

If no digits are available in the stream buffer (other than the "0" in "0X" or "0x" preceding a hexadecimal value), the input operator sets ios::failbit in the error state of the input stream.

Overload 16
public:istream& operator >>(unsigned short&)

This is supported on AIX OS/400 z/OS

The input operator extracts characters from the stream buffer associated with the input stream and converts them according to the format state of the input stream. The converted characters are then store in the reference location provided. There is no overflow detection on conversion of integral types.

The first character extracted from the stream buffer may be a sign (+ or -). The subsequent characters are converted until a nondigit character is encountered. This nondigit character is left in the stream buffer. Which characters are treated as digits depends on the setting of the following format flags:

  • ios::oct - the characters are converted to an octal value. Characters are extracted from the stream buffer until a character that is not an octal digit (a digit from 0 to 7) is encountered. If ios::oct is set and a signed value is encountered, the value is converted into a decimal value.
  • ios::dec - the characters are converted to a decimal value. Characters are extracted from the stream buffer until a character that is not a decimal digit (a digit from 0 to 9) is encountered.
  • ios::hex - the characters are converted to an hexadecimal value. Characters are extracted from the stream buffer until a character that is not a hexadecimal digit (a digit from 0 to 0 or a letter from "A" to "F", upper or lower case) is encountered. If ios::hex is set and a signed value is encountered, the value is converted into a decimal value.

If none of these format flags is set, the characters are converted according to the C++ lexical conventions. This conversion depends on the characters that follow the optional sign:

  • If these characters are "0x" or "0X", the subsequent characters are converted to a hexadecimal value.
  • If the first character is "0" and the second character is not a "x" or "X", the subsequent characters are converted to an octal value.
  • If neither of these cases is true, the characters are converted to a decimal value.

If no digits are available in the stream buffer (other than the "0" in "0X" or "0x" preceding a hexadecimal value), the input operator sets ios::failbit in the error state of the input stream.

Overload 17
public:istream& operator >>(wchar_t&)

This is supported on AIX OS/400 z/OS

The input operator extracts a wchar_t character from the stream buffer attached to the input stream and stores it in the reference location provided. If ios::skipws is set, the input operator skips leading wchar_t spaces as well as leading char white spaces.

Overload 18
public:istream& operator >>(wchar_t*)

This is supported on AIX OS/400 z/OS

The input operator stores characters from the stream buffer attached to the input stream in the array pointed to by the argument. The input operator stores characters until a white-space character or a wchar_t blank is found. If the terminating character is a white-space character, it is left in the stream buffer. If it is a wchar_t blank, it is discarded to avoid returning two bytes to the input stream.

For wchar_t* arrays, if ios::x_width does not equal 0, a maximum of ios::x_width - 1 characters (at 2 bytes each) are extracted. A 2-character space is reserved for the wchar_t terminating null character.

The input operator resets ios::x_width to 0.

The input operator always stores a terminating null character in the array, even if an error occurs. For arrays of wchar_t*, this terminating null character is a wchar_t terminating null character.

Overload 19
public:istream& operator >>(unsigned char& c)

This is supported on AIX OS/400 z/OS

The input operator extracts a character from the stream buffer attached to the input stream and stores it in c.

Overload 20
public:istream& operator >>(istream & ( * f ) ( istream & ))

This is supported on AIX OS/400 z/OS

The following built-in manipulators are accepted by this input operator:

       istream&   ws(istream&)

These manipulators have a specific effect on an istream object beyond extracting their own values. For example, If ins is a reference to an istream object, then this statement extracts white-space characters from the stream buffer attached to ins:

       ins >> ws;
Overload 21
public:istream& operator >>(double&)

This is supported on AIX OS/400 z/OS

The input operator converts characters from the stream buffer attached to the input stream according to the C++ lexical conventions.

The following conversions occur for certain string values:

  • If the value consists of the character strings "inf" or "infinity" in any combination of uppercase and lowercase letters, the string is converted to the approprate type's representation of infinity.
  • If the value consists of the character string "nan" in any combination of uppercase and lowercase letters, the string is converted to the appropriate type's representation of a NaN.

Note that if you use thse string values as input in a program compiled with z/OS C/C++, the input operator will not recognize them as floating point numbers and will set ios::badbit in the stream's error state.

The resulting value is stored in the reference location provided. The input operator sets ios::failbit if no digits are available in the stream buffer or if the digits that are available do not begin a floating-point number.

Overload 22
public:istream& operator >>(char& c)

This is supported on AIX OS/400 z/OS

The input operator extracts a character from the stream buffer attached to the input stream and stores it in c.

Positioning Functions

Functions that work with the get pointer of the ultimate producer.

putback
public:istream& putback(char c)

This is supported on AIX OS/400 z/OS

putback() attempts to put an extracted character back into the stream buffer. c must equal the character before the get pointer of the stream buffer. Unless some other activity is modifying the stream buffer, this is the last character extracted from the stream buffer. If c is not equal to the character before the get pointer, the result of putback() is undefined, and the error state of the input stream may be set. putback() does not call ipfx(), but if the error state of the input stream is nonzero, putback() returns without putting back the character or setting the error state.

seekg
Overload 1
public:istream& seekg(streampos p)

This is supported on AIX OS/400 z/OS

Sets the get pointer to the position p.

If you attempt to set the get pointer to a position that is not valid, seekg() sets ios::badbit.

Overload 2
public:istream& seekg(streamoff o, ios::seek_dir d)

This is supported on AIX OS/400 z/OS

Sets the get pointer to the position specified by d with the offset o. The argument d can have the following values:

  • ios::beg - the beginning of the stream
  • ios::cur - the current position of the get pointer
  • ios::end - the end of the stream

If you attempt to set the get pointer to a position that is not valid, seekg() sets ios::badbit.

sync
public:int sync()

This is supported on AIX OS/400 z/OS

Establishes consistency between the ultimate producer and the stream buffer attached to the input stream. sync() calls rdbuf()->sync(), which is a virtual function, so the details of its operation depend on the way the function is defined in a given derived class. If an error occurs, sync() returns EOF.

tellg
public:streampos tellg()

This is supported on AIX OS/400 z/OS

Returns the current position of the get pointer of the ultimate producer.

Prefix and Suffix Functions

Functions that are called either before or after extracting characters from the ultimate producer.

ipfx

Checks the stream buffer attached to an istream object to determine if it is capable of satisfying requests for characters. It returns a nonzero value if the stream buffer is ready, and 0 if it is not.

The formatted input operator calls ipfx(0), while the unformatted input functions call ipfx(1).

If the error state of the istream object is nonzero, ipfx() returns 0. Otherwise, the stream buffer attached to the istream object is flushed if either of the following conditions is true:

If ios::skipws is set in the format state of the istream object and noskipws has a value of 0, leading white-space characters are extracted from the stream buffer and discarded. If ios::hardfail is set or EOF is encountered, ipfx() returns 0. Otherwise, it returns a nonzero value.

Overload 1
public:int ipfx(int noskipws = 0)

This is supported on AIX OS/400 z/OS

AIX and z/OS Considerations

This function accepts an int value for 32-bit applications. It is not available for 64-bit applications.

Overload 2
public:int ipfx(long noskipws = 0)

This is supported on AIX z/OS

This function accepts a long value for 64-bit applications. It is not available for 32-bit applications.

isfx
public:void isfx()

This is supported on AIX OS/400 z/OS

Internal function. Do not use.

do_ipfx
Overload 1
protected:int do_ipfx(long noskipws)

This is supported on AIX z/OS

Internal function. Do not use.

This function is available for 64-bit applications. It accepts a long argument.

Overload 2
protected:int do_ipfx(int noskipws)

This is supported on AIX OS/400 z/OS

Internal function. Do not use.

AIX and z/OS Considerations

This function is available for 32-bit applications. It accepts an int argument.