xentara::utils::io::File Class Reference

A file. More...

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

Inheritance diagram for xentara::utils::io::File:

Public Types
enum class	Access {   Read , Write , Append , Truncate ,   Edit , CreateNew , WriteExisting , AppendExisting ,   TruncateExisting , EditExisting }
	File access modes. More...
enum class	PseudoFile { StandardInput , StandardOutput , StandardError }
	Standard output pseudo-files. More...

Public Member Functions
	File ()=default
	Default constructor.
	File (const std::filesystem::path &path, Access access)
	Constructor that opens a file.
	File (PseudoFile pseudoFile)
	Constructor that opens a pseudo-file.
	~File () noexcept(false)
	Destructor.
internal auto	operator= (PseudoFile pseudoFile) -> File &
	Assignment operator for a pseudo-file.
auto	open (const std::filesystem::path &path, Access access) -> void
	Opens a file.
auto	size () const -> std::size_t
	Gets the size of the file.
auto	close () -> void
	Closes the file, if one is open.
auto	close (std::nothrow_t) noexcept -> std::error_code
	Closes the file, if one is open, and returns any errors.
	operator bool () const noexcept
	Checks whether the file is open.
Public Member Functions inherited from xentara::utils::io::InputDevice
virtual	~InputDevice () noexcept(false)=0
	Virtual, throwing destructor.
auto	read (std::size_t size) -> core::RawDataBlock
	Reads a block of data of a specific size.
auto	readByte () -> std::byte
	Reads a single byte.
auto	tryReadByte () -> std::optional< std::byte >
	Tries to read a single byte from a device.
auto	readAll () -> core::RawDataBlock
	Reads all remaining data.
auto	readAll (std::size_t maxSize) -> core::RawDataBlock
	Reads all remaining data up to a maximum size.
auto	readChunk () -> core::RawDataBlock
	Reads a single chunk of data.
auto	readChunk (std::size_t maxSize) -> core::RawDataBlock
	Reads a single chunk of data up to a maximum size.
auto	readAvailable () -> std::pair< core::RawDataBlock, bool >
	Reads all immediately available data.
auto	readAvailable (std::size_t maxSize) -> std::pair< core::RawDataBlock, bool >
	Reads immediately available data up to a maximum size.
template<std::size_t kArraySize>
auto	read (std::byte(&array)[kArraySize]) -> void
	Read a block of data into an array.
template<std::size_t kArraySize>
auto	read (std::array< std::byte, kArraySize > &array) -> void
	Read a block of data into an array.
template<std::size_t kArraySize>
auto	readChunk (std::byte(&array)[kArraySize]) -> core::RawDataBlock
	Reads a single chunk of data into an array.
template<std::size_t kArraySize>
auto	readChunk (std::array< std::byte, kArraySize > &array) -> core::RawDataBlock
	Reads a single chunk of data into an array.
template<std::size_t kArraySize>
auto	readAvailable (std::byte(&array)[kArraySize]) -> std::pair< std::size_t, bool >
	Reads immediately available data into an array.
template<std::size_t kArraySize>
auto	readAvailable (std::array< std::byte, kArraySize > &array) -> std::pair< std::size_t, bool >
	Reads immediately available data into an array.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::remove_volatile_t<std::iter_value_t<Iterator>>, std::byte>
auto	read (Iterator first, Sentinel last) -> void
	Read data to fill an iterator range.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::iter_value_t<Iterator>, std::byte>
auto	readChunk (Iterator first, Sentinel last) -> Iterator
	Reads a single chunk of data data into an iterator range.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::iter_value_t<Iterator>, std::byte>
auto	readAvailable (Iterator first, Sentinel last) -> std::pair< Iterator, bool >
	Reads immediately available data into an iterator range.
auto	read (std::byte *buffer, std::size_t size) -> void
	Read a block of data into a buffer.
auto	readChunk (std::byte *buffer, std::size_t size) -> std::size_t
	Reads a single chunk of data into a buffer.
auto	readAvailable (std::byte *buffer, std::size_t size) -> std::pair< std::size_t, bool >
	Reads immediately available data into a buffer.
auto	availableReadSize () const -> std::optional< std::size_t >
	Get the number of bytes for reading without blocking.
auto	remainingReadSize () const -> std::optional< std::size_t >
	Get the number of bytes remaining before the end of the device.
auto	readPosition () const -> std::optional< std::size_t >
	Gets the current read position within the device.
auto	setReadPosition (std::size_t position) -> std::optional< std::size_t >
	Sets the current read position within the device.
auto	moveReadPosition (std::ptrdiff_t offset, std::ios_base::seekdir origin=std::ios_base::cur) -> std::optional< std::size_t >
	Advances or retreats the current read position within the device.
auto	advanceReadPosition (std::size_t offset) -> std::optional< std::size_t >
	Advance the current read position within the device.
