Base class for input streams. More...

#include <io/InputStream.hpp>

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

Classes
class	ReadPosition
	A class used to remember positions with the stream. More...

Public Types
using	element_type = Element
	The element type.

Public Member Functions
virtual	~InputStream () noexcept(false)=0
	Virtual, throwing destructor.

Read Functions
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.

Conditional Read Functions
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.

Block Read Functions
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.

Terminated Read Functions
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.

Functions for Skipping Data
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.

Accessing the Read Position
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.

Text stream functions
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.

Alternate function names for byte streams
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.

Alternate function names 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.

Waiting for Read Data
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.

Protected Member Functions
	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::InputStream< Element >

Base class for input streams.

Input streams provide an efficient way of accessing the data supplied by a device as a sequence of elements. Input streams buffer the data, and hence generally provide better performance than raw devices.

Note: When deriving this class, you must supply a memory region to be used as read buffer. The derived class is responsible for allocating and deallocating the buffer, if this is necessary. This class only tracks the location of the buffer, it does not take ownership or responsibility for it.

Template Parameters

Element The type of element the stream contains

Member Typedef Documentation

◆ element_type

template<StreamElement Element>

using xentara::utils::io::InputStream< Element >::element_type = Element

The element type.

Constructor & Destructor Documentation

◆ ~InputStream()

template<StreamElement Element>

virtual xentara::utils::io::InputStream< Element >::~InputStream ( )

pure virtual

Virtual, throwing destructor.

◆ InputStream() [1/4]

template<StreamElement Element>

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

protecteddefaultnoexcept

Default constructor.

This constructor creates an empty stream with no buffer. You can set a buffer later on using the function setReadBuffer()

◆ InputStream() [2/4]

template<StreamElement Element>

xentara::utils::io::InputStream< Element >::InputStream	(	Element *	bufferBegin,
		Element *	bufferEnd
	)

protectednoexcept

Constructor that sets an initially empty buffer.

Note: The derived class is responsible for allocating and deallocating the buffer, if this is necessary. This class only tracks the location of the buffer, it does not take ownership or responsibility for it.

Parameters

bufferBegin	A pointer to the beginning of the read buffer
bufferEnd	A pointer one past the end of the buffer

◆ InputStream() [3/4]

template<StreamElement Element>

xentara::utils::io::InputStream< Element >::InputStream	(	Element *	bufferBegin,
		Element *	bufferEnd,
		Element *	dataBegin,
		Element *	dataEnd
	)

protectednoexcept

Constructor that sets a buffer that possibly already contains some data.

Note: The derived class is responsible for allocating and deallocating the buffer, if this is necessary. This class only tracks the location of the buffer, it does not take ownership or responsibility for it.

Parameters

bufferBegin	A pointer to the beginning of the read buffer
bufferEnd	A pointer one past the end of the buffer
dataBegin	A pointer to the data already in the buffer
dataEnd	A pointer one past the end of the data already in the buffer

◆ InputStream() [4/4]

template<StreamElement Element>

xentara::utils::io::InputStream< Element >::InputStream ( InputStream< Element > && other )

protectednoexcept

Move constructor.

This function will transfer the buffer and data positions from the other stream. The buffer and data positions of the other stream will be left as nullptr.

Parameters

other The stream to move from

Member Function Documentation

◆ doAdvanceReadPosition()

template<StreamElement Element>

virtual auto xentara::utils::io::InputStream< Element >::doAdvanceReadPosition ( std::size_t offset ) -> std::optional<std::size_t>

protectedvirtual

Advances the current read position within the device.

The framework will discard all data in the buffer before calling this function, so that the buffer read position will be at the end of the data in the buffer.

If necessary or convenient, a reimplementation of this function may place new data into the buffer using setReadData(), or relocate or resize the buffer using setReadBuffer(). The derived class is then responsible for allocating the new buffer and deallocating the old buffer, if necessary. This class only tracks the location of the buffer, it does not take ownership or responsibility for it.

Default Implementation: The default implementation returns std::nullopt

Parameters

offset The desired offset for the read position from the current position. This offset may put the position past the end of the device, in which case the position must be set to the exact end of the device.

Returns: The amount that the read position was actually moved, or std::nullopt if the device does not support the functionality.

Exceptions

std::runtime_error The functionality is supported in principal, but an error occurred

Reimplemented in xentara::utils::io::AbstractDeviceInputStream< Element >.

◆ doGetReadPosition()

template<StreamElement Element>

virtual auto xentara::utils::io::InputStream< Element >::doGetReadPosition ( ) const -> std::optional<std::size_t>

protectedvirtual

Called by the framework to get the current read position within the device.

Default Implementation: The default implementation returns std::nullopt

Returns: The read position as an offset from the beginning of the device, or std::nullopt if the device does not support the functionality.

Exceptions

std::runtime_error The functionality is supported in principal, but an error occurred

Reimplemented in xentara::utils::io::AbstractDeviceInputStream< Element >.

◆ doRead()

template<StreamElement Element>

virtual auto xentara::utils::io::InputStream< Element >::doRead	(	Element *	buffer,
		std::size_t	size,
		bool	waitForData
	)		-> std::optional< std::size_t >

protectedpure virtual

Called by the framework to read data into a memory buffer.

This function must read data into the given buffer, up to the maximum size specified.

This function is used in two ways:

The default implementaion of doReplenishReadBuffer() calls this function to replenish the read buffer if it is exhausted. doReplenishReadBuffer() will always pass the entire read buffer in buffer and size.
The framework will also call this function if it whishes to bypass the normal read buffer and read data from the stream directly. In this case the given buffer will always lie entirely outside the normal read buffer.

In either case, this function is only ever called when the normal read buffer is empty.

If no data could be read because the end of the stream has been reached (e.g. at end of a file, or if acommunication stream was closed gracefully), this function must return 0, or throw an error of type EndOfStreamError. On communication devices, any EndOfStreamError thrown should also derive from ConnectionClosed, e.g. by using throwWithConnectionClosed().

