xentara::utils::io::FileOutputStream< Element > Class Template Reference

A stream that writes to a file. More...

#include <xentara/utils/io/FileOutputStream.hpp>

Inheritance diagram for xentara::utils::io::FileOutputStream< Element >:

Public Member Functions
	FileOutputStream ()=default
	Default constructor.
	FileOutputStream (const std::filesystem::path &path, File::Access access=File::Access::Truncate)
	Constructor that opens a file.
	FileOutputStream (File &&file) noexcept
	Constructor that takes ownership of an existing file.
	~FileOutputStream () noexcept(false)
	Destructor.
auto	operator= (File &&file) noexcept -> FileOutputStream &
	Assignment operator that takes ownership of an existing file.
auto	open (const std::filesystem::path &path, File::Access access=File::Access::Truncate) -> void
	Opens a file.
auto	close () -> void
	Closes the file, if it is open.
auto	close (std::nothrow_t) noexcept -> std::error_code
	Closes the file, if it is open, and return any errors.
Public Member Functions inherited from xentara::utils::io::AbstractBufferedOutputStream< Element >
	AbstractBufferedOutputStream ()=default
	Default constructor Creates a stream without a buffer.
Public Member Functions inherited from xentara::utils::io::OutputStream< Element >
virtual	~OutputStream () noexcept(false)=0
	Virtual, throwing destructor.
auto	write (Element element) -> void
	Write a single element to the stream.
template<std::ranges::contiguous_range Data> requires std::same_as<std::remove_cv_t<std::ranges::range_value_t<Data>>, Element>
auto	write (const Data &data) -> void
	Write a block of data.
template<std::size_t kDataSize>
auto	write (const Element(&data)[kDataSize]) -> void
	Write a block of data contained in an array.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::remove_cv_t<std::iter_value_t<Iterator>>, Element>
auto	write (Iterator first, Sentinel last) -> void
	Write a block of data contained in an iterator range.
auto	write (const Element *data, std::size_t size) -> void
	Write a block of data contained in a region of memory.
auto	write (const Element *nullTerminatedString) -> void
	Write a NULL-teminated string.
auto	flush () -> void
	Flushes the buffer.
Public Member Functions inherited from xentara::utils::io::StreamBase
virtual	~StreamBase () noexcept(false)=0
	Virtual, throwing destructor.
auto	streamDescription () const -> std::string
	Get a description of the device.

Additional Inherited Members
Public Types inherited from xentara::utils::io::OutputStream< Element >
using	element_type = Element
	The element type.
Protected Member Functions inherited from xentara::utils::io::AbstractDeviceOutputStream< Element >
virtual auto	outputDevice () noexcept -> OutputDevice &=0
	Called by the framework to get the device.
auto	doGetStreamDescription () const -> std::string override
	Implementation of InputStream::doGetStreamDescription()
auto	doWrite (const Element *data, std::size_t size) -> std::size_t final
	Implementation of InputStream::doWrite()
Protected Member Functions inherited from xentara::utils::io::AbstractBufferedOutputStream< Element >
auto	resetOutputBuffer (std::size_t bufferSizeHint=kDefaultBufferSize) -> void
	Resets the buffer.
auto	destroyOutputBuffer () -> void
	Destroys the buffer.
Protected Member Functions inherited from xentara::utils::io::OutputStream< Element >
	OutputStream () noexcept=default
	Default constructor.
	OutputStream (Element *bufferBegin, Element *bufferEnd) noexcept
	Constructor that sets an initially empty buffer.
	OutputStream (Element *bufferBegin, Element *bufferEnd, Element *dataEnd) noexcept
	Constructor that sets a buffer that possibly already contains some data.
	OutputStream (OutputStream &&other) noexcept
	Move constructor.
auto	operator= (OutputStream &&rhs) noexcept -> OutputStream &
	Move assignemnt operator.
auto	setWriteBuffer (Element *bufferBegin, Element *bufferEnd) noexcept -> void
	Sets a new empty buffer.
auto	setWriteBuffer (Element *bufferBegin, Element *bufferEnd, Element *dataEnd) noexcept -> void
	Sets the buffer.
auto	setWriteDataEnd (Element *dataEnd) noexcept -> void
	Sets the end of the data within the buffer.
auto	writeBufferBegin () const -> Element *
	Writes back the buffer start position.
