Description

A number of serial channels ready to use.

Constrained by the architecture of STL streams, Elementa serial channels have the following characteristics (there is no both sensible and efficient way of forcing the user to provide all these characteristics in a compiler-controlled fashion, thus it is the responsibility of the programmer to comply with them):

New channels (some of them defined in this module) will inherit publicly from those "base classes", but the STL public functionality cannot be overriden, since the base class methods are declared non-virtual, and thus in polymorphic scenarios the base methods will be always called instead of the derived ones.
New channels can (and must) override the virtual functionality of std::streambuf inside their classes (privately) in order to provide the actual functionality of the derived channel.

Note: - It is convenient that any serial channel class derived from the "base classes" is named as "SerChI_<yourname>", "SerChO_<yourname>" or "SerChIO_<yourname>" for easy identification as serial channel with a given (input, output, in/out) flow of information.

Author: Juan-Antonio Fernandez-Madrigal. http://jafma.net

Date: 2018-2020

Copyright: Copyright (c), Individual contributors, see AUTHORS file. This program is free for non-commercial uses. For the rest, contact the AUTHORS. Please include a mention in your programs to the main developer and the web page of the library.

Collaboration diagram for Common serial channels:

Classes
class	elementa::base::SerChO_Null
	Null output serial channel to discard anything written to it. More...

class	elementa::base::SerChO_NullCoBuf
	Null output serial channel that can count what is written and also buffer it. More...

class	elementa::base::SerChO_AppCont< Cont >
	Output ser. chan. that appends to a container without pre-allocated storage. More...

class	elementa::base::SerChI_Constant
	Input serial channel that provides a pre-defined char value endlessly. More...

class	elementa::base::SerChI_Procedural
	Input serial channel that provides values based on some procedure. More...

class	elementa::base::InStreamBuf_MemoryPriv
	Private class that needs to be here for the following channels to work. More...

class	elementa::base::InOutStreamBuf_MemoryPriv
	Private class that needs to be here for the following channels to work. More...

class	elementa::base::SerChIO_Memory
	Input + output ser. chan. associated to a pre-allocated region of memory. More...

class	elementa::base::SerChI_Memory
	Input + output ser. chan. associated to a pre-allocated region of memory. More...

Functions
template<>
SerChSize	elementa::base::serch_transfer< SerChIO_Memory, SerChIO_Memory > (SerChIO_Memory &chin, SerChIO_Memory &chout, SerChSize count)
	Full specialization of serch_transfer for both channels being Memory. More...

template<>
SerChSize	elementa::base::serch_transfer< SerChI_Memory, SerChIO_Memory > (SerChI_Memory &chin, SerChIO_Memory &chout, SerChSize count)
	Full specialization of serch_transfer for both channels being Memory. More...

template<typename T >
	elementa::base::SerChIO_Memory::SerChIO_Memory (void *begin, T n) noexcept
	Template constructor. More...

template<typename T >
	elementa::base::SerChIO_Memory::SerChIO_Memory (std::vector< T > &v, typename std::vector< T >::size_type offbegin=0, typename std::vector< T >::size_type offend=0)
	Template constructor for a region within a std::vector. More...

template<typename T , std::size_t N>
	elementa::base::SerChIO_Memory::SerChIO_Memory (std::array< T, N > &a, typename std::array< T, N >::size_type offbegin=0, typename std::array< T, N >::size_type offend=0)
	Template constructor for a region within a std::array. More...

template<typename T >
	elementa::base::SerChI_Memory::SerChI_Memory (const void *begin, T n) noexcept
	Template constructor. More...

template<typename T >
	elementa::base::SerChI_Memory::SerChI_Memory (const std::vector< T > &v, typename std::vector< T >::size_type offbegin=0, typename std::vector< T >::size_type offend=0)
	Template constructor for a region within a std::vector. More...

template<typename T , std::size_t N>
	elementa::base::SerChI_Memory::SerChI_Memory (const std::array< T, N > &a, typename std::array< T, N >::size_type offbegin=0, typename std::array< T, N >::size_type offend=0)
	Template constructor for a region within a std::array. More...