If the read on a communications stream would block, the behaviour of this function depends on the value of the parameter waitForData. If waitForData is false, the function must return std::nullopt immediately. If waitForData is true, the function must first wait for a short time for any new data to arrive, and only return std::nullopt if the wait times out. Alternatively, an exception of type ReadTimeoutError can be thrown on if the wait times out. If the wait succeeds, the function must then attempt to read the newly arrived data, and return the data length or throw an exception accordingly. The exact length of the read timeout is left up to the individual implementation.

Non-communication streams should ignore the waitForData flag, and never return std::nullopt or throw an exception of type ReadTimeoutError.

Parameters

buffer	A pointer to the buffer that will receive the data. This is not necessarily the normal read buffer (see above).
size	The amout of data to read. The framework will never pass 0 for this parameter. Please note that this value may be greater than the maximum read size of the operating system (SSIZE_MAX on Posix, maximum DWORD value on Windows). Care must be taken to account for this in the implementation.
waitForData	A flag is used to tell a communication stream whether to wait for data or not. Non-communication streams should ignore this flag.

Returns

The number of bytes actually read, or 0 if the end of the stream has been reached. Communication streams must return std::nullopt if no data was read, but more data might be available after calling doWaitForData(). Non-communication streams must never return std::nullopt.

Instead of returning 0 or std::nullopt to signal the end of stream or a blocking read, the function can throw an exception of type EndOfStreamError or ReadTimeoutError as described below.

Exceptions

EndOfStreamError	An exception of this type (or of a suitable subclass) can be thrown instead of returning 0 if the end of the stream has been reached. On communication devices, any EndOfStreamError thrown should also derive from ConnectionClosed, e.g. by using throwWithConnectionClosed().
ReadTimeoutError	An exception of this type (or of a suitable subclass) can be thrown by communications streams instead of returning std::nullopt if no data was read, but more data might be available later.
StopRequested	Implementations that use a stop source should throw this exception if waitForData is true, and the stop source was triggered when waiting for data.
std::runtime_error	This exception or an appropriate subclass must be thrown if an error occurs.

Implemented in xentara::utils::io::AbstractDeviceInputStream< Element >.

◆ doReplenishReadBuffer()

template<StreamElement Element>

virtual auto xentara::utils::io::InputStream< Element >::doReplenishReadBuffer ( bool waitForData ) -> bool

protectedvirtual

Called by the framework to place more data into the buffer when it is exhausted.

This function must replenish the buffer with new data from the stream, and call setReadData() to specify the location of the new data within the buffer. If the device supports read positions, this function should read data from the device’s current read position, and advance the read position accordingly, as if conducting a regular read.

If no data could be read because the end of the stream has been reached (e.g. at end of a file, or if acommunication stream was closed gracefully), this function must clear the buffer by setting the beginning and end to the same location. Alternatively, an error of type EndOfStreamError can be thrown. On communication devices, any EndOfStreamError thrown should also derive from ConnectionClosed, e.g. by using throwWithConnectionClosed().

If the read on a communications stream would block, the behaviour of this function depends on the value of the parameter waitForData. If waitForData is false, the function must return false immediately. If waitForData is true, the function must first wait for a short time for any new data to arrive, and only return false if the wait times out. Alternatively, an exception of type ReadTimeoutError can be thrown on if the wait times out. If the wait succeeds, the function must then attempt to read the newly arrived data, and agjust the buffer or throw an exception accordingly. The exact length of the read timeout is left up to the individual implementation.

The function must never return false if it placed any data into the read buffer. If you return false, the framework will assume no data could be read, and empty the buffer itself. This will discard any data you placed into the buffer.

A reimplementation of this function can relocate or resize the buffer, if it whishes, by calling setReadBuffer() instead of setReadData(). The derived class is then responsible for allocating the new buffer and deallocating the old buffer, if necessary. This class only tracks the location of the buffer, it does not take ownership or responsibility for it.

Default Implementation: The default implementation calls doRead() to try to fill the buffer with data.

Parameters

waitForData A flag is used to tell a communication stream whether to wait for data or not. Non-communication streams should ignore this flag.

Returns

This function must true if any data has been placed into the buffer, or if the end of stream has been reached.

Communication streams must return false if no data was placed into the buffer, but more data might be available after calling doWaitForData(). Non-communication streams must never return false.

Instead of returning false to signal a blocking read, a communication stream can throw an exception of type ReadTimeoutError as described below.

Exceptions

EndOfStreamError	An exception of this type (or of a suitable subclass) can be thrown instead of emptying the buffer if the end of the stream has been reached. On communication devices, any EndOfStreamError thrown should also derive from ConnectionClosed, e.g. by using throwWithConnectionClosed().
ReadTimeoutError	An exception of this type (or of a suitable subclass) can be thrown by communications streams instead of returning false if no data was placed into the buffer, but more data might be available later.
StopRequested	Implementations that use a stop source should throw this exception if waitForData is true, and the stop source was triggered when waiting for data.
std::runtime_error	This exception or an appropriate subclass must be thrown if an error occurs.

◆ doSetReadPosition()

template<StreamElement Element>

virtual auto xentara::utils::io::InputStream< Element >::doSetReadPosition ( std::size_t position ) -> bool

protectedvirtual

Called by the framework to set the current read position within the device.

The framework will clear the buffer before calling this function.

If necessary or convenient, a reimplementation of this function may place new data into the buffer using setReadData(), or relocate or resize the buffer using setReadBuffer(). The derived class is then responsible for allocating the new buffer and deallocating the old buffer, if necessary. This class only tracks the location of the buffer, it does not take ownership or responsibility for it.

If this function places new data into the buffer, the buffer read position must point to the data at position. The underlying devices's read position must, as always, point to the end of the data placed into the buffer, so that the next call to doReplenishReadBuffer() or doRead() will read the correct data.

The framework will not ask the device to set arbitrary read positions. The requested position will always be either 0, or a position you previously returned from doGetReadPosition().

Default Implementation: The default implementation returns false

Parameters

position The desired new read position. This will alway be either 0, or a position previously returned by doGetReadPosition().

Returns: false if the device does not support the functionality

Exceptions

std::runtime_error The functionality is supported in principal, but an error occurred

Reimplemented in xentara::utils::io::AbstractDeviceInputStream< Element >.

◆ doThrowEndOfStreamError()

template<StreamElement Element>

virtual auto xentara::utils::io::InputStream< Element >::doThrowEndOfStreamError ( ) const -> void

