Output streams

Description

Streams for use with tcspc::write_binary_stream().

An output 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 write operation resulted in an error. Not influenced by failure of tell().
• auto tell() noexcept -> std::optional<std::uint64_t>: Return the current stream position if supported by the stream, or std::nullopt.
• void write(std::span<std::byte const> buffer) noexcept: Write the given bytes to the stream.

Functions
auto	tcspc::binary_file_output_stream (std::string const &filename, arg::truncate< bool > truncate=arg::truncate{false}, arg::append< bool > append=arg::append{false})
	Create a binary output stream for the given file.
auto	tcspc::borrowed_cfile_output_stream (std::FILE *fp)
	Create an output stream from a non-owned C file pointer.
auto	tcspc::null_output_stream ()
	Create an output stream that discards all written bytes.
template<typename OStream>
auto	tcspc::ostream_output_stream (OStream stream)
	Create an output stream from an std::ostream instance.
auto	tcspc::owning_cfile_output_stream (std::FILE *fp)
	Create an output stream from a C file pointer, taking ownership.

Function Documentation

binary_file_output_stream()

auto tcspc::binary_file_output_stream ( std::string const & filename, arg::truncate< bool > truncate = arg::truncate{false}, arg::append< bool > append = arg::append{false} )

inline

Create a binary output stream for the given file.

If both truncate and append are true, behave as if only truncate is true. If neither are true, the file must not exist or the stream will be in an error state. If the file cannot be opened, the stream will be in an error state.

Parameters

filename	the filename
truncate	if true, overwrite existing file
append	if true, file will be appended to if it exists

Returns

output stream

borrowed_cfile_output_stream()

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

inline

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

The stream will use the C stdio functions, such as std::fwrite(). 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 output stream.

The file pointer fp should have been opened in binary mode. (If using stdout, use std::freopen() with a full 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_output_stream

Parameters

fp	a file pointer

Returns

output stream

null_output_stream()

auto tcspc::null_output_stream ( )

inline

Create an output stream that discards all written bytes.

Returns

output stream

ostream_output_stream()

template<typename OStream>

auto tcspc::ostream_output_stream ( OStream stream )

inline

Create an output stream from an std::ostream instance.

The ostream is moved into the returned output stream and destroyed together, so you cannot use this with an ostream that you do not own (such as std::cout). For that, see tcspc::borrowed_cfile_output_stream (which works with stdout).

Parameters

stream

an ostream (derived from std::ostream)

Returns

output stream

owning_cfile_output_stream()

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

inline

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

The stream will use the C stdio functions, such as std::fwrite(). 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_output_stream

Parameters

fp	a file pointer

Returns

output stream