auto	writeBufferEnd () const -> Element *
	Writes back the buffer end position.
auto	writeBufferSize () const -> std::size_t
	Gets the buffer size.
auto	writeDataBegin () const -> Element *
	Returns the beginning of data in the buffer.
auto	writeDataEnd () const -> Element *
	Returns the end of the data in the buffer.
auto	writeDataSize () const -> std::size_t
	Returns the size of the unwritten data in the buffer.
auto	freeBufferBegin () const -> Element *
	Returns the beginning of the free region of the buffer.
auto	freeBufferSize () const -> std::size_t
	Returns the size of the unwritten data in the buffer.
virtual auto	doFlushWriteBuffer () -> void
	Called by the framework to write the buffered data to the underlying device once it is full.
Static Protected Attributes inherited from xentara::utils::io::AbstractBufferedOutputStream< Element >
static const std::size_t	kDefaultBufferSize
	The default buffer size.

Detailed Description

template<StreamElement Element>
requires (sizeof(Element) == sizeof(std::byte))
class xentara::utils::io::FileOutputStream< Element >

A stream that writes to a file.

Constructor & Destructor Documentation

FileOutputStream() [1/3]

template<StreamElement Element>

xentara::utils::io::FileOutputStream< Element >::FileOutputStream ( )

default

Default constructor.

This constructor does not open any file. you must open a file with open() before using the class.

FileOutputStream() [2/3]

template<StreamElement Element>

xentara::utils::io::FileOutputStream< Element >::FileOutputStream	(	const std::filesystem::path &	path,
		File::Access	access = File::Access::Truncate
	)

Constructor that opens a file.

Parameters

path	The path to open
access	The access. Must be a write-only access, i.e it cannot be File::Access::Read, File::Access::Edit, or File::Access::EditExisting.

Exceptions

FileNotFoundError	The file does not exist
std::system_error	A different error occurred opening the file

FileOutputStream() [3/3]

template<StreamElement Element>

xentara::utils::io::FileOutputStream< Element >::FileOutputStream ( File &&  file )

noexcept

Constructor that takes ownership of an existing file.

Parameters

file	The file to use, or a default constructed object for none. if the file is open, it must be writable.

~FileOutputStream()

template<StreamElement Element>

xentara::utils::io::FileOutputStream< Element >::~FileOutputStream

(

)

Destructor.

This destructor closes the file, if it is open.

This destructor may throw an exception if cached data or metadata could not be written back to disk. To prevent termination of the program, no exceptions are thrown during stack windup, though. You can prevent the destructor from throwing any exceptions by closing the file manually beforehand using close() or close(std::nothrow_t).

Exceptions

std::system_error

The file was open, but cached data or metadata could not be written back to disk. The file will be closed anyway, however.

Member Function Documentation

close() [1/2]

template<StreamElement Element>

auto xentara::utils::io::FileOutputStream< Element >::close

(

)

-> void

Closes the file, if it is open.

This function will throw an exception if cached data could not be written to the file. The actual file will still be closed, though.

Exceptions

std::system_error

Cached data or metadata could not be written back to disk. The file will be closed anyway, however.

close() [2/2]

template<StreamElement Element>

auto xentara::utils::io::FileOutputStream< Element >::close ( std::nothrow_t  ) -> std::error_code

noexcept

Closes the file, if it is open, and return any errors.

This function return an error code if cached data could not be written to the file. The actual file will still be closed, though.

Returns

std::error_code() on success, or an appropriate error if cached data or metadata could not be written back to disk. The file will be closed either way, however.

open()

template<StreamElement Element>

auto xentara::utils::io::FileOutputStream< Element >::open	(	const std::filesystem::path &	path,
		File::Access	access = File::Access::Truncate
	)		-> void

Opens a file.

Any file alwritey open is silently closed

Parameters

path	The path to open
access	The access. Must be a write-only access, i.e it cannot be File::Access::Read, File::Access::Edit, or File::Access::EditExisting.

Exceptions

FileNotFoundError	The file does not exist
std::system_error	A different error occurred opening the file

operator=()

template<StreamElement Element>

auto xentara::utils::io::FileOutputStream< Element >::operator= ( File &&  file ) -> FileOutputStream &

noexcept

Assignment operator that takes ownership of an existing file.

Parameters

file	The file to use, or a default constructed object to just close the existing file. If the file is open, it must be writable. return A reference to this object.