protectedvirtual

Called by the framework to throw an error denoting the end of the stream.

The framework calls this function if doReplenishReadBuffer() return true and cleared the buffer, if or doRead() returned 0, but more data was actually needed. Derived classes should throw an error of type EndOfStreamError with a descriptive text, like e.g. “end of file”, or “connection closed”.

Communication streams should throw an exception that also derives from ConnectionClosed, e.g. by using throwWithConnectionClosed().

Default Implementation: The default implementation throws a regular EndOfStreamError exception with a generic message.

Exceptions

EndOfStreamError This exception, or a suitable subclass, must always be thrown. Communication devices should throw an exception that derives from both EndOfStreamError and ConnectionClosed, e.g. by using throwWithConnectionClosed().

Reimplemented in xentara::utils::io::AbstractDeviceInputStream< Element >.

◆ doWaitForData()

template<StreamElement Element>

virtual auto xentara::utils::io::InputStream< Element >::doWaitForData ( std::optional< std::chrono::nanoseconds > timeout ) -> bool

protectedvirtual

Called by the framework to wait for more data to become available.

This function must wait for new data to become available for read.

This function is usually only overridden for communication streams, which will wait for the device to go into a readable state or into an error state.

Default Implementation: The default implementation returns true, indicating that the next read will not block.

Parameters

timeout The number of nanoseconds to wait, or std::nullopt to wait indefinitely. If a timeout of 0 is passed, the function should not wait, but simply return whether the device can be read without blocking or not. The framework will never pass a negative value.

Returns: This function must always return true, except when a timeout was specified, and the timeout elapsed before anything relevant happened. The function can return true even if attempting to read the device will result in an exception rather than a successful read.

Exceptions

StopRequested Implementations that use a stop source should throw this exception if the stop source was triggered.

std::runtime_error

This exception, or an appropriate subclass, must be thrown if an error occurs waiting for the data. Throwing an exception on error is optional if a subsequent call to doRead() or doReplenishReadBuffer() will itself throw a suitable exception.

Throwing an error is only required if doWaitForData() failed, but a subsequent call to doRead() or doReplenishReadBuffer() might still succeed. If this function uses the Linux poll(2) command, for example, and poll(2) sets the POLLERR flag in revents, you can just return true instead of throwing an exception, because a subsequent call to recv(2) is guaranteed to fail. If poll(2) returns -1, however, you must throw an exception, because a subsequent call to recv(2) might still be successful.

Reimplemented in xentara::utils::io::AbstractDeviceInputStream< Element >.

◆ eof()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::eof ( ) -> bool

Checks if the end of the stream has been reached.

On communication streams, this function checks whether the connection was gracefully closed.

Note: This function will actually check whether any more bytes are available. This differs from the behaviour of std::basic_ios::eof(), which merely checks whether an attempt was made to read past the end of the data.

Returns: Returns true if the stream is exhausted, or false if more characters can be read

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ operator=()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::operator= ( InputStream< Element > && rhs ) -> InputStream &

protectednoexcept

Move assignemnt operator.

This operator swaps the buffer and data positions of this object and the other object

Parameters

rhs	The stream to move from

Returns: A reference to this object

◆ peek()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::peek ( ) -> Element

Look at the next element in the stream without actually reading it.

Returns: The element that will be read next

Exceptions

EndOfStreamError	This exception is thrown if we are at the end of the data. On communication streams, this exception is also derived from ConnectionClosed and denotes that the connection was gracefully closed.
ReadTimeoutError	This exception is thrown on communication streams if data takes too long to arrive. This can mean that there is a network congestion, that the sender is too slow, or that the sender did not send enough data.
StopRequested	This exception is thrown on communication streams that use a stop source if the stop source was triggered while waiting for data.
std::runtime_error	An error occurred reading data from the underlying device
ConnectionClosed	On communication streams, any EndOfStreamError thrown is also derived from ConnectionClosed. This allows you to handle closed connections during read and write operations in the same catch block by catching exceptions of type ConnectionClosed.

◆ peekOr()

template<StreamElement Element>

template<Element kNoMoreData>

auto xentara::utils::io::InputStream< Element >::peekOr ( ) -> Element

Look at the next element in the stream without actually reading it.

Template Parameters

kNoMoreData The value to return for end of the data

Returns: The element that will be read next, or kNoMoreData if we are at the end of the data

Exceptions

std::runtime_error An error occurred reading data from the underlying device

◆ read() [1/6]

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::read	(	Element *	buffer,
		std::size_t	size
	)		-> void

Read a block of data into a buffer.

Parameters

buffer	A pointer to the buffer that will receive the data
size	The size of the buffer

Exceptions

EndOfStreamError	This exception is thrown if the end of the data is reached before the data was read. On communication streams, this exception is also derived from ConnectionClosed and denotes that the connection was gracefully closed.
ReadTimeoutError	This exception is thrown on communication streams if data takes too long to arrive. This can mean that there is a network congestion, that the sender is too slow, or that the sender did not send enough data.
StopRequested	This exception is thrown on communication streams that use a stop source if the stop source was triggered while waiting for data.
std::runtime_error	An error occurred reading data from the underlying device
ConnectionClosed	On communication streams, any EndOfStreamError thrown is also derived from ConnectionClosed. This allows you to handle closed connections during read and write operations in the same catch block by catching exceptions of type ConnectionClosed.

◆ read() [2/6]

template<StreamElement Element>

template<std::size_t kArraySize>

auto xentara::utils::io::InputStream< Element >::read ( Element(&) array[kArraySize] ) -> void

Read a block of data into an array.

Parameters

array The array that will receive the data

Template Parameters

kArraySize The size of the array

Exceptions

EndOfStreamError	This exception is thrown if the end of the data is reached before the data was read. On communication streams, this exception is also derived from ConnectionClosed and denotes that the connection was gracefully closed.
ReadTimeoutError	This exception is thrown on communication streams if data takes too long to arrive. This can mean that there is a network congestion, that the sender is too slow, or that the sender did not send enough data.
StopRequested	This exception is thrown on communication streams that use a stop source if the stop source was triggered while waiting for data.
std::runtime_error	An error occurred reading data from the underlying device
ConnectionClosed	On communication streams, any EndOfStreamError thrown is also derived from ConnectionClosed. This allows you to handle closed connections during read and write operations in the same catch block by catching exceptions of type ConnectionClosed.