auto	rewind () -> bool
	Sets the current read position to the beginning of the device.
auto	waitForData () -> void
	Waits for more read data to become available.
auto	waitForData (std::optional< std::chrono::nanoseconds > timeout) -> bool
	Waits for more read data to become available within a certain time.
auto	readTimeout () const noexcept -> std::chrono::nanoseconds
	Returns the read timeout for communication devices.
auto	throwEndOfStreamError () const -> void
	Throws an error denoting the end of the stream.
Public Member Functions inherited from xentara::utils::io::DeviceBase
virtual	~DeviceBase () noexcept(false)=0
	Virtual, throwing destructor.
auto	deviceDescription () const -> std::string
	Get a description of the device.
Public Member Functions inherited from xentara::utils::io::OutputDevice
virtual	~OutputDevice () noexcept(false)=0
	Virtual, throwing destructor.
template<std::ranges::contiguous_range Data> requires std::same_as<std::remove_cv_t<std::ranges::range_value_t<Data>>, std::byte>
auto	write (const Data &data) -> void
	Writes a block of data.
auto	writeByte (std::byte byte) -> void
	Write a single byte.
template<std::ranges::contiguous_range Data> requires std::same_as<std::remove_cv_t<std::ranges::range_value_t<Data>>, std::byte>
auto	writeChunk (const Data &data) -> std::ranges::range_size_t< Data >
	Writes a single chunk of data contained in an iterator range.
template<std::ranges::contiguous_range Data> requires std::same_as<std::remove_cv_t<std::ranges::range_value_t<Data>>, std::byte>
auto	tryWrite (const Data &data) -> std::ranges::range_size_t< Data >
	Write as much of a data block as is possible without blocking.
auto	tryWriteByte (std::byte byte) -> bool
	Write a single byte, if this can be done without blocking.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::remove_cv_t<std::iter_value_t<Iterator>>, std::byte>
auto	write (Iterator first, Sentinel last) -> void
	Writes the data contained in an iterator range.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::remove_cv_t<std::iter_value_t<Iterator>>, std::byte>
auto	writeChunk (Iterator first, Sentinel last) -> Iterator
	Writes a single chunk of data from an an iterator range.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::iter_value_t<Iterator>, std::byte>
auto	tryWrite (Iterator first, Sentinel last) -> Iterator
	Write as much of the data contained in an iterator range as is possible without blocking.
auto	write (const std::byte *data, std::size_t size) -> void
	Write a block of data.
auto	writeChunk (const std::byte *data, std::size_t size) -> std::size_t
	Writes a single chunk of data.
auto	tryWrite (const std::byte *data, std::size_t size) -> std::size_t
	Write as much of a data block as is possible without blocking.
auto	writePosition () const -> std::optional< std::size_t >
	Gets the current write position within the device.
auto	setWritePosition (std::size_t position) -> std::optional< std::size_t >
	Sets the current write position within the device.
auto	moveWritePosition (std::ptrdiff_t offset, std::ios_base::seekdir origin=std::ios_base::cur) -> std::optional< std::size_t >
	Advances or retreats the current write position within the device.
auto	waitUntilWritable (std::chrono::nanoseconds timeout) -> bool
	Waits for the device to be able to accept more write data within a certain time.
auto	writeTimeout () const noexcept -> std::chrono::nanoseconds
	Returns the write timeout for communication devices.

Additional Inherited Members
Protected Member Functions inherited from xentara::utils::io::InputDevice
virtual auto	doRead (std::byte *buffer, std::size_t size) -> std::optional< std::size_t >=0
	Called by the framework to read available data into a buffer up to a maximum size.
virtual auto	doThrowEndOfStreamError () const -> void
	Called by the framework to throw an error denoting the end of the stream.
virtual auto	doGetAvailableReadSize () const -> std::optional< std::size_t >
	Called by the framework to get the number of bytes that will be read by the next call to doRead().
virtual auto	doGetRemainingReadSize () const -> std::optional< std::size_t >
	Called by the framework to get the number of bytes remaining before the end of the device.
virtual auto	doWaitForData (std::optional< std::chrono::nanoseconds > timeout) -> bool
	Called by the framework to wait for more read data to become available.
virtual auto	doWaitForDataAndRead (std::byte *buffer, std::size_t size, std::chrono::nanoseconds timeout) -> std::optional< std::size_t >
	Called by the framework to wait for read data to become available, and then read it.
virtual auto	doGetReadTimeout () const noexcept -> std::chrono::nanoseconds
	Called by the framework to get the read timeout.
virtual auto	doGetReadPosition () const -> std::optional< std::size_t >
	Called by the framework to get the current read position within the device.
virtual auto	doSetReadPosition (std::size_t position) -> std::optional< std::size_t >
	Called by the framework to set the current read position within the device.
