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

A stream that reads data from memory. More...

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

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

Public Member Functions
template<memory::MemoryIterator< Element > Iterator>
	MemoryInputStream (Iterator begin, Iterator end)
	Constructs a stream that reads from a memory region defined by a pair of iterators.
template<memory::MemoryIterator< Element > Iterator>
	MemoryInputStream (Iterator begin, std::iter_difference_t< Iterator > size)
	Constructs a stream that reads from a memory region defined by an iterator and a size.
template<memory::VoidPointer Pointer>
	MemoryInputStream (Pointer begin, Pointer end)
	Constructs a stream that reads from a memory region defined by a pair of void pointers.
template<memory::VoidPointer Pointer>
	MemoryInputStream (Pointer begin, std::size_t size)
	Constructs a stream that reads from a memory region defined by a void pointer and a size.
template<memory::MemoryRegion< Element > Region>
	MemoryInputStream (const Region &region)
	Constructs a stream that reads from a memory region.
Accessing the Read Position as a pointer
auto	rawReadPosition () const -> const Element *
	Gets the current read position as a pointer.
auto	setRawReadPosition (const Element *rawPosition) -> void
	Sets the current read position within the device.
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::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.
virtual auto	doRead (Element *buffer, std::size_t size, bool waitForData) -> std::optional< std::size_t >=0
	Called by the framework to read data into a memory buffer.
virtual auto	doThrowEndOfStreamError () const -> void
	Called by the framework to throw an error denoting the end of the stream.
virtual auto	doWaitForData (std::optional< std::chrono::nanoseconds > timeout) -> bool
	Called by the framework to wait for more data to become available.
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) -> bool
	Called by the framework to set the current read position within the device.
virtual auto	doAdvanceReadPosition (std::size_t offset) -> std::optional< std::size_t >
	Advances the current read position within the device.
Protected Member Functions inherited from xentara::utils::io::StreamBase
virtual auto	doGetStreamDescription () const -> std::string=0
	Called by the framework to get a description of the stream.

Detailed Description

template<StreamElement Element>
class xentara::utils::io::MemoryInputStream< Element >

A stream that reads data from memory.

Constructor & Destructor Documentation

MemoryInputStream() [1/5]

template<StreamElement Element>

template<memory::MemoryIterator< Element > Iterator>

xentara::utils::io::MemoryInputStream< Element >::MemoryInputStream	(	Iterator	begin,
		Iterator	end
	)

Constructs a stream that reads from a memory region defined by a pair of iterators.

Parameters

begin	An iterator that points at the beginning of the memory region
end	An iterator that points at the end of the memory region

MemoryInputStream() [2/5]

template<StreamElement Element>

template<memory::MemoryIterator< Element > Iterator>

xentara::utils::io::MemoryInputStream< Element >::MemoryInputStream	(	Iterator	begin,
		std::iter_difference_t< Iterator >	size
	)

Constructs a stream that reads from a memory region defined by an iterator and a size.

Parameters

begin	An iterator that points at the beginning of the memory region
size	The size of the memory region

MemoryInputStream() [3/5]

template<StreamElement Element>

template<memory::VoidPointer Pointer>

xentara::utils::io::MemoryInputStream< Element >::MemoryInputStream	(	Pointer	begin,
		Pointer	end
	)

Constructs a stream that reads from a memory region defined by a pair of void pointers.

Attention

The memory must be properly aligned to hold elements of type Element.

Parameters

begin	An iterator that points at the beginning of the memory region
end	An iterator that points at the end of the memory region

MemoryInputStream() [4/5]

template<StreamElement Element>

template<memory::VoidPointer Pointer>

xentara::utils::io::MemoryInputStream< Element >::MemoryInputStream	(	Pointer	begin,
		std::size_t	size
	)

Constructs a stream that reads from a memory region defined by a void pointer and a size.

Attention

The memory must be properly aligned to hold elements of type Element.

Parameters

begin	An iterator that points at the beginning of the memory region
size	The size of the memory region, in bytes

MemoryInputStream() [5/5]

template<StreamElement Element>

template<memory::MemoryRegion< Element > Region>

xentara::utils::io::MemoryInputStream< Element >::MemoryInputStream

(

const Region &

region

)

Constructs a stream that reads from a memory region.

Parameters

region

The memory region

Member Function Documentation

rawReadPosition()

template<StreamElement Element>

auto xentara::utils::io::MemoryInputStream< Element >::rawReadPosition

(

)

const -> const Element *

Gets the current read position as a pointer.

Returns

A pointer to the next element that will be read, or a pointer to the position past the end of the data if all data has already been read.

setRawReadPosition()

template<StreamElement Element>

auto xentara::utils::io::MemoryInputStream< Element >::setRawReadPosition

(

const Element *

rawPosition

)

-> void

Sets the current read position within the device.

Parameters

rawPosition

The desired position. This must be pointer to a valid element within the data, or a pointer to the position past the end of the data to mark the stream as exhausted.