◆ read() [3/6]

template<StreamElement Element>

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 xentara::utils::io::InputStream< Element >::read	(	Iterator	first,
		Sentinel	last
	)		-> void

Read a block of data into an iterator range.

Parameters

first	The beginning of the range
last	The postion after the end of the range

Exceptions

EndOfStreamError	This exception is thrown if the end of the data is reached before the data was read. On communication streams, this exception is also derived from ConnectionClosed and denotes that the connection was gracefully closed.
ReadTimeoutError	This exception is thrown on communication streams if data takes too long to arrive. This can mean that there is a network congestion, that the sender is too slow, or that the sender did not send enough data.
StopRequested	This exception is thrown on communication streams that use a stop source if the stop source was triggered while waiting for data.
std::runtime_error	An error occurred reading data from the underlying device
ConnectionClosed	On communication streams, any EndOfStreamError thrown is also derived from ConnectionClosed. This allows you to handle closed connections during read and write operations in the same catch block by catching exceptions of type ConnectionClosed.

◆ read() [4/6]

template<StreamElement Element>

template<std::size_t kArraySize>

auto xentara::utils::io::InputStream< Element >::read ( std::array< Element, kArraySize > & array ) -> void

Read a block of data into an array.

Parameters

array The array that will receive the data

Template Parameters

kArraySize The size of the buffer

Exceptions

EndOfStreamError	This exception is thrown if the end of the data is reached before the data was read. On communication streams, this exception is also derived from ConnectionClosed and denotes that the connection was gracefully closed.
ReadTimeoutError	This exception is thrown on communication streams if data takes too long to arrive. This can mean that there is a network congestion, that the sender is too slow, or that the sender did not send enough data.
StopRequested	This exception is thrown on communication streams that use a stop source if the stop source was triggered while waiting for data.
std::runtime_error	An error occurred reading data from the underlying device
ConnectionClosed	On communication streams, any EndOfStreamError thrown is also derived from ConnectionClosed. This allows you to handle closed connections during read and write operations in the same catch block by catching exceptions of type ConnectionClosed.

◆ read() [5/6]

template<StreamElement Element>

template<tools::Allocator< Element > Allocator = std::allocator<Element>>
requires (!tools::CharType<Element>)

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

Requirements:: This function is not available for streams with characters as elements.

Parameters

size	The size of the data block to read
allocator	The allocator to use for the returned vector

Returns: The data block read

Exceptions

EndOfStreamError	This exception is thrown if the end of the stream is reached before the requested number of elements were read. On communication streams, this exception is also derived from ConnectionClosed and denotes that the connection was gracefully closed.
ReadTimeoutError	This exception is thrown on communication streams if data takes too long to arrive. This can mean that there is a network congestion, that the sender is too slow, or that the sender did not send enough data.
StopRequested	This exception is thrown on communication streams that use a stop source if the stop source was triggered while waiting for data.
std::runtime_error	An error occurred reading data from the underlying device
ConnectionClosed	On communication streams, any EndOfStreamError thrown is also derived from ConnectionClosed. This allows you to handle closed connections during read and write operations in the same catch block by catching exceptions of type ConnectionClosed.

◆ read() [6/6]

template<StreamElement Element>

template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>>
requires tools::CharType<Element>

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

Requirements:: This function is only available for streams with characters as elements.

Parameters

size	The size of the text block to read
allocator	The allocator to use for the returned vector

Returns: The data block read

Exceptions

EndOfStreamError	This exception is thrown if the end of the data is reached before the data was read. On communication streams, this exception is also derived from ConnectionClosed and denotes that the connection was gracefully closed.
ReadTimeoutError	This exception is thrown on communication streams if data takes too long to arrive. This can mean that there is a network congestion, that the sender is too slow, or that the sender did not send enough data.
StopRequested	This exception is thrown on communication streams that use a stop source if the stop source was triggered while waiting for data.
std::runtime_error	An error occurred reading data from the underlying device
ConnectionClosed	On communication streams, any EndOfStreamError thrown is also derived from ConnectionClosed. This allows you to handle closed connections during read and write operations in the same catch block by catching exceptions of type ConnectionClosed.

◆ readBufferBegin()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::readBufferBegin ( ) const -> Element *

protected

Reads back the buffer start position.

This function merely returns the pointer set using one of the constructors or one of the setReadBuffer() functions

Returns: A pointer to the beginning of the read buffer you set

◆ readBufferEnd()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::readBufferEnd ( ) const -> Element *

protected

Reads back the buffer end position.

This function merely returns the pointer set using one of the constructors or one of the setReadBuffer() functions

Returns: A pointer one past the end of the buffer you set

◆ readBufferSize()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::readBufferSize ( ) const -> std::size_t

protected

Gets the buffer size.

This function merely returns the difference between the pointers set using one of the constructors or one of the setReadBuffer() functions.

Returns: The size of the buffer

◆ readByte()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::readByte ( ) -> Element

Alternate name for readElement()

Requirements:: This function is only available for streams element type std::byte.

◆ readByteIf() [1/2]

template<StreamElement Element>

template<Element... kAllowedElements>
requires (!tools::CharType<Element>)

auto xentara::utils::io::InputStream< Element >::readByteIf ( ) -> std::optional<Element>

Alternate name for readElementIf()

Requirements:: This function is only available for streams element type std::byte.

◆ readByteIf() [2/2]

template<StreamElement Element>

template<std::predicate< Element > Predicate>
requires (!tools::CharType<Element>)

auto xentara::utils::io::InputStream< Element >::readByteIf ( Predicate predicate ) -> std::optional<Element>

Alternate name for readElementIf().

Requirements:: This function is only available for streams element type std::byte.

◆ readByteIfOr() [1/2]

template<StreamElement Element>

template<Element kFallback, Element... kAllowedElements>
requires (!tools::CharType<Element>)

auto xentara::utils::io::InputStream< Element >::readByteIfOr ( ) -> Element

Alternate name for readElementIfOr()

Requirements:: This function is only available for streams element type std::byte.

◆ readByteIfOr() [2/2]

template<StreamElement Element>