Variables
SerChI_Constant	elementa::base::serchI_dummy
	A singleton, dummy input channel that always produces space characters.

Class Documentation

◆ elementa::base::SerChO_Null

class elementa::base::SerChO_Null

Null output serial channel to discard anything written to it.

This class may serve to discard a sequence of data. If you need to count how many, or to buffer them, use SerChO_NullCoBuf instead.

Note: - This channel is thread-safe.; - If you need to trace things sent to this channel, use SerChORedir.

See also: SerChO_NullCoBuf.

Definition at line 80 of file channels.h.

Inheritance diagram for elementa::base::SerChO_Null:

[legend]

Collaboration diagram for elementa::base::SerChO_Null:

[legend]

Constructor & Destructor Documentation

◆ SerChO_Null()

elementa::base::SerChO_Null::SerChO_Null ( void )

inline

Definition at line 84 of file channels.h.

◆ elementa::base::SerChO_NullCoBuf

class elementa::base::SerChO_NullCoBuf

Null output serial channel that can count what is written and also buffer it.

This class may serve to count the serialized data and also to buffer it for using it afterwards. If you need a buffer with unlimited storage, see SerChO_AppCont.

Note: - If more chars than BUFFER are serialized, the excess are silently discarded (the count is still correctly updated).; - This channel is not thread-safe.

See also: SerChO_AppCont, SerChO_Null.

Definition at line 126 of file channels.h.

Inheritance diagram for elementa::base::SerChO_NullCoBuf:

[legend]

Collaboration diagram for elementa::base::SerChO_NullCoBuf:

[legend]

Public Member Functions
	SerChO_NullCoBuf (SerChSize buffer=0)
	Create a serial channel able to count and with a buffer of BUFFER chars. More...

SerChSize	size (void) const
	Return the buffer size defined in the constructor. More...

void	reset (void)
	Reset the count of the channel and, if any, clear the buffer. More...

SerChSize	count (void) const
	Return the current number of chars already serialized. More...

const char *	buffer (void) const
	Return nullptr if the buffer has size 0, or the buffer otherwise. More...

Constructor & Destructor Documentation

◆ SerChO_NullCoBuf()

elementa::base::SerChO_NullCoBuf::SerChO_NullCoBuf ( SerChSize buffer = 0 )

inline

Create a serial channel able to count and with a buffer of BUFFER chars.

Definition at line 131 of file channels.h.

Member Function Documentation

◆ size()

SerChSize elementa::base::SerChO_NullCoBuf::size ( void ) const

inline

Return the buffer size defined in the constructor.

Definition at line 136 of file channels.h.

◆ reset()

void elementa::base::SerChO_NullCoBuf::reset ( void )

inline

Reset the count of the channel and, if any, clear the buffer.

Definition at line 139 of file channels.h.

◆ count()

SerChSize elementa::base::SerChO_NullCoBuf::count ( void ) const

inline

Return the current number of chars already serialized.

Definition at line 142 of file channels.h.

◆ buffer()

const char * elementa::base::SerChO_NullCoBuf::buffer ( void ) const

inline

Return nullptr if the buffer has size 0, or the buffer otherwise.

Definition at line 145 of file channels.h.

◆ elementa::base::SerChO_AppCont

class elementa::base::SerChO_AppCont

template<class Cont>
class elementa::base::SerChO_AppCont< Cont >

Output ser. chan. that appends to a container without pre-allocated storage.

If you need to output data to a container with pre-allocated storage, see SerChIO_Memory.

Note: - The amount of data appended is not limited except by available memory.; - The container must admit the "push_back" method. As for C++11, containers that have such methods are std::vector, std::list, std::dequeue, and std::string.; - This channel is not thread-safe.

See also: SerChIO_Memory.

Definition at line 196 of file channels.h.

Inheritance diagram for elementa::base::SerChO_AppCont< Cont >:

[legend]

Collaboration diagram for elementa::base::SerChO_AppCont< Cont >:

[legend]

