std::basic_istream::readsome

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical Specifications

 

Input/output library

I/O manipulators

C-style I/O

Buffers

basic_streambuf

basic_filebuf

basic_stringbuf

strstreambuf (deprecated)

Streams

Abstractions

ios_base

basic_ios

basic_istream

basic_ostream

basic_iostream

File I/O

basic_ifstream

basic_ofstream

basic_fstream

String I/O

basic_istringstream

basic_ostringstream

basic_stringstream

Array I/O

istrstream (deprecated)

ostrstream (deprecated)

strstream (deprecated)

Types

streamoff

streamsize

fpos

Error category interface

iostream_category (C++11)

io_errc (C++11)

 

std::basic_istream

Global objects

cinwcin

Member functions

basic_istream::basic_istream

basic_istream::~basic_istream

basic_istream::operator= (C++11)

Formatted input

basic_istream::operator>>

Unformatted input

basic_istream::get

basic_istream::peek

basic_istream::unget

basic_istream::putback

basic_istream::getline

basic_istream::ignore

basic_istream::read

basic_istream::readsome

basic_istream::gcount

Positioning

basic_istream::tellg

basic_istream::seekg

Miscellaneous

basic_istream::sync

basic_istream::swap (C++11)

Member classes

basic_istream::sentry

Non-member functions

operator>>(std::basic_istream)

 

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

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)