template<Element kFallback, std::predicate< Element > Predicate>
requires (!tools::CharType<Element>)

auto xentara::utils::io::InputStream< Element >::readByteIfOr ( Predicate predicate ) -> Element

Alternate name for readElementIfOr().

Requirements:: This function is only available for streams element type std::byte.

◆ readByteOr()

template<StreamElement Element>

template<Element kNoMoreData>
requires (!tools::CharType<Element>)

auto xentara::utils::io::InputStream< Element >::readByteOr ( ) -> Element

Alternate name for readElementOr()

Requirements:: This function is only available for streams element type std::byte.

◆ readChar()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::readChar ( ) -> Element

Alternate name for readElement()

Requirements:: This function is only available for streams with characters as elements.

◆ readCharIf() [1/2]

template<StreamElement Element>

template<Element... kAllowedElements>
requires tools::CharType<Element>

auto xentara::utils::io::InputStream< Element >::readCharIf ( ) -> std::optional<Element>

Alternate name for readElementIf()

Requirements:: This function is only available for streams with characters as elements.

◆ readCharIf() [2/2]

template<StreamElement Element>

template<std::predicate< Element > Predicate>
requires tools::CharType<Element>

auto xentara::utils::io::InputStream< Element >::readCharIf ( Predicate predicate ) -> std::optional<Element>

Alternate name for readElementIf().

Requirements:: This function is only available for streams with characters as elements.

◆ readCharIfOr() [1/2]

template<StreamElement Element>

template<Element kFallback, Element... kAllowedElements>
requires tools::CharType<Element>

auto xentara::utils::io::InputStream< Element >::readCharIfOr ( ) -> Element

Alternate name for readElementIfOr()

Requirements:: This function is only available for streams with characters as elements.

◆ readCharIfOr() [2/2]

template<StreamElement Element>

template<Element kFallback, std::predicate< Element > Predicate>
requires tools::CharType<Element>

auto xentara::utils::io::InputStream< Element >::readCharIfOr ( Predicate predicate ) -> Element

Alternate name for readElementIfOr().

Requirements:: This function is only available for streams with characters as elements.

◆ readCharOr()

template<StreamElement Element>

template<Element kNoMoreData>
requires tools::CharType<Element>

auto xentara::utils::io::InputStream< Element >::readCharOr ( ) -> Element

Alternate name for readElementOr()

Requirements:: This function is only available for streams with characters as elements.

◆ readDataBegin()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::readDataBegin ( ) const -> Element *

protected

Returns the beginning of the unconsumed data in the buffer.

Returns: A pointer to the beginning of the buffered data that has not been read or skipped yet

◆ readDataEnd()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::readDataEnd ( ) const -> Element *

protected

Returns the end of the data in the buffer.

Returns: A pointer one past the end of the buffered data

◆ readDataSize()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::readDataSize ( ) const -> std::size_t

protected

Returns the size of the unconsumed data in the buffer.

Returns: The size of the buffered data that has not been read or skipped yet

◆ readElement()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::readElement ( ) -> Element

Read a single element from the stream.

Returns: The element that was read

Exceptions

EndOfStreamError	This exception is thrown if the end of the stream is reached before the element was read. On communication streams, this exception is also derived from ConnectionClosed and denotes that the connection was gracefully closed.
ReadTimeoutError	This exception is thrown on communication streams if data takes too long to arrive. This can mean that there is a network congestion, that the sender is too slow, or that the sender did not send enough data.
StopRequested	This exception is thrown on communication streams that use a stop source if the stop source was triggered while waiting for data.
std::runtime_error	An error occurred reading data from the underlying device
ConnectionClosed	On communication streams, any EndOfStreamError thrown is also derived from ConnectionClosed. This allows you to handle closed connections during read and write operations in the same catch block by catching exceptions of type ConnectionClosed.

◆ readElementIf() [1/2]

template<StreamElement Element>

template<Element... kAllowedElements>

auto xentara::utils::io::InputStream< Element >::readElementIf ( ) -> std::optional< Element >

Read an element from the stream if it is one of a list of allowed elements.

Template Parameters

kAllowedElements The allowed elements

Returns: The element that was read, or std::nullopt if the next element was not one of the allowed elements, or if the end of stream was reached before the element was read

Exceptions

std::runtime_error An error occurred reading data from the underlying device

◆ readElementIf() [2/2]

template<StreamElement Element>

template<std::predicate< Element > Predicate>

auto xentara::utils::io::InputStream< Element >::readElementIf ( Predicate predicate ) -> std::optional< Element >

Read an element from the stream if it fits a predicate.

Parameters

predicate The predicate to check

Returns: The element that was read, or std::nullopt if the next element did not match the predicate, or if the end of stream was reached before the element was read

Exceptions

std::runtime_error An error occurred reading data from the underlying device

◆ readElementIfOr() [1/2]

template<StreamElement Element>

template<Element kFallback, Element... kAllowedElements>

auto xentara::utils::io::InputStream< Element >::readElementIfOr ( ) -> Element

Read an element from the stream if it is one of a list of allowed elements.

Template Parameters

kFallback	The value to return for elements that do not fit the predicate and for end of the data
kAllowedElements	The allowed elements

Returns: The element that was read, or kFallback if the next element was not one of the allowed elements, or if the end of stream was reached before the element was read

Exceptions

std::runtime_error An error occurred reading data from the underlying device

◆ readElementIfOr() [2/2]

template<StreamElement Element>

template<Element kFallback, std::predicate< Element > Predicate>

auto xentara::utils::io::InputStream< Element >::readElementIfOr ( Predicate predicate ) -> Element

Read an element from the stream if it fits a predicate.

Template Parameters

kFallback The value to return for elements that do not fit the predicate and for end of the data

Parameters

predicate The predicate to check

Returns: The element that was read, or kFallback if the next element did not match the predicate, or if the end of stream was reached before the element was read

Exceptions

std::runtime_error An error occurred reading data from the underlying device

◆ readElementOr()

template<StreamElement Element>

template<Element kNoMoreData>

auto xentara::utils::io::InputStream< Element >::readElementOr ( ) -> Element

Tries to read a single element from a stream.

Template Parameters

kNoMoreData The value to return for end of the data

