public member function
<istream> <iostream>
istream& ignore (streamsize n = 1, int delim = EOF);
Extract and discard characters
Extracts characters from the input sequence and discards them, until either n characters have been extracted, or one compares equal to delim.
The function also stops extracting characters if the end-of-file is reached. If this is reached prematurely (before either extracting n characters or finding delim), the function sets the eofbit flag.
Internally, the function accesses the input sequence by first constructing a sentry object (with noskipws set to true). Then (if good), it extracts characters from its associated stream buffer object as if calling its member functions sbumpc or sgetc, and finally destroys the sentry object before returning.
Parameters
- n
- Maximum number of characters to extract (and ignore).
If this is exactly numeric_limits<streamsize>::max(), there is no limit: As many characters are extracted as needed until delim (or the end-of-file) is found.
streamsize is a signed integral type.
- delim
- Delimiting character: The function stops extracting characters as soon as an extracted character compares equal to this.
Note that the delimiting character is extracted, and thus the next input operation will continue on the character that follows it (if any).
If this is the end-of-file value (EOF), no character will compare equal, and thus exactly n characters will be discarded (unless the function fails or the end-of-file is reached).
Return Value
The istream object (*this).
Errors are signaled by modifying the internal state flags:
| flag | error |
|---|
| eofbit | The function stopped extracting characters because the input sequence has no more characters available (end-of-file reached). |
| failbit | The construction of sentry failed (such as when the stream state was not good before the call). |
| badbit | Error on stream (such as when this function catches an exception thrown by an internal operation).
When set, the integrity of the stream may have been affected. |
Multiple flags may be set by a single operation.
If the operation sets an internal state flag that was registered with member exceptions, the function throws an exception of member type failure.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
// istream::ignore example
#include <iostream> // std::cin, std::cout
int main () {
char first, last;
std::cout << "Please, enter your first name followed by your surname: ";
first = std::cin.get(); // get one character
std::cin.ignore(256,' '); // ignore until space
last = std::cin.get(); // get one character
std::cout << "Your initials are " << first << last << '\n';
return 0;
}
|
Possible output:
Please, enter your first name followed by your surname: John Smith
Your initials are JS
|
Data races
Modifies the stream object.
Concurrent access to the same stream object may cause data races, except for the standard stream object cin when this is synchronized with stdio (in this case, no data races are initiated, although no guarantees are given on the order in which extracted characters are attributed to threads).
Exception safety
Basic guarantee: if an exception is thrown, the object is in a valid state.
It throws an exception of member type failure if the resulting error state flag is not goodbit and member exceptions was set to throw for that state.
Any exception thrown by an internal operation is caught and handled by the function, setting badbit. If badbit was set on the last call to exceptions, the function rethrows the caught exception.