Public Member Functions
	SerChO_AppCont (Cont &cont)
	Create a serial channel to append chars at the end of CONT. More...

Cont &	container (void) noexcept
	Return a reference to the container. More...

Constructor & Destructor Documentation

◆ SerChO_AppCont()

template<class Cont >

elementa::base::SerChO_AppCont< Cont >::SerChO_AppCont ( Cont & cont )

inline

Create a serial channel to append chars at the end of CONT.

CONT must outlive the channel, since the channel does not take ownership of it.

Definition at line 203 of file channels.h.

Member Function Documentation

◆ container()

template<class Cont >

Cont & elementa::base::SerChO_AppCont< Cont >::container ( void )

inlinenoexcept

Return a reference to the container.

Definition at line 207 of file channels.h.

◆ elementa::base::SerChI_Constant

class elementa::base::SerChI_Constant

Input serial channel that provides a pre-defined char value endlessly.

Note: - Putback is not possible unless the same char already read is put back.; - This channel is thread-safe.

Definition at line 251 of file channels.h.

Inheritance diagram for elementa::base::SerChI_Constant:

[legend]

Collaboration diagram for elementa::base::SerChI_Constant:

[legend]

Public Member Functions
	SerChI_Constant (char c)

Constructor & Destructor Documentation

◆ SerChI_Constant()

elementa::base::SerChI_Constant::SerChI_Constant ( char c )

inline

Definition at line 255 of file channels.h.

◆ elementa::base::SerChI_Procedural

class elementa::base::SerChI_Procedural

Input serial channel that provides values based on some procedure.

Note: - Putback is not possible unless the same char already read is put back, and only works once.; - This channel is thread-safe.

Definition at line 299 of file channels.h.

Inheritance diagram for elementa::base::SerChI_Procedural:

[legend]

Collaboration diagram for elementa::base::SerChI_Procedural:

[legend]

Public Types
using	Procedure = std::function< SerChDatum(void) >
	A procedure that generates the characters. More...

Public Member Functions
	SerChI_Procedural (Procedure &p)
	Constructor. P must outlive this channel: only a reference is taken. More...

Member Typedef Documentation

◆ Procedure

using elementa::base::SerChI_Procedural::Procedure = std::function< SerChDatum(void) >

A procedure that generates the characters.

If there is a character available, SerChCharTraits::to_int_type(c) must be returned; otherwise, kSerChEOF must be returned.

Definition at line 306 of file channels.h.

Constructor & Destructor Documentation

◆ SerChI_Procedural()

elementa::base::SerChI_Procedural::SerChI_Procedural ( Procedure & p )

inline

Constructor. P must outlive this channel: only a reference is taken.

Definition at line 309 of file channels.h.

◆ elementa::base::InStreamBuf_MemoryPriv

class elementa::base::InStreamBuf_MemoryPriv

Private class that needs to be here for the following channels to work.

Definition at line 363 of file channels.h.

Inheritance diagram for elementa::base::InStreamBuf_MemoryPriv:

[legend]

Collaboration diagram for elementa::base::InStreamBuf_MemoryPriv:

[legend]

Public Member Functions
void	reset (const char begin, const char end)

SerChSize	transfer (InOutStreamBuf_MemoryPriv &other, SerChSize count)

◆ elementa::base::InOutStreamBuf_MemoryPriv

class elementa::base::InOutStreamBuf_MemoryPriv

Private class that needs to be here for the following channels to work.

Definition at line 382 of file channels.h.

Inheritance diagram for elementa::base::InOutStreamBuf_MemoryPriv:

[legend]

Collaboration diagram for elementa::base::InOutStreamBuf_MemoryPriv:

[legend]

Public Member Functions
void	reset (char begin, char end)

SerChSize	transfer (InOutStreamBuf_MemoryPriv &other, SerChSize count)

◆ elementa::base::SerChIO_Memory

class elementa::base::SerChIO_Memory

Input + output ser. chan. associated to a pre-allocated region of memory.

Allow to access a memory region through the serial channel paradigm. That memory can be provided by containers such as std::vector, std::array or std::string.

