table of contents
std::basic_istream::getline(3) | C++ Standard Libary | std::basic_istream::getline(3) |
NAME¶
std::basic_istream::getline - std::basic_istream::getline
Synopsis¶
basic_istream& getline( char_type* s, std::streamsize count
); (1)
basic_istream& getline( char_type* s, std::streamsize count, char_type
delim ); (2)
Extracts characters from stream until end of line or the specified delimiter
delim.
The first overload is equivalent to getline(s, count, widen('\n')).
Behaves as UnformattedInputFunction. After constructing and checking the
sentry
object, extracts characters from *this and stores them in successive
locations of
the array whose first element is pointed to by s, until any of the following
occurs
(tested in the order shown):
1. end of file condition occurs in the input sequence (in which case
setstate(eofbit) is executed)
2. the next available character c is the delimiter, as determined by
Traits::eq(c,
delim). The delimiter is extracted (unlike basic_istream::get()) and counted
towards gcount(), but is not stored.
3. count-1 characters have been extracted (in which case setstate(failbit) is
executed).
If the function extracts no characters (e.g. if count < 1),
setstate(failbit) is
executed.
In any case, if count > 0, it then stores a null character CharT() into
the next
successive location of the array and updates gcount().
Notes¶
Because condition #2 is tested before condition #3, the input
line that exactly fits
the buffer does not trigger failbit.
Because the terminating character is counted as an extracted character, an
empty
input line does not trigger failbit.
Parameters¶
s - pointer to the character string to store the characters to
count - size of character string pointed to by s
delim - delimiting character to stop the extraction at. It is extracted but
not
stored.
Return value¶
*this
Exceptions¶
failure if an error occurred (the error state flag is not
goodbit) and exceptions()
is set to throw for that state.
If an internal operation throws an exception, it is caught and badbit is set.
If
exceptions() is set for badbit, the exception is rethrown.
Example¶
// Run this code
#include <iostream>
#include <sstream>
#include <vector>
#include <array>
int main()
{
std::istringstream input("abc|def|gh");
std::vector<std::array<char, 4>> v;
// note: the following loop terminates when std::ios_base::operator bool()
// on the stream returned from getline() returns false
for (std::array<char, 4> a; input.getline(&a[0], 4, '|'); ) {
v.push_back(a);
}
for (auto& a : v) {
std::cout << &a[0] << '\n';
}
}
Output:¶
abc
def
gh
See also¶
getline read data from an I/O stream into a string
(function template)
operator>> extracts formatted data
(public member function)
get extracts characters
(public member function)
read extracts blocks of characters
(public member function)
2022.07.31 | http://cppreference.com |