home | help 
std::basic_istream::read(3)    C++ Standard Libary   std::basic_istream::read(3)

NAME
     std::basic_istream::read - std::basic_istream::read

Synopsis
	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  ex-
     tracted
	    characters can be queried using gcount().

Parameters
	s     - pointer to the character array to store the characters to
	count - number of characters to read

Return value
	*this

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
	When using a non-converting locale (the default locale	is  non-convert-
     ing), 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).

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

See also
	write	   inserts blocks of characters
		   (public member function of std::basic_ostream<CharT,Traits>)
	operator>> extracts formatted data
		   (public member function)
	readsome   extracts already available blocks of characters
		   (public member function)
	get	   extracts characters
		   (public member function)
	getline    extracts characters until the given character is found
		   (public member function)
	fread	   reads from a file
		   (function)

http://cppreference.com 	   2024.06.10	     std::basic_istream::read(3)
home | help