Returns: The element that was read, or kNoMoreData if the end of the data was reached before the element was read

Exceptions

std::runtime_error An error occurred reading data from the underlying device

◆ readFromBuffer()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::readFromBuffer ( std::size_t maxSize ) -> std::span< const Element >

Reads data from the buffer only.

This function will read all the remaining data in the buffer, up to a maximum size. If the buffer is exhausted, then an empty span will be returned. The function will never read from the underlying device.

Parameters

maxSize The maximum size of the data to read

Returns: A reference to the data within the buffer. The reference will remain valid until the next read.

Exceptions

std::runtime_error An error occurred reading data from the underlying device

◆ readLine()

template<StreamElement Element>

template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>>
requires tools::CharType<Element>

auto xentara::utils::io::InputStream< Element >::readLine ( const Allocator & allocator = Allocator() ) -> std::basic_string< Element, CharTraits, Allocator >

Reads a single line.

This function reads all characters until one of the unicode characters LINE FEED or CARRIAGE RETURN is encountered, or until the stream is exhausted. The line termination itself is not read or returned. You can use skipLineEnding() to check for and skip over the line termination.

Parameters

allocator The allocator to use for the returned string

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ readPosition()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::readPosition ( ) const -> std::optional< ReadPosition >

Gets the current read position within the stream.

Returns: The current read position, or std::nullopt if the underlying device does not support getting and setting the read position

Exceptions

std::runtime_error The device supports getting and setting the read position, but an error occurred

◆ readUntil() [1/7]

template<StreamElement Element>

template<Element... kTerminations>
requires (!tools::CharType<Element>)

auto xentara::utils::io::InputStream< Element >::readUntil ( ) -> core::RawVector<Element>

Reads all elements until a termination is found.

This function reads all elements until one of the terminations included in kTerminations is encountered, or until the stream is exhausted. The terminating element itself is not read or returned. You can use readElement() or tryReadElement() to read the terminating element.

Requirements:: This function is not available for streams with characters as elements.

Template Parameters

kTerminations All of the elements that should terminate the read

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ readUntil() [2/7]

template<StreamElement Element>

template<Element... kTerminations>
requires tools::CharType<Element>

auto xentara::utils::io::InputStream< Element >::readUntil ( ) -> std::basic_string<Element>

Reads all characters until a termination is found.

This function reads all characters until one of the terminations included in kTerminations is encountered, or until the stream is exhausted. The terminating character itself is not read or returned. You can use readElement() or tryReadElement() to read the terminating character.

Requirements:: This function is only available for streams with characters as elements.

Template Parameters

kTerminations All of the characters that should terminate the read

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ readUntil() [3/7]

template<StreamElement Element>

template<typename CharTraits , Element... kTerminations>
requires tools::CharType<Element>

auto xentara::utils::io::InputStream< Element >::readUntil ( ) -> std::basic_string<Element, CharTraits>

Reads all characters until a termination is found.

This function reads all characters until one of the terminations included in kTerminations is encountered, or until the stream is exhausted. The terminating character itself is not read or returned. You can use readElement() or tryReadElement() to read the terminating character.

Requirements:: This function is only available for streams with characters as elements.

Template Parameters

CharTraits	The character traits to be used for the returned string
kTerminations	All of the characters that should terminate the read

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ readUntil() [4/7]

template<StreamElement Element>

template<tools::Allocator< Element > Allocator, Element... kTerminations>
requires (!tools::CharType<Element>)

auto xentara::utils::io::InputStream< Element >::readUntil ( const Allocator & allocator = Allocator() ) -> core::RawVector<Element, Allocator>

Reads all elements until a termination is found.

This function reads all elements until one of the terminations included in kTerminations is encountered, or until the stream is exhausted. The terminating element itself is not read or returned. You can use readElement() or tryReadElement() to read the terminating element.

Requirements:: This function is not available for streams with characters as elements.

Template Parameters

Allocator	The allocator type to be used for the returned vector
kTerminations	All of the elements that should terminate the read

Parameters

allocator The allocator to use for the returned vector

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ readUntil() [5/7]

template<StreamElement Element>

template<typename CharTraits , tools::Allocator< Element > Allocator, Element... kTerminations>
requires tools::CharType<Element>

auto xentara::utils::io::InputStream< Element >::readUntil ( const Allocator & allocator = Allocator() ) -> std::basic_string<Element, CharTraits, Allocator>

Reads all characters until a termination is found.

This function reads all characters until one of the terminations included in kTerminations is encountered, or until the stream is exhausted. The terminating character itself is not read or returned. You can use readElement() or tryReadElement() to read the terminating character.

Requirements:: This function is only available for streams with characters as elements.

Template Parameters

CharTraits	The character traits to be used for the returned string
Allocator	The allocator type to be used for the returned string
kTerminations	All of the characters that should terminate the read

Parameters

allocator The allocator to use for the returned vector

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ readUntil() [6/7]

template<StreamElement Element>

template<tools::Allocator< Element > Allocator = std::allocator<Element>, std::predicate< Element > Predicate>
requires (!tools::CharType<Element>)

auto xentara::utils::io::InputStream< Element >::readUntil	(	Predicate	predicate,
		const Allocator &	allocator = `Allocator()`
	)		-> core::RawVector<Element, Allocator>

Skips all elements until a termination element that fits a predicate.

This function reads all elements until a element is encountered for which predicate returns true, or until the stream is exhausted. The terminating element itself is not read or returned. You can use readElement() or tryReadElement() to read the terminating element.

Requirements:: This function is not available for streams with characters as elements.

Parameters

predicate	The predicate
allocator	The allocator to use for the returned vector

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ readUntil() [7/7]

template<StreamElement Element>

template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>, std::predicate< Element > Predicate>
requires tools::CharType<Element>

auto xentara::utils::io::InputStream< Element >::readUntil	(	Predicate	predicate,
		const Allocator &	allocator = `Allocator()`
	)		-> std::basic_string<Element, CharTraits, Allocator>

Skips all characters until a termination character that fits a predicate.

This function reads all characters until a character is encountered for which predicate returns true, or until the stream is exhausted. The terminating character itself is not read or returned. You can use readElement() or tryReadElement() to read the terminating character.

Requirements:: This function is only available for streams with characters as elements.

