std::basic_...eam::getline(3)

💅 std::basic_istream::getline 💅

okay bestie, gather round because we're talking about std::basic_istream::getline from the C++ Standard Library and honestly? it's giving "reads a whole line but make it customizable" energy. this is the manual page for the C++ Standard Library's getline member function, and yes you're gonna understand it by the end. no cap. 🫶

---

✨ Synopsis ✨

basic_istream& getline( char_type* s, std::streamsize count );

(1)

basic_istream& getline( char_type* s, std::streamsize count,
                        char_type delim );

(2)

so what does it do? it extracts characters from the stream until end of line or until the specified delimiter delim, whichever hits first. iconic behavior honestly. 🎀

the first overload is literally equivalent to getline(s, count, widen('\n')). same thing, just with the newline as the default delimiter. slay.

it behaves as an UnformattedInputFunction. after constructing and checking the sentry object, it 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 (and yes, they're tested in the order shown, this matters bestie):

1. end of file condition occurs in the input sequence.
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. periodt.
3. count is non-positive, or count - 1 characters have been extracted (in this case setstate(failbit) is called).

if the function extracts no characters, failbit is set in the local error state before setstate() is called.

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. that's the vibe check passing, bestie. ✅

because the terminating character is counted as an extracted character, an empty input line does not trigger failbit. so don't panic if you get a blank line, it's literally fine. 💅

---

💖 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 — that's it. it returns itself like a main character. 💁‍♀️

---

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

so basically, don't ignore your error states, bestie. they will come for you. 💀

---

⭐ Example ⭐

#include <array>
#include <iostream>
#include <sstream>
#include <vector>

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

look at that. clean. iconic. no notes. 🌈

---

🧚 Defect reports 🧚

the following behavior-changing defect reports were applied retroactively to previously published C++ standards. yes bestie, they went back and fixed things. we love accountability. 🫶

• LWG 531 — Applied to C++98 — Behavior as published: std::getline could not handle the case where count is non-positive — Correct behavior: no character is extracted in this case

ngl that's a glow-up. ✨

---

👑 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)

---

and that's the whole page bestie, you ate that. 💅✨

this little masterpiece comes from http://cppreference.com, dated 2024.06.10, and the page title is std::basic_...eam::getline(3). go forth and read your lines with confidence. 🎀🦋💖