##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# std::basic_istream::getline

From cppreference.com
< cpp‎ | io‎ | basic istream

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 version is equivalent to getline(s, count, widen('\n')).

Behaves as `UnformattedInputFunction`. After constructing and checking the sentry object, extracts characters from `*this` and stored 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)

- end of file condition occurs in the input sequence (in which case setstate(eofbit) is executed)

- 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.

- 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()`.

### [edit] 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.

### [edit] 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.

### [edit] Return value

*this

### [edit] Exceptions

[edit]
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.

### [edit] 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

### [edit] See also

getline | read data from an I/O stream into a string (function)
operator>> | extracts formatted data (public member function) [edit]
get | extracts characters (public member function) [edit]
read | extracts blocks of characters (public member function) [edit]

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/io/basic_istream/getline&oldid=69048"