Parameters

predicate	The predicate
allocator	The allocator to use for the returned string

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ readWord()

template<StreamElement Element>

template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>>
requires tools::CharType<Element>

auto xentara::utils::io::InputStream< Element >::readWord ( const Allocator & allocator = Allocator() ) -> std::basic_string< Element, CharTraits, Allocator >

Reads a single whitespace-separated word.

This function reads all characters until one of the unicode characters SPACE, CHARACTER TABULATION, LINE FEED, or CARRIAGE RETURN is encountered, or until the stream is exhausted. The terminating character itself is not read or returned. You can use readChar() or tryReadChar() to read the terminating character.

Parameters

allocator The allocator to use for the returned string

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ rewind()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::rewind ( ) -> void

Sets the current read position to the beginning of the stream.

Exceptions

std::runtime_error An error occurred setting the read position, or the device does not support it

◆ setReadBuffer() [1/2]

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::setReadBuffer	(	Element *	bufferBegin,
		Element *	bufferEnd
	)		-> void

protectednoexcept

Sets a new empty buffer.

This function discards any data in the old buffer.

Note: The derived class is responsible for allocating the new buffer and deallocating the old buffer, if necessary. This class only tracks the location of the buffer, it does not take ownership or responsibility for it.

Parameters

bufferBegin	A pointer to the beginning of the read buffer
bufferEnd	A pointer past the end of the data already in the buffer

◆ setReadBuffer() [2/2]

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::setReadBuffer	(	Element *	bufferBegin,
		Element *	bufferEnd,
		Element *	dataBegin,
		Element *	dataEnd
	)		-> void

protectednoexcept

Sets the buffer.

This function discards any data in the old buffer.

Note: The derived class is responsible for allocating the new buffer and deallocating the old buffer, if necessary. This class only tracks the location of the buffer, it does not take ownership or responsibility for it.

Parameters

bufferBegin	A pointer to the beginning of the read buffer
bufferEnd	A pointer one past the end of the buffer
dataBegin	A pointer to the data already in the buffer
dataEnd	A pointer one past the end of the data already in the buffer

◆ setReadData()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::setReadData	(	Element *	dataBegin,
		Element *	dataEnd
	)		-> void

protectednoexcept

Sets the position of the data within the buffer.

This function discards the old data.

Parameters

dataBegin	A pointer to the data in the buffer
dataEnd	A pointer one past the end of the data in the buffer

◆ setReadPosition()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::setReadPosition ( ReadPosition position ) -> void

Sets the current read position within the device.

Parameters

position The desired position. This must be either ReadPosition(), or a value previously returned by readPosition()

Exceptions

std::runtime_error An error occurred setting the read position, or the device does not support it

◆ skip()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::skip ( std::size_t size ) -> void

Skips a block of data.

Parameters

size	The number of elements to skip

Exceptions

EndOfStreamError	This exception is thrown if the end of the data is reached before the correct amount of data was skipped. On communication streams, this exception is also derived from ConnectionClosed and denotes that the connection was gracefully closed.
ReadTimeoutError	This exception is thrown on communication streams if data takes too long to arrive. This can mean that there is a network congestion, that the sender is too slow, or that the sender did not send enough data.
StopRequested	This exception is thrown on communication streams that use a stop source if the stop source was triggered while waiting for data.
std::runtime_error	An error occurred accessing the underlying device
ConnectionClosed	On communication streams, any EndOfStreamError thrown is also derived from ConnectionClosed. This allows you to handle closed connections during read and write operations in the same catch block by catching exceptions of type ConnectionClosed.

◆ skipByte()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::skipByte ( ) -> void

Alternate name for skipElement()

Requirements:: This function is only available for streams element type std::byte.

◆ skipChar()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::skipChar ( ) -> void

Alternate name for skipElement()

Requirements:: This function is only available for streams with characters as elements.

◆ skipElement()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::skipElement ( ) -> void

Skips a single element from the stream.

Exceptions

EndOfStreamError	This exception is thrown if the end of the data is reached before the element was read. On communication streams, this exception is also derived from ConnectionClosed and denotes that the connection was gracefully closed.
ReadTimeoutError	This exception is thrown on communication streams if data takes too long to arrive. This can mean that there is a network congestion, that the sender is too slow, or that the sender did not send enough data.
StopRequested	This exception is thrown on communication streams that use a stop source if the stop source was triggered while waiting for data.
std::runtime_error	An error occurred accessing the underlying device
ConnectionClosed	On communication streams, any EndOfStreamError thrown is also derived from ConnectionClosed. This allows you to handle closed connections during read and write operations in the same catch block by catching exceptions of type ConnectionClosed.

◆ skipLine()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::skipLine ( ) -> std::size_t

Skips the rest of the line.

This function discards all characters until one of the unicode characters LINE FEED or CARRIAGE RETURN is encountered, or until the stream is exhausted. The terminating character itself is not discarded.

Returns: The number of characters skipped

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ skipLineEnding()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::skipLineEnding ( ) -> bool

Skips a single line termination.

This function skips the unicode character LINE FEED, or the unicode character pair CARRIAGE RETURN/LINE FEED. A single CARRIAGE RETURN without a LINE FEED is also skipped.

Requirements:: This function is only available for streams with characters as elements.

Returns: Return true if a line ending was found, or false if no line ending was present.

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ skipWhile() [1/2]

template<StreamElement Element>

template<Element... kSkippableElements>

auto xentara::utils::io::InputStream< Element >::skipWhile ( ) -> std::size_t

Skips all elements than appear in a list of skippable elements.

Template Parameters

kSkippableElements The elements to skip

Returns: The number of elements skipped

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ skipWhile() [2/2]

template<StreamElement Element>

template<std::predicate< Element > Predicate>

auto xentara::utils::io::InputStream< Element >::skipWhile ( Predicate predicate ) -> std::size_t

Skips all elements that fit a predicate.

Parameters

predicate The predicate

Returns: The number of elements skipped

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ skipWhitespace()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::skipWhitespace ( ) -> bool

Skips all ASCII whitespace elements.

This funktion skips the unicode elements SPACE, CHARACTER TABULATION, LINE FEED, and CARRIAGE RETURN. Other unicode elements from the categories “Separator, Space[Zs]”, are not skipped.

