std::basic_istream<CharT,Traits>::read
From cppreference.com
< cpp | io | basic istream
C++
Feature test macros (C++20)
Concepts library (C++20)
Metaprogramming library (C++11)
Ranges library (C++20)
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Input/output library
Print functions (C++23)
Buffers
(C++23)
(C++98/26*)
(C++20)
Streams
Abstractions
File I/O
String I/O
Array I/O
(C++23)
(C++23)
(C++23)
(C++98/26*)
(C++98/26*)
(C++98/26*)
Synchronized Output
(C++20)
Types
Error category interface
(C++11)
(C++11)
std::basic_istream
Global objects
Member functions
(C++11)
Formatted input
Unformatted input
basic_istream::read
Positioning
Miscellaneous
(C++11)
Member classes
Non-member functions
basic_istream& read( char_type* s, std::streamsize count );
Extracts characters from stream.
Behaves as UnformattedInputFunction. After constructing and checking the sentry object, extracts characters and stores them into successive locations of the character array whose first element is pointed to by s. Characters are extracted and stored until any of the following conditions occurs:
- count characters were extracted and stored.
- end of file condition occurs on the input sequence (in which case, setstate(failbit|eofbit) is called). The number of successfully extracted characters can be queried using gcount().
[edit] Parameters
s
-
pointer to the character array to store the characters to
count
-
number of characters to read
[edit] Return value
*this
[edit] 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.
[edit] Notes
When using a non-converting locale (the default locale is non-converting), the overrider of this function in std::basic_ifstream may be optimized for zero-copy bulk I/O (by means of overriding std::streambuf::xsgetn ).
[edit] Example
Run this code
#include <cstdint> #include <fstream> #include <iostream> #include <sstream> #include <string> int main() { // read() is often used for binary I/O std::string bin = {'\x12', '\x12', '\x12', '\x12'}; std::istringstream raw(bin); std::uint32_t n; if (raw.read(reinterpret_cast<char*>(&n), sizeof n)) std::cout << std::hex << std::showbase << n << '\n'; // prepare file for next snippet std::ofstream ("test.txt", std::ios::binary) << "abcd1\nabcd2\nabcd3"; // read entire file into string if (std::ifstream is{"test.txt", std::ios::binary | std::ios::ate}) { auto size = is.tellg(); std::string str(size, '0円'); // construct string to stream size is.seekg(0); if (is.read(&str[0], size)) std::cout << str << '\n'; } }
Output:
0x12121212 abcd1 abcd2 abcd3