This class is not thread-safe.

See also: SerChI_Memory

Definition at line 420 of file channels.h.

Inheritance diagram for elementa::base::SerChIO_Memory:

[legend]

Collaboration diagram for elementa::base::SerChIO_Memory:

[legend]

Public Member Functions
template<typename T >
	SerChIO_Memory (void *begin, T n) noexcept
	Template constructor. More...

	SerChIO_Memory (std::string &str, std::string::size_type offbegin=0, std::string::size_type offend=0)
	Constructor for a region within a string. More...

template<typename T >
	SerChIO_Memory (std::vector< T > &v, typename std::vector< T >::size_type offbegin=0, typename std::vector< T >::size_type offend=0)
	Template constructor for a region within a std::vector. More...

template<typename T , std::size_t N>
	SerChIO_Memory (std::array< T, N > &a, typename std::array< T, N >::size_type offbegin=0, typename std::array< T, N >::size_type offend=0)
	Template constructor for a region within a std::array. More...

	SerChIO_Memory (const SerChIO_Memory &)=delete

	SerChIO_Memory (SerChIO_Memory &&)=delete

SerChIO_Memory &	operator= (SerChIO_Memory &)=delete

SerChIO_Memory &	operator= (SerChIO_Memory &&)=delete

void	reset (void)
	Reset the channel to its initial position and state.

SerChSize	transfer (SerChIO_Memory &chout, SerChSize count=0)
	Specialized version of serch_transfer when both channels are of memory. More...

Constructor & Destructor Documentation

◆ SerChIO_Memory()

elementa::base::SerChIO_Memory::SerChIO_Memory	(	std::string &	str,
		std::string::size_type	offbegin = `0`,
		std::string::size_type	offend = `0`
	)

Constructor for a region within a string.

Parameters

offbegin	is the offset from the beginning of the region used by the channel.
offend	is the offset from the ending, backwards, of the region used by the channel.

Member Function Documentation

◆ transfer()

SerChSize elementa::base::SerChIO_Memory::transfer	(	SerChIO_Memory &	chout,
		SerChSize	count = `0`
	)

inline

Specialized version of serch_transfer when both channels are of memory.

This object becomes the input channel.

See also: serch_transfer

Definition at line 478 of file channels.h.

Referenced by elementa::base::serch_transfer< SerChIO_Memory, SerChIO_Memory >().

◆ elementa::base::SerChI_Memory

class elementa::base::SerChI_Memory

Input + output ser. chan. associated to a pre-allocated region of memory.

Allow to access a memory region through the serial channel paradigm. That memory can be provided by containers such as std::vector, std::array or std::string.

This class is not thread-safe.

See also: SerChIO_Memory

Definition at line 525 of file channels.h.

Inheritance diagram for elementa::base::SerChI_Memory:

[legend]

Collaboration diagram for elementa::base::SerChI_Memory:

[legend]

Public Member Functions
template<typename T >
	SerChI_Memory (const void *begin, T n) noexcept
	Template constructor. More...

	SerChI_Memory (const std::string &str, std::string::size_type offbegin=0, std::string::size_type offend=0)
	Constructor for a region within a string. More...

template<typename T >
	SerChI_Memory (const std::vector< T > &v, typename std::vector< T >::size_type offbegin=0, typename std::vector< T >::size_type offend=0)
	Template constructor for a region within a std::vector. More...

template<typename T , std::size_t N>
	SerChI_Memory (const std::array< T, N > &a, typename std::array< T, N >::size_type offbegin=0, typename std::array< T, N >::size_type offend=0)
	Template constructor for a region within a std::array. More...

	SerChI_Memory (const SerChI_Memory &)=delete

	SerChI_Memory (SerChI_Memory &&)=delete

SerChI_Memory &	operator= (SerChI_Memory &)=delete

SerChI_Memory &	operator= (SerChI_Memory &&)=delete

void	reset (void)
	Reset the channel to its initial position and state.

SerChSize	transfer (SerChIO_Memory &chout, SerChSize count=0)
	Specialized version of serch_transfer when both channels are of memory. More...

