StreamReader is an non-essential Stream utility, adding simplicity of use for a common use case, and a significant performance boost. More...

#include <StreamReader.h>

Public Member Functions
	StreamReader (const typename InputStream::Ptr< ElementType > &underlyingReadFromStreamAdopted)

nonvirtual optional< span< ElementType > >	Read (span< ElementType > intoBuffer, NoDataAvailableHandling blockFlag)
	Read into data referenced by span argument - and using argument blocking strategy (default blocking)

nonvirtual optional< ElementType >	ReadBlocking ()
	ReadBlocking () reads either a single element, or fills in argument intoBuffer - but never blocks (nor throws EWouldBlock)

nonvirtual optional< span< ElementType > >	ReadNonBlocking (span< ElementType > intoBuffer)
	read into intoBuffer - returning nullopt if would block, and else returning subspan of input with read data present

nonvirtual span< ElementType >	ReadOrThrow (span< ElementType > intoBuffer, NoDataAvailableHandling blockFlag)
	Read (either one or into argument span) and taking NoDataAvailableHandling blockFlag), and throw if would block.

nonvirtual optional< ElementType >	Peek ()
	Logically the same as InputStream::Ptr<ELEMENT_TYPE>::Peek () but reading cached data.

nonvirtual SeekOffsetType	GetOffset () const
	Logically the same as InputStream::Ptr<ELEMENT_TYPE>::GetOffset () - but without being 'synchronized' it maybe a different value than the underlying stream.

nonvirtual SeekOffsetType	Seek (SeekOffsetType offset)
	Logically the same as InputStream::Ptr<ELEMENT_TYPE>::Seek () - but without being 'synchronized' it maybe a different value than the underlying stream.

nonvirtual size_t	ReadAll (ElementType intoStart, ElementType intoEnd)
	Logically the same as InputStream::Ptr<ELEMENT_TYPE>::ReadAll ()

nonvirtual optional< size_t >	AvailableToRead () const
	returns nullopt if nothing known available, zero if known EOF, and any other number of elements (typically 1) if that number know to be available to read

nonvirtual optional< SeekOffsetType >	RemainingLength () const
	returns nullopt if not known (typical, and the default) - but sometimes it is known, and quite helpful)

nonvirtual void	SynchronizeToUnderlyingStream ()

nonvirtual void	SynchronizeFromUnderlyingStream ()

Detailed Description

template<typename ELEMENT_TYPE>
struct Stroika::Foundation::Streams::StreamReader< ELEMENT_TYPE >

StreamReader is an non-essential Stream utility, adding simplicity of use for a common use case, and a significant performance boost.

See also: also https://learn.microsoft.com/en-us/dotnet/api/system.io.streamreader?view=net-8.0 - similar idea, except there you specify conversion from binary stream.

StreamReader is an unnecessary class for using the Streams library, but it is easy to use, similar to InputStream<T>::Ptr, and significantly more performant

Note: Similar to BufferedInputStream - but that provides an actual Stream object, and is slightly less performant for direct use.

TODO:

Definition at line 36 of file StreamReader.h.

Constructor & Destructor Documentation

◆ StreamReader()

template<typename ELEMENT_TYPE >

Stroika::Foundation::Streams::StreamReader< ELEMENT_TYPE >::StreamReader ( const typename InputStream::Ptr< ElementType > & underlyingReadFromStreamAdopted )

Note: Do NOT use the InputStream::Ptr<ElementType> passed in at the same time as its being used by the StreamReader, or grave disorder may result. StreamReader assumes its the only one seeking and reading through the input stream. See SynchronizeToUnderlyingStream ().; At destruction, StreamReader automatically calls SynchronizeToUnderlyingStream

Precondition: underlyingReadFromStreamAdopted.Seekable ();

Definition at line 110 of file StreamReader.inl.

Member Function Documentation

◆ Read()

template<typename ELEMENT_TYPE >

optional< span< ELEMENT_TYPE > > Stroika::Foundation::Streams::StreamReader< ELEMENT_TYPE >::Read	(	span< ElementType >	intoBuffer,
		NoDataAvailableHandling	blockFlag
	)

Read into data referenced by span argument - and using argument blocking strategy (default blocking)

returns nullopt ONLY if blockFlag = eNonBlocking AND there is NO data available without blocking.

a return of NOT missing, but an empty span implies EOF.

BLOCKING until data is available, but can return with fewer elements than argument span-size without prejudice about how much more is available.

Note: It is legal to call Read () if its already returned EOF, but then it MUST return EOF again.

Precondition: not intoBuffer.empty ()

See also: ReadAll () to read all the data from the stream at once.; ReadBlocking () - often simplest to use API; ReadOrThrow (); ReadNonBlocking (); also InputStream::Ptr::Read () - identical API (except non-const)

Definition at line 123 of file StreamReader.inl.

