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

A stream that reads from a file. More...

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

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

Public Member Functions
	FileInputStream ()=default
	Default constructor.
	FileInputStream (const std::filesystem::path &path)
	Constructor that opens a file.
	FileInputStream (File &&file) noexcept
	Constructor that takes ownership of an existing file.
	~FileInputStream () noexcept
	Destructor.
auto	operator= (File &&file) noexcept -> FileInputStream &
	Assignment operator that takes ownership of an existing file.
auto	open (const std::filesystem::path &path) -> void
	Opens a file.
auto	size () const -> std::size_t
	Gets the size of the file.
auto	close () noexcept -> void
	Closes the file, if it is open.
Public Member Functions inherited from xentara::utils::io::AbstractBufferedInputStream< Element >
	AbstractBufferedInputStream ()=default
	Default constructor Creates a stream without a buffer.
Public Member Functions inherited from xentara::utils::io::InputStream< Element >
virtual	~InputStream () noexcept(false)=0
	Virtual, throwing destructor.
auto	readElement () -> Element
	Read a single element from the stream.
auto	tryReadElement () -> std::optional< Element >
	Tries to read a single element from a stream.
template<Element kNoMoreData>
auto	readElementOr () -> Element
	Tries to read a single element from a stream.
auto	peek () -> Element
	Look at the next element in the stream without actually reading it.
auto	tryPeek () -> std::optional< Element >
	Look at the next element in the stream without actually reading it.
template<Element kNoMoreData>
auto	peekOr () -> Element
	Look at the next element in the stream without actually reading it.
auto	readFromBuffer (std::size_t maxSize) -> std::span< const Element >
	Reads data from the buffer only.
auto	eof () -> bool
	Checks if the end of the stream has been reached.
template<Element... kAllowedElements>
auto	readElementIf () -> std::optional< Element >
	Read an element from the stream if it is one of a list of allowed elements.
template<std::predicate< Element > Predicate>
auto	readElementIf (Predicate predicate) -> std::optional< Element >
	Read an element from the stream if it fits a predicate.
template<Element kFallback, Element... kAllowedElements>
auto	readElementIfOr () -> Element
	Read an element from the stream if it is one of a list of allowed elements.
template<Element kFallback, std::predicate< Element > Predicate>
auto	readElementIfOr (Predicate predicate) -> Element
	Read an element from the stream if it fits a predicate.
template<tools::Allocator< Element > Allocator = std::allocator<Element>> requires (!tools::CharType<Element>)
auto	read (typename std::allocator_traits< Allocator >::size_type size, const Allocator &allocator=Allocator()) -> core::RawVector< Element, Allocator >
	Read a block of data of a specific size.