Constructor & Destructor Documentation

◆ SerChI_Memory()

elementa::base::SerChI_Memory::SerChI_Memory	(	const std::string &	str,
		std::string::size_type	offbegin = `0`,
		std::string::size_type	offend = `0`
	)

Constructor for a region within a string.

Parameters

offbegin	is the offset from the beginning.
offend	is the offset from the ending backwards.

Member Function Documentation

◆ transfer()

SerChSize elementa::base::SerChI_Memory::transfer	(	SerChIO_Memory &	chout,
		SerChSize	count = `0`
	)

inline

Specialized version of serch_transfer when both channels are of memory.

This object becomes the input channel.

See also: serch_transfer

Definition at line 576 of file channels.h.

Referenced by elementa::base::serch_transfer< SerChI_Memory, SerChIO_Memory >().

Function Documentation

◆ serch_transfer< SerChIO_Memory, SerChIO_Memory >()

template<>

SerChSize elementa::base::serch_transfer< SerChIO_Memory, SerChIO_Memory >	(	SerChIO_Memory &	chin,
		SerChIO_Memory &	chout,
		SerChSize	count
	)

inline

#include <elementa/base/serial_channels/channels.h>

Full specialization of serch_transfer for both channels being Memory.

Note: - Need to be inline since a full specialization becomes a non-template function and therefore cannot be included more than once.

Definition at line 495 of file channels.h.

References ELE_CODE_TRACE_OFF, elementa::base::serch_st_to_string(), and elementa::base::SerChIO_Memory::transfer().

◆ serch_transfer< SerChI_Memory, SerChIO_Memory >()

template<>

SerChSize elementa::base::serch_transfer< SerChI_Memory, SerChIO_Memory >	(	SerChI_Memory &	chin,
		SerChIO_Memory &	chout,
		SerChSize	count
	)

inline

#include <elementa/base/serial_channels/channels.h>

Full specialization of serch_transfer for both channels being Memory.

Note: - Need to be inline since a full specialization becomes a non-template function and therefore cannot be included more than once.

Definition at line 593 of file channels.h.

References ELE_CODE_TRACE_OFF, elementa::base::serch_st_to_string(), and elementa::base::SerChI_Memory::transfer().

◆ SerChIO_Memory() [1/3]

template<typename T >

elementa::base::SerChIO_Memory::SerChIO_Memory	(	void *	begin,
		T	n
	)

noexcept

#include <elementa/base/serial_channels/channels.h>

Template constructor.

Template Parameters

T	must be an integral type for indicating length.

Parameters

begin	is a pointer to the first char in memory. Cannot be null.
n	is the number of chars stored there. Cannot be <= 0.

Definition at line 622 of file channels.h.

◆ SerChIO_Memory() [2/3]

template<typename T >

elementa::base::SerChIO_Memory::SerChIO_Memory	(	std::vector< T > &	v,
		typename std::vector< T >::size_type	offbegin = `0`,
		typename std::vector< T >::size_type	offend = `0`
	)

#include <elementa/base/serial_channels/channels.h>

Template constructor for a region within a std::vector.

Template Parameters

T	is the type of element of the vector; this constructor will define the region as a number of such elements, but will deal with them as bytes.

Parameters

offbegin	is the first element in the vector to use by the channel.
offend	is the offset from the ending, backwards, where the channel ends having data.

Definition at line 635 of file channels.h.

References ELE_CODE_INVARG, and elementa::base::SerChIO_Memory::reset().

◆ SerChIO_Memory() [3/3]

template<typename T , std::size_t N>

elementa::base::SerChIO_Memory::SerChIO_Memory	(	std::array< T, N > &	a,
		typename std::array< T, N >::size_type	offbegin = `0`,
		typename std::array< T, N >::size_type	offend = `0`
	)

#include <elementa/base/serial_channels/channels.h>

Template constructor for a region within a std::array.

Template Parameters

T	is the type of element of the vector; this constructor will define the region as a number of such elements, but will deal with them as bytes.

Parameters

