NAME

std::basic_istream::readsome - std::basic_istream::readsome

Synopsis

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

Extracts up to count immediately available characters from the input stream. The
extracted characters are stored into the character array pointed to by s.

Behaves as UnformattedInputFunction. After constructing and checking the sentry
object,

* If rdbuf()->in_avail() == -1, calls setstate(eofbit) and extracts no characters.

* If rdbuf()->in_avail() == 0, extracts no characters.

* If rdbuf()->in_avail() > 0, 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 to store the characters to
count - maximum number of characters to read

Return value

The number of characters actually extracted.

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.

Notes

The behavior of this function is highly implementation-specific. For example, when
used with std::ifstream, some library implementations fill the underlying filebuf
with data as soon as the file is opened (and readsome() on such implementations
reads data, potentially, but not necessarily, the entire file), while other
implementations only read from 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.

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;
}

Output:

is sample