virtual auto	doMoveReadPosition (std::ptrdiff_t offset, std::ios_base::seekdir origin=std::ios_base::cur) -> std::optional< std::size_t >
	Called by the framework to advance or retreat the current read position within the device.
virtual auto	doAdvanceReadPosition (std::size_t offset) -> std::optional< std::size_t >
	Called by the framework to advance the current read position within the device.
Protected Member Functions inherited from xentara::utils::io::DeviceBase
virtual auto	doGetDeviceDescription () const -> std::string=0
	Called by the framework to get a description of the device.
Protected Member Functions inherited from xentara::utils::io::OutputDevice
virtual auto	doWrite (const std::byte *data, std::size_t size) -> std::size_t=0
	Called by the framework to write data up to a maximum size.
virtual auto	doWaitUntilWritable (std::optional< std::chrono::nanoseconds > timeout) -> bool
	Called by the framework to wait for the device to be able to accept more write data with an optional timeout.
virtual auto	doWaitUntilWritableAndWrite (const std::byte *data, std::size_t size, std::chrono::nanoseconds timeout) -> std::size_t
	Called by the framework to wait for the device to be able to accept more write data, and then write to it.
virtual auto	doGetWriteTimeout () const noexcept -> std::chrono::nanoseconds
	Called by the framework to get the write timeout.
virtual auto	doGetWritePosition () const -> std::optional< std::size_t >
	Called by the framework to get the current write position within the device.
virtual auto	doSetWritePosition (std::size_t position) -> std::optional< std::size_t >
	Called by the framework to set the current write position within the device.
virtual auto	doMoveWritePosition (std::ptrdiff_t offset, std::ios_base::seekdir origin=std::ios_base::cur) -> std::optional< std::size_t >
	Called by the framework to advance or retreat the current write position within the device.

Detailed Description

A file.

This class represents an open file on disk.

This class can be moved but not copied

Member Enumeration Documentation

Access

enum class xentara::utils::io::File::Access

strong

File access modes.

Enumerator
Read	Opens an existing file for reading.
Write	Opens a file for writing, or creates a new file if it doesn't exist.
Append	Opens a file for writing at the end, or creates a new file if it doesn't exist.
Truncate	Opens a file for writing and truncates the contents, or creates a new file if it doesn't exist.
Edit	Opens a file for reading and writing, or creates a new file if it doesn't exist.
CreateNew	Creates a new file and opens it for writing.
WriteExisting	Opens an existing file for writing.
AppendExisting	Opens an existing file for writing at the end.
TruncateExisting	Opens an existing file file for writing and truncates the contents.
EditExisting	Opens an existing file file for reading and writing.

PseudoFile

enum class xentara::utils::io::File::PseudoFile

strong

Standard output pseudo-files.

Enumerator
StandardInput	The standard input stream.
StandardOutput	The standard output stream.
StandardError	The standard error stream.

Constructor & Destructor Documentation

File() [1/3]

xentara::utils::io::File::File ( )

default

Default constructor.

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

File() [2/3]

xentara::utils::io::File::File	(	const std::filesystem::path &	path,
		Access	access
	)

Constructor that opens a file.

Parameters

path	The path to open
access	The access

Exceptions

FileNotFoundError	The access you specified required the file to exist, but it doesn't
FileExistsError	You specied Access::Create as access, but a file with the given name already exists.
std::system_error	A different error occurred opening the file

File() [3/3]

xentara::utils::io::File::File

(

PseudoFile

pseudoFile

)

Constructor that opens a pseudo-file.

Parameters

pseudoFile

The file to open

Exceptions

std::system_error

An error occurred opening the file

~File()

xentara::utils::io::File::~File

(

)

Destructor.

This destructor closes the file, if any 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]

auto xentara::utils::io::File::close

(

)

-> void

Closes the file, if one 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]

auto xentara::utils::io::File::close ( std::nothrow_t  ) -> std::error_code

noexcept

Closes the file, if one is open, and returns 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()

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

Opens a file.

Any file already open is silently closed.

Parameters

path	The path to open
access	The access

Exceptions

FileNotFoundError	The access you specified required the file to exist, but it doesn't
FileExistsError	You specied Access::Create as access, but a file with the given name already exists.
std::system_error	A different error occurred opening the file

operator bool()

xentara::utils::io::File::operator bool ( ) const

explicitnoexcept

Checks whether the file is open.

Returns

Returns true if the file is open, or false if it is closed.

operator=()

internal auto xentara::utils::io::File::operator=

(

PseudoFile

pseudoFile

)

-> File &

Assignment operator for a pseudo-file.

Any file already open is silently closed.

Parameters

pseudoFile

The file to open

Exceptions

std::system_error

A different error occurred opening the file

size()

auto xentara::utils::io::File::size

(

)

const -> std::size_t

Gets the size of the file.

Returns

The current size of the file in bytes

Exceptions

std::system_error

An error occurred getting the file size