Unique handle to a file in the virtual Filesystem. More...

#include <donut/File.hpp>

Classes
struct	Error
	Exception type for errors that may arise when attempting to access files through the virtual File API. More...

struct	Metadata
	Record of metadata for a specific virtual file. More...

Public Types
enum class	Kind : std::uint8_t { REGULAR , DIRECTORY , SYMLINK , OTHER }
	Virtual file entry type. More...

Public Member Functions
constexpr	File () noexcept=default
	Construct a closed virtual file handle without an associated file. More...

constexpr	operator bool () const noexcept
	Check if the file handle has an open file associated with it. More...

void	close ()
	Close the associated file so that it can no longer be accessed through this handle, and reset the handle to a closed virtual file handle without an associated file. More...

constexpr bool	isOpen () const noexcept
	Check if the file handle has an open file associated with it. More...

bool	eof () const noexcept
	Check if the end of the file has been reached. More...

std::size_t	size () const noexcept
	Get the readable length of the full file contents, in bytes. More...

std::size_t	tellg () const noexcept
	Get the current reading position of the file. More...

std::size_t	tellp () const noexcept
	Get the current writing position of the file. More...

void	seekg (std::size_t position)
	Set the file reading position to an absolute offset from the beginning of the file. More...

void	seekp (std::size_t position)
	Set the file writing position to an absolute offset from the beginning of the file. More...

void	skipg (std::ptrdiff_t offset)
	Advance the file reading position by a relative offset, which may be negative in order to go backwards. More...

void	skipp (std::ptrdiff_t offset)
	Advance the file writing position by a relative offset, which may be negative in order to go backwards. More...

std::vector< std::byte >	readAll () &&
	Read the full contents of an open file into an array of bytes. More...

std::string	readAllIntoString () &&
	Read the full contents of an open file into a string of bytes. More...

std::size_t	read (std::span< std::byte > data)
	Read data from an open file into a buffer, starting at the current reading position. More...

std::size_t	write (std::span< const std::byte > data)
	Write data to the end of an open file from a buffer. More...

void	flush ()
	Synchronize with the underlying file to make sure that all buffered data that has been written so far is flushed into the actual file. More...

Static Public Attributes
static constexpr std::size_t	NPOS = static_cast<std::size_t>(-1)
	Invalid value for a file offset, used as an end-of-file marker. More...

Detailed Description

Unique handle to a file in the virtual Filesystem.

Warning: This file handle type may only be used during the lifetime of a Filesystem object, which initializes the relevant global context upon construction. Attempting to use the File API without an active Filesystem results in undefined behavior.

Member Enumeration Documentation

◆ Kind

enum donut::File::Kind : std::uint8_t

strong

Virtual file entry type.

Enumerator
REGULAR	Regular file.
DIRECTORY	Directory/folder.
SYMLINK	Symbolic link.
OTHER	Something else, such as a network socket or a device.

Constructor & Destructor Documentation

◆ File()

constexpr donut::File::File ( )

constexprdefaultnoexcept

Construct a closed virtual file handle without an associated file.

Member Function Documentation

◆ operator bool()

constexpr donut::File::operator bool ( ) const

inlineexplicitconstexprnoexcept

Check if the file handle has an open file associated with it.

Returns: true if there is an associated open file, false otherwise.

◆ close()

void donut::File::close ( )

Close the associated file so that it can no longer be accessed through this handle, and reset the handle to a closed virtual file handle without an associated file.

Exceptions

Error	on failure to close the file.
std::bad_alloc	on allocation failure.

Note: This function has no effect if the handle has no open file associated with it.

See also: ~File()

◆ isOpen()

constexpr bool donut::File::isOpen ( ) const

inlineconstexprnoexcept

Check if the file handle has an open file associated with it.

Returns: true if there is an associated open file, false otherwise.

◆ eof()

bool donut::File::eof ( ) const

noexcept

Check if the end of the file has been reached.

Returns: true if the end of the file has been reached, false otherwise.

◆ size()

std::size_t donut::File::size ( ) const

noexcept

Get the readable length of the full file contents, in bytes.

Returns: the length of the file, or File::NPOS if the length cannot be determined.

◆ tellg()