Requirements:: This function is only available for streams with characters as elements.

Returns: Return true if any whitespace was present, or false if no characters where skipped.

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ skipWord()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::skipWord ( ) -> std::size_t

Skips the rest of a whitespace-separated word.

This function discards all characters until one of the unicode characters SPACE, CHARACTER TABULATION, LINE FEED, or CARRIAGE RETURN is encountered, or until the stream is exhausted. . The terminating character itself is not discarded.

Returns: The number of characters skipped

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ tryPeek()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::tryPeek ( ) -> std::optional< Element >

Look at the next element in the stream without actually reading it.

Returns: The element that will be read next, or std::nullopt if we are at the end of the data

Exceptions

std::runtime_error An error occurred reading data from the underlying device

◆ tryReadByte()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::tryReadByte ( ) -> std::optional<Element>

Alternate name for tryReadElement()

Requirements:: This function is only available for streams element type std::byte.

◆ tryReadChar()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::tryReadChar ( ) -> std::optional<Element>

Alternate name for tryReadElement()

Requirements:: This function is only available for streams with characters as elements.

◆ tryReadElement()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::tryReadElement ( ) -> std::optional< Element >

Tries to read a single element from a stream.

Returns: The element that was read, or std::nullopt if the end of the data was reached before the element was read

Exceptions

std::runtime_error An error occurred reading data from the underlying device

◆ trySkipByte()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::trySkipByte ( ) -> bool

Alternate name for trySkipElement() for character streams.

Requirements:: This function is only available for streams element type std::byte.

◆ trySkipChar()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::trySkipChar ( ) -> bool

Alternate name for trySkipElement() for character streams.

Requirements:: This function is only available for streams with characters as elements.

◆ trySkipElement()

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::trySkipElement ( ) -> bool

Tries to skip a single element from a stream.

Returns: The element that was read, or std::nullopt if none was available.

Exceptions

std::runtime_error An error occurred accessing the underlying device

◆ waitForData() [1/2]

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::waitForData ( ) -> void

Waits for more read data to become available.

On communication streams, this function waits until the stream is in a state where the next read operation will not block.

On non-communication streams, this function always returns immediately.

Exceptions

EndOfStreamError	This exception is thrown if the end of the stream has been reached. On communication streams, this exception is also derived from ConnectionClosed and denotes that the connection was gracefully closed.
StopRequested	This exception is thrown on communication streams that use a stop source if the stop source was triggered during the wait.
ConnectionClosed	On communication streams, any EndOfStreamError thrown is also derived from ConnectionClosed. This allows you to handle closed connections during read and write operations in the same catch block by catching exceptions of type ConnectionClosed.
std::runtime_error	An error occurred accessing the underlying device

◆ waitForData() [2/2]

template<StreamElement Element>

auto xentara::utils::io::InputStream< Element >::waitForData ( std::optional< std::chrono::nanoseconds > timeout ) -> bool

Waits for more read data to become available within a certain time.

On communication streams, this function waits until the stream is in a state where the next read operation will not block, and return true if that state was reached before an optional timeout elapsed.

On non-communication streams, this function always returns true immediately.

Parameters

timeout The number of nanoseconds to wait, or std::nullopt to wait indefinitely. If you pass 0 or a negative value to this function, it will not wait, but simply return whether the stream can be read without blocking or not.

Returns: Returns true if the stream can be read without blocking, or false on timeout. If you do not specify a timeout, the function will never return false.

Exceptions

EndOfStreamError	This exception is thrown if the end of the stream has been reached. On communication streams, this exception is also derived from ConnectionClosed and denotes that the connection was gracefully closed.
StopRequested	This exception is thrown on communication streams that use a stop source if the stop source was triggered during the wait.
ConnectionClosed	On communication streams, any EndOfStreamError thrown is also derived from ConnectionClosed. This allows you to handle closed connections during read and write operations in the same catch block by catching exceptions of type ConnectionClosed.
std::runtime_error	An error occurred accessing the underlying device

Classes

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ element_type

Constructor & Destructor Documentation

◆ ~InputStream()

◆ InputStream() [1/4]

◆ InputStream() [2/4]

◆ InputStream() [3/4]

◆ InputStream() [4/4]

Member Function Documentation

◆ doAdvanceReadPosition()

◆ doGetReadPosition()

◆ doRead()

◆ doReplenishReadBuffer()

◆ doSetReadPosition()

◆ doThrowEndOfStreamError()

◆ doWaitForData()

◆ eof()

◆ operator=()

◆ peek()

◆ peekOr()

◆ read() [1/6]

◆ read() [2/6]

◆ read() [3/6]

◆ read() [4/6]

◆ read() [5/6]

◆ read() [6/6]

◆ readBufferBegin()

◆ readBufferEnd()

◆ readBufferSize()

◆ readByte()

◆ readByteIf() [1/2]

◆ readByteIf() [2/2]

◆ readByteIfOr() [1/2]

◆ readByteIfOr() [2/2]

◆ readByteOr()

◆ readChar()

◆ readCharIf() [1/2]

◆ readCharIf() [2/2]

◆ readCharIfOr() [1/2]

◆ readCharIfOr() [2/2]

◆ readCharOr()

◆ readDataBegin()

◆ readDataEnd()

◆ readDataSize()

◆ readElement()

◆ readElementIf() [1/2]

◆ readElementIf() [2/2]

◆ readElementIfOr() [1/2]

◆ readElementIfOr() [2/2]

◆ readElementOr()

◆ readFromBuffer()

◆ readLine()

◆ readPosition()

◆ readUntil() [1/7]

◆ readUntil() [2/7]

◆ readUntil() [3/7]

◆ readUntil() [4/7]

◆ readUntil() [5/7]

◆ readUntil() [6/7]

◆ readUntil() [7/7]

◆ readWord()

◆ rewind()

◆ setReadBuffer() [1/2]

◆ setReadBuffer() [2/2]

◆ setReadData()

◆ setReadPosition()

◆ skip()

◆ skipByte()

◆ skipChar()

◆ skipElement()

◆ skipLine()

◆ skipLineEnding()

◆ skipWhile() [1/2]

◆ skipWhile() [2/2]

◆ skipWhitespace()