offbegin	is the first element in the vector to use by the channel.
offend	is the offset from the ending, backwards, where the channel ends having data.

Definition at line 652 of file channels.h.

References ELE_CODE_INVARG, and elementa::base::SerChIO_Memory::reset().

◆ SerChI_Memory() [1/3]

template<typename T >

elementa::base::SerChI_Memory::SerChI_Memory	(	const void *	begin,
		T	n
	)

noexcept

#include <elementa/base/serial_channels/channels.h>

Template constructor.

Template Parameters

T	must be an integral type for indicating length.

Parameters

begin	is a pointer to the first char in memory. Cannot be null.
n	is the number of chars stored there. Cannot be <= 0.

Definition at line 676 of file channels.h.

◆ SerChI_Memory() [2/3]

template<typename T >

elementa::base::SerChI_Memory::SerChI_Memory	(	const std::vector< T > &	v,
		typename std::vector< T >::size_type	offbegin = `0`,
		typename std::vector< T >::size_type	offend = `0`
	)

#include <elementa/base/serial_channels/channels.h>

Template constructor for a region within a std::vector.

Template Parameters

T	is the type of element of the vector; this constructor will define the region as a number of such elements, but will deal with them as bytes.

Parameters

offbegin	is the first element in the vector to use.
offend	is the offset from the ending, backwards.

Definition at line 689 of file channels.h.

References ELE_CODE_INVARG, and elementa::base::SerChI_Memory::reset().

◆ SerChI_Memory() [3/3]

template<typename T , std::size_t N>

elementa::base::SerChI_Memory::SerChI_Memory	(	const std::array< T, N > &	a,
		typename std::array< T, N >::size_type	offbegin = `0`,
		typename std::array< T, N >::size_type	offend = `0`
	)

#include <elementa/base/serial_channels/channels.h>

Template constructor for a region within a std::array.

Template Parameters

T	is the type of element of the vector; this constructor will define the region as a number of such elements, but will deal with them as bytes.

Parameters

offbegin	is the first element in the vector to use.
offend	is the offset from the ending, backwards.

Definition at line 707 of file channels.h.

References ELE_CODE_INVARG, and elementa::base::SerChI_Memory::reset().

Description

Classes

Functions

Variables

Class Documentation

◆ elementa::base::SerChO_Null

Constructor & Destructor Documentation

◆ SerChO_Null()

◆ elementa::base::SerChO_NullCoBuf

Public Member Functions

Constructor & Destructor Documentation

◆ SerChO_NullCoBuf()

Member Function Documentation

◆ size()

◆ reset()

◆ count()

◆ buffer()

◆ elementa::base::SerChO_AppCont

Public Member Functions

Constructor & Destructor Documentation

◆ SerChO_AppCont()

Member Function Documentation

◆ container()

◆ elementa::base::SerChI_Constant

Public Member Functions

Constructor & Destructor Documentation

◆ SerChI_Constant()

◆ elementa::base::SerChI_Procedural

Public Types

Public Member Functions

Member Typedef Documentation

◆ Procedure

Constructor & Destructor Documentation

◆ SerChI_Procedural()

◆ elementa::base::InStreamBuf_MemoryPriv

Public Member Functions

◆ elementa::base::InOutStreamBuf_MemoryPriv

Public Member Functions

◆ elementa::base::SerChIO_Memory

Public Member Functions

Constructor & Destructor Documentation

◆ SerChIO_Memory()

Member Function Documentation

◆ transfer()

◆ elementa::base::SerChI_Memory

Public Member Functions

Constructor & Destructor Documentation

◆ SerChI_Memory()

Member Function Documentation

◆ transfer()

Function Documentation

◆ serch_transfer< SerChIO_Memory, SerChIO_Memory >()

◆ serch_transfer< SerChI_Memory, SerChIO_Memory >()

◆ SerChIO_Memory() [1/3]

◆ SerChIO_Memory() [2/3]

◆ SerChIO_Memory() [3/3]

◆ SerChI_Memory() [1/3]

◆ SerChI_Memory() [2/3]

◆ SerChI_Memory() [3/3]