Input streams

Description

Streams for use with tcspc::read_binary_stream().

An input stream is a movable (usually noncopyable) object with the following member functions:

• auto is_error() noexcept -> bool: Return true if the stream is not available or the previous read operation resulted in an error (not including reaching EOF). Not influenced by failure of tell() or skip().
• auto is_eof() noexcept -> bool: Return true if the previous read operation tried to read beyond the end of the stream (or if the stream is not available). Not influenced by failure of tell() or skip().
• auto is_good() noexcept -> bool: Return true if neither is_error() nor is_eof() is true.
• auto tell() noexcept -> std::optional<std::uint64_t>: Return the current stream position if supported by the stream, or std::nullopt.
• auto skip(std::uint64_t bytes) noexcept -> bool: Seek, relative to the current offset, forward by bytes. Return true if successful.
• auto read(std::span<std::byte> buffer) noexcept -> std::uint64_t: Read into the given buffer, up to the buffer size. Return the number of bytes read.

Functions
auto	tcspc::binary_file_input_stream (std::string const &filename, arg::start_offset< u64 > start_offset=arg::start_offset{u64(0)})
	Create a binary input stream for the given file.
auto	tcspc::borrowed_cfile_input_stream (std::FILE *fp)
	Create an input stream from a non-owned C file pointer.
template<typename IStream>
auto	tcspc::istream_input_stream (IStream stream)
	Create an input stream from an std::istream instance.
auto	tcspc::null_input_stream ()
	Create an input stream that contains no bytes.
auto	tcspc::owning_cfile_input_stream (std::FILE *fp)
	Create an input stream from a C file pointer, taking ownership.

Function Documentation

binary_file_input_stream()

auto tcspc::binary_file_input_stream ( std::string const & filename, arg::start_offset< u64 > start_offset = arg::start_offset{u64(0)} )

inline

Create a binary input stream for the given file.

If the file cannot be opened, or is smaller than start_offset bytes, the stream will be in an error state.

Parameters

filename	the filename
start_offset	offset within the file to start reading from

Returns

input stream

borrowed_cfile_input_stream()

auto tcspc::borrowed_cfile_input_stream ( std::FILE * fp )

inline

Create an input stream from a non-owned C file pointer.

The stream will use the C stdio functions, such as std::fread(). The file pointer is not closed when the stream is destroyed. The caller is responsible for ensuring that the file pointer will remain valid throughout the lifetime of the returned input stream.

The file pointer fp should have been opened in binary mode. (If using stdin, use std::freopen() with a null filename on POSIX or _setmode() with _O_BINARY on Windows (via _fileno()).)

If fp is null, the stream will always be in an error state.

See also

tcspc::owning_cfile_input_stream

Parameters

fp	a file pointer

Returns

input stream

istream_input_stream()

template<typename IStream>

auto tcspc::istream_input_stream ( IStream stream )

inline

Create an input stream from an std::istream instance.

The istream is moved into the returned input stream and destroyed together, so you cannot use this with an istream that you do not own (such as std::cin). For that, see tcspc::borrowed_cfile_input_stream (which works with stdin).

Due to poor performance, use of this stream type is not recommended unless you must interface with an existing std::istream.

Parameters

stream

an istream (derived from std::istream)

Returns

input stream

null_input_stream()

auto tcspc::null_input_stream ( )

inline

Create an input stream that contains no bytes.

Returns

input stream

owning_cfile_input_stream()

auto tcspc::owning_cfile_input_stream ( std::FILE * fp )

inline

Create an input stream from a C file pointer, taking ownership.

The stream will use the C stdio functions, such as std::fread(). The file pointer is closed when the stream is destroyed.

The file pointer fp should have been opened in binary mode.

If fp is null, the stream will always be in an error state.

See also

tcspc::borrowed_cfile_input_stream

Parameters

fp	a file pointer

Returns

input stream