std::basic_...m::readsome(3)

💅 NAME

ok so this page is all about std::basic_istream::readsome — yes the name is literally the same twice, that's just how cppreference does it bestie. this is a page from the C++ Standard Library manual, and it's about a member function that grabs whatever characters are immediately available. no waiting, no blocking, no patience. periodt.

---

✨ Synopsis

std::streamsize readsome( char_type* s, std::streamsize count );

okay so what this does 👇 it extracts up to count immediately available characters from the input stream, and the characters it pulls out get stored into the character array that s points to.

it behaves as an UnformattedInputFunction. after it constructs and checks the sentry object, here's the tea:

• if rdbuf()->in_avail() == -1, it calls setstate(eofbit) and extracts no characters 😭
• if rdbuf()->in_avail() == 0, it extracts no characters (again, nothing, zero, nada)
• if rdbuf()->in_avail() > 0, it extracts std::min(rdbuf()->in_avail(), count) characters and stores them into successive locations of the character array whose first element is pointed to by s 🎀

---

🫶 Parameters

• s — pointer to the character array you're storing the characters into
• count — the maximum number of characters to read

---

🌸 Return value

the number of characters actually extracted. not the number you asked for, the number you got. vibe check on reality, honestly.

---

💀 Exceptions

• failure — thrown if an error occurred (aka the error state flag is not goodbit) and exceptions() is set to throw for that state.
• if an internal operation throws an exception, it gets caught and badbit is set. and if exceptions() is set for badbit, that exception is rethrown. so it comes right back at you 🙈

---

👑 Notes

ok this is the part you actually need to hear: the behavior of this function is highly implementation-specific. like, extremely. no cap.

for example, when you use it with std::ifstream, some library implementations fill the underlying filebuf with data as soon as the file is opened (and readsome() on those implementations reads data — potentially, but not necessarily, the entire file 😭). while other implementations only read from the file when an actual input operation is requested (and readsome() issued after file opening never extracts any characters).

likewise, a call to std::cin.readsome() may return all pending unprocessed console input, or may always return zero and extract no characters. yes really. it's giving chaos. it's giving "depends on your stdlib". iykyk.

---

🦋 Example

// Run this code

#include <iostream>
#include <sstream>

int main()
{
    char c[10] = {};
    std::istringstream input("This is sample text."); // std::stringbuf makes its entire
                                                      // buffer available for
                                                      // unblocking read
    input.readsome(c, 5); // reads 'This ' and stores in c[0] .. c[4]
    input.readsome(c, 9); // reads 'is sample' and stores in c[0] .. c[8]
    std::cout << c << '\n';
}

Output

 is sample

(yeah there's a leading space, it's not a typo, it's literally the output bestie 💖)

---

⭐ See also

• read — extracts blocks of characters (public member function)
• in_avail — obtains the number of characters immediately available in the get area (public member function of std::basic_streambuf<CharT,Traits>)

---

ok that's the whole page, you ate that 💅 this little gem came to you from cppreference.com, dated 2024.06.10 — go forth and readsome responsibly, mwah 🎀✨