◆ ReadBlocking()

template<typename ELEMENT_TYPE >

auto Stroika::Foundation::Streams::StreamReader< ELEMENT_TYPE >::ReadBlocking ( )

ReadBlocking () reads either a single element, or fills in argument intoBuffer - but never blocks (nor throws EWouldBlock)

ReadBlocking (): Reads a single element (blocking as long as needed) - or nullopt when at EOF.

ReadBlocking(span<ElementType> intoBuffer) fills in subspan with at least one element (or zero if at EOF)

See also: also InputStream::Ptr::ReadBlocking () - identical API (except non-const)

Definition at line 138 of file StreamReader.inl.

◆ ReadNonBlocking()

template<typename ELEMENT_TYPE >

auto Stroika::Foundation::Streams::StreamReader< ELEMENT_TYPE >::ReadNonBlocking ( span< ElementType > intoBuffer )

read into intoBuffer - returning nullopt if would block, and else returning subspan of input with read data present

same as Read (intoBuffer, NoDataAvailableHandling::eDontBlock)

See also: also InputStream::Ptr::ReadBlocking () - identical API(except non-const)

Definition at line 162 of file StreamReader.inl.

◆ ReadOrThrow()

template<typename ELEMENT_TYPE >

auto Stroika::Foundation::Streams::StreamReader< ELEMENT_TYPE >::ReadOrThrow	(	span< ElementType >	intoBuffer,
		NoDataAvailableHandling	blockFlag
	)

Read (either one or into argument span) and taking NoDataAvailableHandling blockFlag), and throw if would block.

same as Read() APIs, but instead of returning optional, for cases where nullopt would be returned, throw EWouldBlock

Note: if blockFlag == eBlockIfNoDataAvailable, this amounts to *Read(...args), since it will never generate an eWouldBlock exception;

when to use this variant? If implementing API where you are handed a blockFlag, but want to KISS, and just throw if EWouldBlock ..

See also: also InputStream::Ptr::ReadOrThrow () - identical API(except non-const)

Definition at line 170 of file StreamReader.inl.

◆ ReadAll()

template<typename ELEMENT_TYPE >

size_t Stroika::Foundation::Streams::StreamReader< ELEMENT_TYPE >::ReadAll	(	ElementType *	intoStart,
		ElementType *	intoEnd
	)

Logically the same as InputStream::Ptr<ELEMENT_TYPE>::ReadAll ()

@todo add other overloads from InputStream::Ptr::ReadAll() - ...

Definition at line 226 of file StreamReader.inl.

◆ AvailableToRead()

template<typename ELEMENT_TYPE >

optional< size_t > Stroika::Foundation::Streams::StreamReader< ELEMENT_TYPE >::AvailableToRead ( ) const

returns nullopt if nothing known available, zero if known EOF, and any other number of elements (typically 1) if that number know to be available to read

See also: also (different) RemainingLength ()

Definition at line 242 of file StreamReader.inl.

◆ RemainingLength()

template<typename ELEMENT_TYPE >

optional< SeekOffsetType > Stroika::Foundation::Streams::StreamReader< ELEMENT_TYPE >::RemainingLength ( ) const

returns nullopt if not known (typical, and the default) - but sometimes it is known, and quite helpful)

Note: - Similar to AvailableToRead, but different. For example, on a socket-stream, you can tell how many bytes are available to read (buffered by kernel). But no guess about the remaining length of the stream (how many bytes will appear before end).

But for a disk file, you MIGHT (not always - like unix special files) know the length of the file. This is for that case.

Definition at line 250 of file StreamReader.inl.

◆ SynchronizeToUnderlyingStream()

template<typename ELEMENT_TYPE >

void Stroika::Foundation::Streams::StreamReader< ELEMENT_TYPE >::SynchronizeToUnderlyingStream ( )

If you must use the underlying stream along-side StreamReader, you can use SynchronizeToUnderlyingStream and SynchronizeFromUnderlyingStream to allow each class to update each other.

Definition at line 259 of file StreamReader.inl.

◆ SynchronizeFromUnderlyingStream()

template<typename ELEMENT_TYPE >

void Stroika::Foundation::Streams::StreamReader< ELEMENT_TYPE >::SynchronizeFromUnderlyingStream ( )

If you must use the underlying stream along-side StreamReader, you can use SynchronizeToUnderlyingStream and SynchronizeFromUnderlyingStream to allow each class to update each other.

Definition at line 264 of file StreamReader.inl.

The documentation for this struct was generated from the following files:

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ StreamReader()

Member Function Documentation

◆ Read()

◆ ReadBlocking()

◆ ReadNonBlocking()

◆ ReadOrThrow()

◆ ReadAll()

◆ AvailableToRead()

◆ RemainingLength()

◆ SynchronizeToUnderlyingStream()

◆ SynchronizeFromUnderlyingStream()