std::size_t donut::File::tellg ( ) const

noexcept

Get the current reading position of the file.

Returns: the current file reading position, or File::NPOS if it cannot be determined.

◆ tellp()

std::size_t donut::File::tellp ( ) const

noexcept

Get the current writing position of the file.

Returns: the current file writing position, or File::NPOS if it cannot be determined.

◆ seekg()

void donut::File::seekg ( std::size_t position )

Set the file reading position to an absolute offset from the beginning of the file.

Parameters

position the new reading position to set.

Exceptions

File::Error on failure to seek to the given position.

Note: Attempting to seek to a position outside the readable length of the file will cause the function to fail.

◆ seekp()

void donut::File::seekp ( std::size_t position )

Set the file writing position to an absolute offset from the beginning of the file.

Parameters

position the new writing position to set.

Exceptions

File::Error on failure to seek to the given position.

Note: Attempting to seek to a position outside the readable length of the file will cause the function to fail.

◆ skipg()

void donut::File::skipg ( std::ptrdiff_t offset )

Advance the file reading position by a relative offset, which may be negative in order to go backwards.

Parameters

offset the relative offset to advance the reading position by.

Exceptions

File::Error on failure to skip by the given offset.

Note: Attempting to seek to a position outside the readable length of the file will cause the function to fail.

◆ skipp()

void donut::File::skipp ( std::ptrdiff_t offset )

Advance the file writing position by a relative offset, which may be negative in order to go backwards.

Parameters

offset the relative offset to advance the writing position by.

Exceptions

File::Error on failure to skip by the given offset.

Note: Attempting to seek to a position outside the readable length of the file will cause the function to fail.

◆ readAll()

std::vector<std::byte> donut::File::readAll ( ) &&

Read the full contents of an open file into an array of bytes.

Returns: a contiguous container containing a copy of the full contents of the file.

Exceptions

File::Error	on failure to read the file contents.
std::bad_alloc	on allocation failure.

◆ readAllIntoString()

std::string donut::File::readAllIntoString ( ) &&

Read the full contents of an open file into a string of bytes.

Returns: a string containing a copy of the full contents of the file.

Exceptions

File::Error	on failure to read the file contents.
std::bad_alloc	on allocation failure.

◆ read()

std::size_t donut::File::read ( std::span< std::byte > data )

Read data from an open file into a buffer, starting at the current reading position.

The reading position is advanced to the end of the bytes that were read.

Parameters

data	writable span over the buffer to read file data into. The size of the span determines the number of bytes that are attempted to be read.

Returns: the number of bytes that were successfully read, which may be any non-negative integer less than or equal to the size of the given span, including 0.

Note: If the end of the file is reached before the entire span's worth of data could be read, this will be reflected in the returned number of read bytes.

Exceptions

File::Error on failure to read from the file.

◆ write()

std::size_t donut::File::write ( std::span< const std::byte > data )

Write data to the end of an open file from a buffer.

The writing position is advanced to the new end of the file.

Parameters

data	read-only view over the buffer to copy the data from. The size of the buffer determines the number of bytes that are attempted to be written.

Returns: the number of bytes that were successfully written, which may be any non-negative integer less than or equal to the size of the given view, including 0.

Exceptions

File::Error on failure to write to the file.

◆ flush()

void donut::File::flush ( )

Synchronize with the underlying file to make sure that all buffered data that has been written so far is flushed into the actual file.

Exceptions

File::Error on failure to synchronize with the file.

Member Data Documentation

◆ NPOS

constexpr std::size_t donut::File::NPOS = static_cast<std::size_t>(-1)

staticconstexpr

Invalid value for a file offset, used as an end-of-file marker.

The documentation for this class was generated from the following file:

include/donut/File.hpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ Kind

Constructor & Destructor Documentation

◆ File()

Member Function Documentation

◆ operator bool()

◆ close()

◆ isOpen()

◆ eof()

◆ size()

◆ tellg()

◆ tellp()

◆ seekg()

◆ seekp()

◆ skipg()

◆ skipp()

◆ readAll()

◆ readAllIntoString()

◆ read()

◆ write()

◆ flush()

Member Data Documentation

◆ NPOS