A Streams::Ptr<ELEMENT_TYPE> is a smart-pointer to a stream of elements of type T. More...

#include <Stream.h>

Inheritance diagram for Stroika::Foundation::Streams::Ptr< ELEMENT_TYPE >:

Public Member Functions
	Ptr () noexcept=default

nonvirtual void	reset () noexcept

nonvirtual bool	operator== (nullptr_t) const
	return true iff stream ptr is nullptr

nonvirtual	operator bool () const
	return true iff *this != nullptr

nonvirtual shared_ptr< IRep< ELEMENT_TYPE > >	GetSharedRep () const
	access to underlying stream smart pointer

nonvirtual const IRep< ELEMENT_TYPE > &	GetRepConstRef () const

nonvirtual IRep< ELEMENT_TYPE > &	GetRepRWRef () const

nonvirtual bool	IsSeekable () const
	Returns true iff this object was constructed with a seekable input stream rep.

Detailed Description

template<typename ELEMENT_TYPE>
class Stroika::Foundation::Streams::Ptr< ELEMENT_TYPE >

A Streams::Ptr<ELEMENT_TYPE> is a smart-pointer to a stream of elements of type T.

Design Overview o A Streams is a sequence of data elements made available over time. These elements are typically 'Bytes' - or 'Characters' - but can be any copyable type.

o Streams are created, and then handled ONLY through smart pointers (Ptr). Assigning Streams merely copies the 'smart pointer' to that same underlying stream. This means that offsets and underlying data, are all shared.

o Streams have two parallel hierarchies, which mirror one another, of smart pointers and related 'virtual rep' objects which provide the API which implementers override.

o Seek Offsets are in elements of the kind of stream (e.g in Bytes for a Stream<byte>, and in Characters for a Stream<Character>).

o Two important subclasses of Stream<> are InputStream::Ptr<> (for reading) and OutputStream::Ptr<> for writing. So that each can maintain its own intrinsic current offset (separate seek offset for reading and writing) in mixed (input/output) streams, the actual offset APIs and logic are in those subclasses.

o Stream APIs are intrinsically blocking (except see InputStream::Ptr<>::ReadNonBlocking() and APIs that take optional non-blocking parameter). This makes working with them much simpler, since code using Streams doesn't need to be written to handle both blocking and non-blocking behavior, and be surprised when a 'mode' is set on a stream making it non-blocking.

o Relationship with std iostream: Stroika streams are in some ways similar to iostreams. They are interoperable with iostreams through the Streams::iostream::(InputStreamFromStdIStream, InputStreamToStdIStream, OutputStreamFromStdIStream, OutputStreamToStdIStream) classes.

o Stroika Streams are much easier to create (just a few intuitive virtual methods to override in the rep, whereas creating your own kind of basic_istream/ostream is much harder).

o Stroika streams are unrelated to formatting of text.

o Stroika Streams are much easier to use and understand, with better internal error checking, and simpler, more consistent naming for offsets/seeking, and seekability.

o Stroika supports non-seekable streams (needed for things like sockets, and certain special files, like Linux procfs files).

o Due to more orthogonal API, easier to provide intuitive simple adapters mapping one kind of stream to another (such as binary streams to streams of text, like the .net TextReader).

o Stroika Streams are divided into 'Smart Pointer' objects (all you interact with) and the underlying Stream data (Rep). Copying an iostream is generally not possible with STL, but with Stroika, it copies a reference (smart pointer) to the underlying stream.

Stream<T>::Ptr is seldom used directly. Much more commonly, you will want InputStream::Ptr<T>, or OutputStream::Ptr<T>.

Note: Since Streams::Ptr<ELEMENT_TYPE> is a smart pointer, the constness of the methods depends on whether they modify the smart pointer itself, not the underlying thread object.; Thread-Safety C++-Standard-Thread-Safety-For-Envelope-But-Ambiguous-Thread-Safety-For-Letter/a> \note Comparisons: o Support operator==(nullptr_t) only

Definition at line 170 of file Stream.h.