template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>> requires tools::CharType<Element>
auto	read (typename std::allocator_traits< Allocator >::size_type size, const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Read a block of text of a specific size.
template<std::size_t kArraySize>
auto	read (Element(&array)[kArraySize]) -> void
	Read a block of data into an array.
template<std::size_t kArraySize>
auto	read (std::array< Element, kArraySize > &array) -> void
	Read a block of 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>>, Element>
auto	read (Iterator first, Sentinel last) -> void
	Read a block of data into an iterator range.
auto	read (Element *buffer, std::size_t size) -> void
	Read a block of data into a buffer.
template<Element... kTerminations> requires (!tools::CharType<Element>)
auto	readUntil () -> core::RawVector< Element >
	Reads all elements until a termination is found.
template<tools::Allocator< Element > Allocator, Element... kTerminations> requires (!tools::CharType<Element>)
auto	readUntil (const Allocator &allocator=Allocator()) -> core::RawVector< Element, Allocator >
	Reads all elements until a termination is found.
template<tools::Allocator< Element > Allocator = std::allocator<Element>, std::predicate< Element > Predicate> requires (!tools::CharType<Element>)
auto	readUntil (Predicate predicate, const Allocator &allocator=Allocator()) -> core::RawVector< Element, Allocator >
	Skips all elements until a termination element that fits a predicate.
template<Element... kTerminations> requires tools::CharType<Element>
auto	readUntil () -> std::basic_string< Element >
	Reads all characters until a termination is found.
template<typename CharTraits , Element... kTerminations> requires tools::CharType<Element>
auto	readUntil () -> std::basic_string< Element, CharTraits >
	Reads all characters until a termination is found.
template<typename CharTraits , tools::Allocator< Element > Allocator, Element... kTerminations> requires tools::CharType<Element>
auto	readUntil (const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Reads all characters until a termination is found.
template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>, std::predicate< Element > Predicate> requires tools::CharType<Element>
auto	readUntil (Predicate predicate, const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Skips all characters until a termination character that fits a predicate.
auto	skipElement () -> void
	Skips a single element from the stream.
auto	trySkipElement () -> bool
	Tries to skip a single element from a stream.
auto	skip (std::size_t size) -> void
	Skips a block of data.
template<Element... kSkippableElements>
auto	skipWhile () -> std::size_t
	Skips all elements than appear in a list of skippable elements.
template<std::predicate< Element > Predicate>
auto	skipWhile (Predicate predicate) -> std::size_t
	Skips all elements that fit a predicate.
auto	readPosition () const -> std::optional< ReadPosition >
	Gets the current read position within the stream.
auto	setReadPosition (ReadPosition position) -> void
	Sets the current read position within the device.
auto	rewind () -> void
	Sets the current read position to the beginning of the stream.
template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>> requires tools::CharType<Element>
auto	readLine (const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Reads a single line.
auto	skipLine () -> std::size_t
	Skips the rest of the line.
template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>> requires tools::CharType<Element>
auto	readWord (const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Reads a single whitespace-separated word.
auto	skipWord () -> std::size_t
	Skips the rest of a whitespace-separated word.
auto	skipLineEnding () -> bool
	Skips a single line termination.
auto	skipWhitespace () -> bool
	Skips all ASCII whitespace elements.
auto	readByte () -> Element
	Alternate name for readElement()
auto	tryReadByte () -> std::optional< Element >
	Alternate name for tryReadElement()
template<Element kNoMoreData> requires (!tools::CharType<Element>)
auto	readByteOr () -> Element
	Alternate name for readElementOr()
template<Element... kAllowedElements> requires (!tools::CharType<Element>)
auto	readByteIf () -> std::optional< Element >
	Alternate name for readElementIf()
template<std::predicate< Element > Predicate> requires (!tools::CharType<Element>)
auto	readByteIf (Predicate predicate) -> std::optional< Element >
	Alternate name for readElementIf().
template<Element kFallback, Element... kAllowedElements> requires (!tools::CharType<Element>)
auto	readByteIfOr () -> Element
	Alternate name for readElementIfOr()
template<Element kFallback, std::predicate< Element > Predicate> requires (!tools::CharType<Element>)
auto	readByteIfOr (Predicate predicate) -> Element
	Alternate name for readElementIfOr().
auto	skipByte () -> void
	Alternate name for skipElement()
auto	trySkipByte () -> bool
	Alternate name for trySkipElement() for character streams.
auto	readChar () -> Element
	Alternate name for readElement()
auto	tryReadChar () -> std::optional< Element >
	Alternate name for tryReadElement()
template<Element kNoMoreData> requires tools::CharType<Element>
auto	readCharOr () -> Element
	Alternate name for readElementOr()
template<Element... kAllowedElements> requires tools::CharType<Element>
auto	readCharIf () -> std::optional< Element >
	Alternate name for readElementIf()
template<std::predicate< Element > Predicate> requires tools::CharType<Element>
auto	readCharIf (Predicate predicate) -> std::optional< Element >
	Alternate name for readElementIf().
template<Element kFallback, Element... kAllowedElements> requires tools::CharType<Element>
auto	readCharIfOr () -> Element
	Alternate name for readElementIfOr()
template<Element kFallback, std::predicate< Element > Predicate> requires tools::CharType<Element>
auto	readCharIfOr (Predicate predicate) -> Element
	Alternate name for readElementIfOr().
auto	skipChar () -> void
	Alternate name for skipElement()
auto	trySkipChar () -> bool
	Alternate name for trySkipElement() for character streams.
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.
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::InputStream< Element >
using	element_type = Element
	The element type.
Protected Member Functions inherited from xentara::utils::io::AbstractDeviceInputStream< Element >
virtual auto	inputDevice () noexcept -> InputDevice &=0
	Called by the framework to get the device.
auto	doGetStreamDescription () const -> std::string override
	Implementation of InputStream::doGetStreamDescription()
auto	doRead (Element *buffer, std::size_t size, bool waitForData) -> std::optional< std::size_t > final
	Implementation of InputStream::doRead()
virtual auto	doThrowEndOfStreamError () const -> void final
	Implementation of InputStream::doRead()
auto	doWaitForData (std::optional< std::chrono::nanoseconds > timeout) -> bool final
	Implementation of InputStream::doWaitForData()
auto	doGetReadPosition () const -> std::optional< std::size_t > final
	Implementation of InputStream::doGetReadPosition()
auto	doSetReadPosition (std::size_t position) -> bool final
	Implementation of InputStream::doSetReadPosition()
auto	doAdvanceReadPosition (std::size_t offset) -> std::optional< std::size_t > final
	Implementation of InputStream::doAdvanceReadPosition()
Protected Member Functions inherited from xentara::utils::io::AbstractBufferedInputStream< Element >
auto	resetInputBuffer (std::size_t bufferSizeHint=kDefaultBufferSize) -> void
	Resets the buffer.
auto	destroyInputBuffer () -> void
	Destroys the buffer.
Protected Member Functions inherited from xentara::utils::io::InputStream< Element >
	InputStream () noexcept=default
	Default constructor.
	InputStream (Element *bufferBegin, Element *bufferEnd) noexcept
	Constructor that sets an initially empty buffer.
	InputStream (Element *bufferBegin, Element *bufferEnd, Element *dataBegin, Element *dataEnd) noexcept
	Constructor that sets a buffer that possibly already contains some data.
	InputStream (InputStream &&other) noexcept
	Move constructor.
auto	operator= (InputStream &&rhs) noexcept -> InputStream &
	Move assignemnt operator.
auto	setReadBuffer (Element *bufferBegin, Element *bufferEnd) noexcept -> void
	Sets a new empty buffer.
auto	setReadBuffer (Element *bufferBegin, Element *bufferEnd, Element *dataBegin, Element *dataEnd) noexcept -> void
	Sets the buffer.
auto	setReadData (Element *dataBegin, Element *dataEnd) noexcept -> void
	Sets the position of the data within the buffer.
auto	readBufferBegin () const -> Element *
	Reads back the buffer start position.
auto	readBufferEnd () const -> Element *
	Reads back the buffer end position.
auto	readBufferSize () const -> std::size_t
	Gets the buffer size.
auto	readDataBegin () const -> Element *
	Returns the beginning of the unconsumed data in the buffer.
auto	readDataEnd () const -> Element *
	Returns the end of the data in the buffer.
auto	readDataSize () const -> std::size_t
	Returns the size of the unconsumed data in the buffer.
virtual auto	doReplenishReadBuffer (bool waitForData) -> bool
	Called by the framework to place more data into the buffer when it is exhausted.
Static Protected Attributes inherited from xentara::utils::io::AbstractBufferedInputStream< 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::FileInputStream< Element >

A stream that reads from a file.

Constructor & Destructor Documentation

FileInputStream() [1/3]

template<StreamElement Element>

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

default

Default constructor.

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

FileInputStream() [2/3]

template<StreamElement Element>

xentara::utils::io::FileInputStream< Element >::FileInputStream

(

const std::filesystem::path &

path

)

Constructor that opens a file.

Parameters

path	The path to open

Exceptions

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

FileInputStream() [3/3]

template<StreamElement Element>

xentara::utils::io::FileInputStream< Element >::FileInputStream ( 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 readable.

~FileInputStream()

template<StreamElement Element>

xentara::utils::io::FileInputStream< Element >::~FileInputStream ( )

noexcept

Destructor.

This destructor closes the file, if it is open.

Member Function Documentation

close()

template<StreamElement Element>

auto xentara::utils::io::FileInputStream< Element >::close ( ) -> void

noexcept

Closes the file, if it is open.

open()

template<StreamElement Element>

auto xentara::utils::io::FileInputStream< Element >::open

(

const std::filesystem::path &

path

)

-> void

Opens a file.

Any file already open is silently closed

Parameters

path	The path to open

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::FileInputStream< Element >::operator= ( File &&  file ) -> FileInputStream &

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 readable. return A reference to this object.

size()

template<StreamElement Element>

auto xentara::utils::io::FileInputStream< Element >::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