Description

Basic definitions for serial channels.

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):

They are "char" based channels. In Elementa, a char is equivalent to an octect, thus, these are binary channels in practice.
Their "base classes" are, therefore, std::istream, std::ostream and std::iostream, all specializations of STL streams for char. Any object derived from that can be used polymorphically in Elementa contexts where an Elementa serial channel is needed.
The input/output/inoutput funcionality of Elementa serial channels is stolen from the one of the STL streams mentioned before, but kept to a minimum. The details are described in the documentation of the OutSerCh, InSerCh and InOutSerCh "base classes" below.
Many methods used in Elementa serial channels return the same channel where the method works, thus allowing chaining the flow of chars in a functional code writing fashion.
As for the error management, that is done equivalently to STL streams, in particular through an std::ios_base::iostate object associated to the channel (no exceptions should be thrown by the channel operations, as it happens in STL built-in channels when they are not explicitly modified). NOTE: Nevertheles, you can use the serch_isgood() function in this module to transform error states into exceptions.

The state bits of the channel and its general state can be got with the following methods, already included in the "base classes" and thus not re-implementable in derived classes if we wish to use polymorphism:

\code
std::ios_base::iostate rdstate(void) const; 
// Read complete state, all bits.
// Non-virtually declared in ios, base of istream/ostream/iostream, 
// which inherits it without modifying -hiding- it with new 
// implementations.
\endcode

\code
void setstate(std::ios_base::iostate st); 
// Set complete state, all bits, to the current state OR the one ST.
// Non-virtually declared in ios, base of istream/ostream/iostream, 
// which inherits it without modifying -hiding- it with new 
// implementations.
\endcode

\code
void clear(); 
// Set complete state, all bits, to a good state (no error).
// Non-virtually declared in ios, base of istream/ostream/iostream, 
// which inherits it without modifying -hiding- it with new 
// implementations.
\endcode

\code
bool good(void) const;
// Whether the channel is ok and working.
// Non-virtually declared in ios, base of istream/ostream/iostream, 
// which inherits it without modifying -hiding- it with new 
// implementations.
\endcode

\code
bool fail(void) const;
// Whether there has been any logical error.
// Non-virtually declared in ios, base of istream/ostream/iostream, 
// which inherits it without modifying -hiding- it with new 
// implementations.
\endcode

\code
bool bad(void) const;
// Whether there has been any error in an I/O operation.
// Non-virtually declared in ios, base of istream/ostream/iostream, 
// which inherits it without modifying -hiding- it with new 
// implementations.
\endcode

\code
bool eof(void) const;
// Whether the channel is exhausted. NOTE: THIS FLAG IS SET ONLY
// IF THE CHANNEL IS TRYING TO GET A CHAR WHEN NONE EXISTS, E.G.,
// AFTER READING THE LAST CHAR OF THE CHANNEL, EOF() IS NOT YET SET.
// Non-virtually declared in ios, base of istream/ostream/iostream, 
// which inherits it without modifying -hiding- it with new 
// implementations.
\endcode

\code
explicit operator bool(void) const;
// True if channel ok and working.
// Non-virtually declared in basic_ios, being istream/ostream/
// iostream instantiations of that template, thus
// having it without modification.
\endcode

\code
bool operator!(void) const;
// True if channel is not ok.
// Non-virtually declared in basic_ios, being istream/ostream/
// iostream instantiations of that template, thus
// having it without modification.
\endcode

Note: - Serial channels, like STL streams, are not copiable; they can be moved if the particular channel considers useful such feature.

See also: Serializers

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 Basics of serial channels:

Classes
class	elementa::base::is_InSerCh< T >
	With this template you can check whether T is an input serial channel. More...

class	elementa::base::is_In_InOut_SerCh< T >
	With this template you can check whether T is an input or inout channel. More...

class	elementa::base::is_OutSerCh< T >
	With this template you can check whether T is an output serial channel. More...

class	elementa::base::is_Out_InOut_SerCh< T >
	With this template you can check whether T is an output or inout channel. More...

class	elementa::base::is_InOutSerCh< T >
	With this template you can check whether T is an in + out serial channel. More...

class	elementa::base::is_SerCh< T >
	With this template you can check whether T is any kind of serial channel. More...

class	elementa::base::SerChError
	Base class for exceptions associated to some serial channel operation. More...

class	elementa::base::SerChErr_Exhausted
	Error to throw when the channel is exhausted but it should not be. More...

class	elementa::base::SerChErr_FewData
	Error to throw when the channel provides less data than it should on read() More...

class	elementa::base::SerChErr_TooManyData
	Error to throw when the channel does not admit too many data. More...

class	elementa::base::SerChErr_State
	Errors thrown by serch_isgood and other functions. More...

class	elementa::base::SerChErr_Unopened
	Errors thrown by channels that must be opened. More...

class	elementa::base::SerChErr_Loc
	Errors related to locations on channels. More...

class	elementa::base::SerChErr_Cont
	Errors related to container-based channels. More...

class	elementa::base::SerChLoc
	Location in a channel, at least in linear form, either at reading or writing. More...

class	elementa::base::SerChLocText
	A location into a text channel consisting of a row and a column. More...

Typedefs
using	elementa::base::SerChSize = std::streamsize
	Type of the size of any channel. More...

using	elementa::base::SerChDatum = std::streambuf::int_type
	Type that can hold either a char or eof. More...

using	elementa::base::SerChCharTraits = std::char_traits< char >
	To have access to the methods of char_traits corresponding to these channs. More...

using	elementa::base::RootSerCh = std::ios
	Class that is at the root of any serial channel in Elementa. More...

using	elementa::base::OutSerCh = std::ostream
	"Base class" that represents any output serial channel in Elementa. More...

using	elementa::base::InSerCh = std::istream
	"Base class" that represents any input serial channel in Elementa. More...

using	elementa::base::InOutSerCh = std::iostream
	"Base class" that represents any input + output serial channel in Elementa. More...

Functions
void	elementa::base::serch_isgood (RootSerCh &serchconst, const std::string &place="", const RTTextWithEnum::Combination &flags={RTTextWith::kAll_})
	Throw an exception if the channel is not good; do nothing otherwise. More...

bool	elementa::base::serch_iseofbutok (RootSerCh &serchconst, const std::string &place="", const RTTextWithEnum::Combination &flags={RTTextWith::kAll_})
	Return TRUE if the channel is eof() (maybe bad/fail); throw if !eof nor good. More...

bool	elementa::base::serch_isexhausted (InSerCh &serch, const std::string &place="", const RTTextWithEnum::Combination &flags={RTTextWith::kAll_})
	Return TRUE if it is eof or exhausted; then throw if the channel is bad/fail. More...

void	elementa::base::serch_hasreadN (InSerCh &chin, char *dest, SerChSize n, const std::string &place="", const RTTextWithEnum::Combination &flags={RTTextWith::kAll_})
	Make sure that N chars are read from CHIN; throws if any error.

void	elementa::base::serch_haswrittenN (OutSerCh &chout, const char *org, SerChSize n, const std::string &place="", const RTTextWithEnum::Combination &flags={RTTextWith::kAll_})
	Make sure that N chars are written to CHOUT; throws if any error.

std::string	elementa::base::serch_st_to_string (std::ios_base::iostate st) noexcept
	Converts an io state into a string. More...

std::string	elementa::base::serch_st_to_string (RootSerCh &ch) noexcept
	Converts the state of a serial channel into a string. More...

std::ios_base::iostate	elementa::base::serch_copy_st (RootSerCh &chorg, RootSerCh &chdest)
	Copy the state of CHORG into DEST, returning that state.

template<class SCOrg , class SCDest >
SerChSize	elementa::base::serch_transfer (SCOrg &chin, SCDest &chout, SerChSize count=0)
	Write COUNT items read from channel CHIN into channel CHOUT. More...

template<class SCOrg , class SCDest >
SerChSize	elementa::base::serch_transfer (SCOrg &&chin, SCDest &&chout, SerChSize count=1)
	Version of serch_transfer for using rvalues (but without moving then). More...

Variables
constexpr SerChDatum	elementa::base::kSerChEOF = std::streambuf::traits_type::eof()
	Const that holds the eof value. More...

Class Documentation

◆ elementa::base::is_InSerCh

class elementa::base::is_InSerCh

template<class T>
class elementa::base::is_InSerCh< T >

With this template you can check whether T is an input serial channel.

Definition at line 375 of file basics.h.

Static Public Attributes
static constexpr bool	value

Member Data Documentation

◆ value

template<class T >

constexpr bool elementa::base::is_InSerCh< T >::value

staticconstexpr

Initial value:

= 
        ( std::is_base_of<InSerCh,T>::value &&
          std::is_same<typename T::char_type,char>::value
        )

Definition at line 379 of file basics.h.

◆ elementa::base::is_In_InOut_SerCh

class elementa::base::is_In_InOut_SerCh

template<class T>
class elementa::base::is_In_InOut_SerCh< T >

With this template you can check whether T is an input or inout channel.

Definition at line 388 of file basics.h.

Static Public Attributes
static constexpr bool	value

Member Data Documentation

◆ value

template<class T >

constexpr bool elementa::base::is_In_InOut_SerCh< T >::value

staticconstexpr

Initial value:

= 
        ( ( std::is_base_of<InSerCh,T>::value || 
            std::is_base_of<InOutSerCh,T>::value ) &&
          std::is_same<typename T::char_type,char>::value
        )

Definition at line 392 of file basics.h.

◆ elementa::base::is_OutSerCh

class elementa::base::is_OutSerCh

template<class T>
class elementa::base::is_OutSerCh< T >

With this template you can check whether T is an output serial channel.

Definition at line 402 of file basics.h.

Static Public Attributes
static constexpr bool	value

Member Data Documentation

◆ value

template<class T >

constexpr bool elementa::base::is_OutSerCh< T >::value

staticconstexpr

Initial value:

= 
        ( std::is_base_of<OutSerCh,T>::value &&
          std::is_same<typename T::char_type,char>::value
        )

Definition at line 406 of file basics.h.

◆ elementa::base::is_Out_InOut_SerCh

class elementa::base::is_Out_InOut_SerCh

template<class T>
class elementa::base::is_Out_InOut_SerCh< T >

With this template you can check whether T is an output or inout channel.

Definition at line 415 of file basics.h.

Static Public Attributes
static constexpr bool	value

Member Data Documentation

◆ value

template<class T >

constexpr bool elementa::base::is_Out_InOut_SerCh< T >::value

staticconstexpr

Initial value:

= 
        ( ( std::is_base_of<OutSerCh,T>::value || 
            std::is_base_of<InOutSerCh,T>::value ) &&
          std::is_same<typename T::char_type,char>::value
        )

Definition at line 419 of file basics.h.

◆ elementa::base::is_InOutSerCh

class elementa::base::is_InOutSerCh

template<class T>
class elementa::base::is_InOutSerCh< T >

With this template you can check whether T is an in + out serial channel.

Definition at line 429 of file basics.h.

Static Public Attributes
static constexpr bool	value

Member Data Documentation

◆ value

template<class T >

constexpr bool elementa::base::is_InOutSerCh< T >::value

staticconstexpr

Initial value:

= 
        ( std::is_base_of<InOutSerCh,T>::value &&
          std::is_same<typename T::char_type,char>::value
        )

Definition at line 433 of file basics.h.

◆ elementa::base::is_SerCh

class elementa::base::is_SerCh

template<class T>
class elementa::base::is_SerCh< T >

With this template you can check whether T is any kind of serial channel.

Definition at line 442 of file basics.h.

Static Public Attributes
static constexpr bool	value

Member Data Documentation

◆ value

template<class T >

constexpr bool elementa::base::is_SerCh< T >::value

staticconstexpr

Initial value:

= ( is_InSerCh<T>::value || 
                                    is_OutSerCh<T>::value || 
                                    is_InOutSerCh<T>::value )

Definition at line 446 of file basics.h.

◆ elementa::base::SerChError

class elementa::base::SerChError

Base class for exceptions associated to some serial channel operation.

Definition at line 537 of file basics.h.

Inheritance diagram for elementa::base::SerChError:

[legend]

Collaboration diagram for elementa::base::SerChError:

[legend]

Public Types
Types, consts., etc.
using	StdBase = std::runtime_error

Public Member Functions
	SerChError (const std::string &explanation)

	ELE_CLASS_EXCOVERRIDE (SerChError)

Launching methods
virtual Exc &	asERR (const std::string &context) noexcept
	Transform it to be thrown as ERR with the given context. More...

virtual Exc &	asEXC (const std::string &place, const RTTextWithEnum::Combination &flags={RTTextWith::kAll_}) noexcept
	Transform it to be thrown as EXC with the given place and flags. More...

Catching methods
const char *	what (void) const noexcept override
	Return the complete message. It will live as long as this exception. More...

const char *	explanation (void) const noexcept
	Return the explanation only. It will live as long as this exception. More...

const char *	context (void) const noexcept
	Return the place (EXC) or context (ERR) only. Will live as long as this. More...

Member Typedef Documentation

◆ StdBase

using elementa::base::Exc::StdBase = std::runtime_error

inherited

Definition at line 119 of file exceptions.h.

Constructor & Destructor Documentation

◆ SerChError()

elementa::base::SerChError::SerChError ( const std::string & explanation )

inline

Definition at line 541 of file basics.h.

Member Function Documentation

◆ asERR()

virtual Exc & elementa::base::Exc::asERR ( const std::string & context )

virtualnoexceptinherited

Transform it to be thrown as ERR with the given context.

Reimplemented in elementa::base::unimplemented, elementa::base::todo, elementa::base::notreach, elementa::base::invstate, elementa::base::internal_error, elementa::base::notfound, elementa::base::invarg, and elementa::base::outofrange.

◆ asEXC()

virtual Exc & elementa::base::Exc::asEXC	(	const std::string &	place,
		const RTTextWithEnum::Combination &	flags = `{RTTextWith::kAll_}`
	)

virtualnoexceptinherited

Transform it to be thrown as EXC with the given place and flags.

The flags are explained in debugging.h, runtime_src_place() function.

Referenced by elementa::base::Szer_Char::deser(), and elementa::base::Szer_NatBin< NatType >::deser().

◆ what()

const char * elementa::base::Exc::what ( void ) const

inlineoverridenoexceptinherited

Return the complete message. It will live as long as this exception.

The message will be one-line except if the explanation or place/context contain some CR.

Definition at line 161 of file exceptions.h.

◆ explanation()

const char * elementa::base::Exc::explanation ( void ) const

inlinenoexceptinherited

Return the explanation only. It will live as long as this exception.

Definition at line 164 of file exceptions.h.

◆ context()

const char * elementa::base::Exc::context ( void ) const

inlinenoexceptinherited

Return the place (EXC) or context (ERR) only. Will live as long as this.

Definition at line 167 of file exceptions.h.

◆ elementa::base::SerChErr_Exhausted

class elementa::base::SerChErr_Exhausted

Error to throw when the channel is exhausted but it should not be.

Definition at line 551 of file basics.h.

Inheritance diagram for elementa::base::SerChErr_Exhausted:

[legend]

Collaboration diagram for elementa::base::SerChErr_Exhausted:

[legend]

Public Types
Types, consts., etc.
using	StdBase = std::runtime_error

Public Member Functions
	SerChErr_Exhausted (const std::string &explanation)

	ELE_CLASS_EXCOVERRIDE (SerChErr_Exhausted)

	ELE_CLASS_EXCOVERRIDE (SerChError)

Launching methods
virtual Exc &	asERR (const std::string &context) noexcept
	Transform it to be thrown as ERR with the given context. More...

virtual Exc &	asEXC (const std::string &place, const RTTextWithEnum::Combination &flags={RTTextWith::kAll_}) noexcept
	Transform it to be thrown as EXC with the given place and flags. More...

Catching methods
const char *	what (void) const noexcept override
	Return the complete message. It will live as long as this exception. More...

const char *	explanation (void) const noexcept
	Return the explanation only. It will live as long as this exception. More...

const char *	context (void) const noexcept
	Return the place (EXC) or context (ERR) only. Will live as long as this. More...

Member Typedef Documentation

◆ StdBase

using elementa::base::Exc::StdBase = std::runtime_error

inherited

Definition at line 119 of file exceptions.h.

Constructor & Destructor Documentation

◆ SerChErr_Exhausted()

elementa::base::SerChErr_Exhausted::SerChErr_Exhausted ( const std::string & explanation )

inline

Definition at line 555 of file basics.h.

Member Function Documentation

◆ asERR()

virtual Exc & elementa::base::Exc::asERR ( const std::string & context )

virtualnoexceptinherited

Transform it to be thrown as ERR with the given context.

Reimplemented in elementa::base::unimplemented, elementa::base::todo, elementa::base::notreach, elementa::base::invstate, elementa::base::internal_error, elementa::base::notfound, elementa::base::invarg, and elementa::base::outofrange.

◆ asEXC()

virtual Exc & elementa::base::Exc::asEXC	(	const std::string &	place,
		const RTTextWithEnum::Combination &	flags = `{RTTextWith::kAll_}`
	)

virtualnoexceptinherited

Transform it to be thrown as EXC with the given place and flags.

The flags are explained in debugging.h, runtime_src_place() function.

Referenced by elementa::base::Szer_Char::deser(), and elementa::base::Szer_NatBin< NatType >::deser().

◆ what()

const char * elementa::base::Exc::what ( void ) const

inlineoverridenoexceptinherited

Return the complete message. It will live as long as this exception.

The message will be one-line except if the explanation or place/context contain some CR.

Definition at line 161 of file exceptions.h.

◆ explanation()

const char * elementa::base::Exc::explanation ( void ) const

inlinenoexceptinherited

Return the explanation only. It will live as long as this exception.

Definition at line 164 of file exceptions.h.

◆ context()

const char * elementa::base::Exc::context ( void ) const

inlinenoexceptinherited

Return the place (EXC) or context (ERR) only. Will live as long as this.

Definition at line 167 of file exceptions.h.

◆ elementa::base::SerChErr_FewData

class elementa::base::SerChErr_FewData

Error to throw when the channel provides less data than it should on read()

Definition at line 565 of file basics.h.

Inheritance diagram for elementa::base::SerChErr_FewData:

[legend]

Collaboration diagram for elementa::base::SerChErr_FewData:

[legend]

Public Types
Types, consts., etc.
using	StdBase = std::runtime_error

Public Member Functions
	SerChErr_FewData (const std::string &explanation)

	ELE_CLASS_EXCOVERRIDE (SerChError)

Launching methods
virtual Exc &	asERR (const std::string &context) noexcept
	Transform it to be thrown as ERR with the given context. More...

virtual Exc &	asEXC (const std::string &place, const RTTextWithEnum::Combination &flags={RTTextWith::kAll_}) noexcept
	Transform it to be thrown as EXC with the given place and flags. More...

Catching methods
const char *	what (void) const noexcept override
	Return the complete message. It will live as long as this exception. More...

const char *	explanation (void) const noexcept
	Return the explanation only. It will live as long as this exception. More...

const char *	context (void) const noexcept
	Return the place (EXC) or context (ERR) only. Will live as long as this. More...

Member Typedef Documentation

◆ StdBase

using elementa::base::Exc::StdBase = std::runtime_error

inherited

Definition at line 119 of file exceptions.h.

Constructor & Destructor Documentation

◆ SerChErr_FewData()

elementa::base::SerChErr_FewData::SerChErr_FewData ( const std::string & explanation )

inline

Definition at line 569 of file basics.h.

Member Function Documentation

◆ asERR()

virtual Exc & elementa::base::Exc::asERR ( const std::string & context )

virtualnoexceptinherited

Transform it to be thrown as ERR with the given context.

Reimplemented in elementa::base::unimplemented, elementa::base::todo, elementa::base::notreach, elementa::base::invstate, elementa::base::internal_error, elementa::base::notfound, elementa::base::invarg, and elementa::base::outofrange.

◆ asEXC()

virtual Exc & elementa::base::Exc::asEXC	(	const std::string &	place,
		const RTTextWithEnum::Combination &	flags = `{RTTextWith::kAll_}`
	)

virtualnoexceptinherited

Transform it to be thrown as EXC with the given place and flags.

The flags are explained in debugging.h, runtime_src_place() function.

Referenced by elementa::base::Szer_Char::deser(), and elementa::base::Szer_NatBin< NatType >::deser().

◆ what()

const char * elementa::base::Exc::what ( void ) const

inlineoverridenoexceptinherited

Return the complete message. It will live as long as this exception.

The message will be one-line except if the explanation or place/context contain some CR.

Definition at line 161 of file exceptions.h.

◆ explanation()

const char * elementa::base::Exc::explanation ( void ) const

inlinenoexceptinherited

Return the explanation only. It will live as long as this exception.

Definition at line 164 of file exceptions.h.

◆ context()

const char * elementa::base::Exc::context ( void ) const

inlinenoexceptinherited

Return the place (EXC) or context (ERR) only. Will live as long as this.

Definition at line 167 of file exceptions.h.

◆ elementa::base::SerChErr_TooManyData

class elementa::base::SerChErr_TooManyData

Error to throw when the channel does not admit too many data.

Definition at line 579 of file basics.h.

Inheritance diagram for elementa::base::SerChErr_TooManyData:

[legend]

Collaboration diagram for elementa::base::SerChErr_TooManyData:

[legend]

Public Types
Types, consts., etc.
using	StdBase = std::runtime_error

Public Member Functions
	SerChErr_TooManyData (const std::string &explanation)

	ELE_CLASS_EXCOVERRIDE (SerChError)

Launching methods
virtual Exc &	asERR (const std::string &context) noexcept
	Transform it to be thrown as ERR with the given context. More...

virtual Exc &	asEXC (const std::string &place, const RTTextWithEnum::Combination &flags={RTTextWith::kAll_}) noexcept
	Transform it to be thrown as EXC with the given place and flags. More...

Catching methods
const char *	what (void) const noexcept override
	Return the complete message. It will live as long as this exception. More...

const char *	explanation (void) const noexcept
	Return the explanation only. It will live as long as this exception. More...

const char *	context (void) const noexcept
	Return the place (EXC) or context (ERR) only. Will live as long as this. More...

Member Typedef Documentation

◆ StdBase

using elementa::base::Exc::StdBase = std::runtime_error

inherited

Definition at line 119 of file exceptions.h.

Constructor & Destructor Documentation

◆ SerChErr_TooManyData()

elementa::base::SerChErr_TooManyData::SerChErr_TooManyData ( const std::string & explanation )

inline

Definition at line 583 of file basics.h.

Member Function Documentation

◆ asERR()

virtual Exc & elementa::base::Exc::asERR ( const std::string & context )

virtualnoexceptinherited

Transform it to be thrown as ERR with the given context.

Reimplemented in elementa::base::unimplemented, elementa::base::todo, elementa::base::notreach, elementa::base::invstate, elementa::base::internal_error, elementa::base::notfound, elementa::base::invarg, and elementa::base::outofrange.

◆ asEXC()

virtual Exc & elementa::base::Exc::asEXC	(	const std::string &	place,
		const RTTextWithEnum::Combination &	flags = `{RTTextWith::kAll_}`
	)

virtualnoexceptinherited

Transform it to be thrown as EXC with the given place and flags.

The flags are explained in debugging.h, runtime_src_place() function.

Referenced by elementa::base::Szer_Char::deser(), and elementa::base::Szer_NatBin< NatType >::deser().

◆ what()

const char * elementa::base::Exc::what ( void ) const

inlineoverridenoexceptinherited

Return the complete message. It will live as long as this exception.

The message will be one-line except if the explanation or place/context contain some CR.

Definition at line 161 of file exceptions.h.

◆ explanation()

const char * elementa::base::Exc::explanation ( void ) const

inlinenoexceptinherited

Return the explanation only. It will live as long as this exception.

Definition at line 164 of file exceptions.h.

◆ context()

const char * elementa::base::Exc::context ( void ) const

inlinenoexceptinherited

Return the place (EXC) or context (ERR) only. Will live as long as this.

Definition at line 167 of file exceptions.h.

◆ elementa::base::SerChErr_State

class elementa::base::SerChErr_State

Errors thrown by serch_isgood and other functions.

Definition at line 594 of file basics.h.

Inheritance diagram for elementa::base::SerChErr_State:

[legend]

Collaboration diagram for elementa::base::SerChErr_State:

[legend]

Public Types
Types, consts., etc.
using	StdBase = std::runtime_error

Public Member Functions
	SerChErr_State (const std::string &explanation)

	ELE_CLASS_EXCOVERRIDE (SerChError)

Launching methods
virtual Exc &	asERR (const std::string &context) noexcept
	Transform it to be thrown as ERR with the given context. More...

virtual Exc &	asEXC (const std::string &place, const RTTextWithEnum::Combination &flags={RTTextWith::kAll_}) noexcept
	Transform it to be thrown as EXC with the given place and flags. More...

Catching methods
const char *	what (void) const noexcept override
	Return the complete message. It will live as long as this exception. More...

const char *	explanation (void) const noexcept
	Return the explanation only. It will live as long as this exception. More...

const char *	context (void) const noexcept
	Return the place (EXC) or context (ERR) only. Will live as long as this. More...

Member Typedef Documentation

◆ StdBase

using elementa::base::Exc::StdBase = std::runtime_error

inherited

Definition at line 119 of file exceptions.h.

Constructor & Destructor Documentation

◆ SerChErr_State()

elementa::base::SerChErr_State::SerChErr_State ( const std::string & explanation )

inline

Definition at line 598 of file basics.h.

Member Function Documentation

◆ asERR()

virtual Exc & elementa::base::Exc::asERR ( const std::string & context )

virtualnoexceptinherited

Transform it to be thrown as ERR with the given context.

Reimplemented in elementa::base::unimplemented, elementa::base::todo, elementa::base::notreach, elementa::base::invstate, elementa::base::internal_error, elementa::base::notfound, elementa::base::invarg, and elementa::base::outofrange.

◆ asEXC()

virtual Exc & elementa::base::Exc::asEXC	(	const std::string &	place,
		const RTTextWithEnum::Combination &	flags = `{RTTextWith::kAll_}`
	)

virtualnoexceptinherited

Transform it to be thrown as EXC with the given place and flags.

The flags are explained in debugging.h, runtime_src_place() function.

Referenced by elementa::base::Szer_Char::deser(), and elementa::base::Szer_NatBin< NatType >::deser().

◆ what()

const char * elementa::base::Exc::what ( void ) const

inlineoverridenoexceptinherited

Return the complete message. It will live as long as this exception.

The message will be one-line except if the explanation or place/context contain some CR.

Definition at line 161 of file exceptions.h.

◆ explanation()

const char * elementa::base::Exc::explanation ( void ) const

inlinenoexceptinherited

Return the explanation only. It will live as long as this exception.

Definition at line 164 of file exceptions.h.

◆ context()

const char * elementa::base::Exc::context ( void ) const

inlinenoexceptinherited

Return the place (EXC) or context (ERR) only. Will live as long as this.

Definition at line 167 of file exceptions.h.

◆ elementa::base::SerChErr_Unopened

class elementa::base::SerChErr_Unopened

Errors thrown by channels that must be opened.

Definition at line 608 of file basics.h.

Inheritance diagram for elementa::base::SerChErr_Unopened:

[legend]

Collaboration diagram for elementa::base::SerChErr_Unopened:

[legend]

Public Types
Types, consts., etc.
using	StdBase = std::runtime_error

Public Member Functions
	SerChErr_Unopened (const std::string &explanation)

	ELE_CLASS_EXCOVERRIDE (SerChError)

Launching methods
virtual Exc &	asERR (const std::string &context) noexcept
	Transform it to be thrown as ERR with the given context. More...

virtual Exc &	asEXC (const std::string &place, const RTTextWithEnum::Combination &flags={RTTextWith::kAll_}) noexcept
	Transform it to be thrown as EXC with the given place and flags. More...

Catching methods
const char *	what (void) const noexcept override
	Return the complete message. It will live as long as this exception. More...

const char *	explanation (void) const noexcept
	Return the explanation only. It will live as long as this exception. More...

const char *	context (void) const noexcept
	Return the place (EXC) or context (ERR) only. Will live as long as this. More...

Member Typedef Documentation

◆ StdBase

using elementa::base::Exc::StdBase = std::runtime_error

inherited

Definition at line 119 of file exceptions.h.

Constructor & Destructor Documentation

◆ SerChErr_Unopened()

elementa::base::SerChErr_Unopened::SerChErr_Unopened ( const std::string & explanation )

inline

Definition at line 612 of file basics.h.

Member Function Documentation

◆ asERR()

virtual Exc & elementa::base::Exc::asERR ( const std::string & context )

virtualnoexceptinherited

Transform it to be thrown as ERR with the given context.

Reimplemented in elementa::base::unimplemented, elementa::base::todo, elementa::base::notreach, elementa::base::invstate, elementa::base::internal_error, elementa::base::notfound, elementa::base::invarg, and elementa::base::outofrange.

◆ asEXC()

virtual Exc & elementa::base::Exc::asEXC	(	const std::string &	place,
		const RTTextWithEnum::Combination &	flags = `{RTTextWith::kAll_}`
	)

virtualnoexceptinherited

Transform it to be thrown as EXC with the given place and flags.

The flags are explained in debugging.h, runtime_src_place() function.

Referenced by elementa::base::Szer_Char::deser(), and elementa::base::Szer_NatBin< NatType >::deser().

◆ what()

const char * elementa::base::Exc::what ( void ) const

inlineoverridenoexceptinherited

Return the complete message. It will live as long as this exception.

The message will be one-line except if the explanation or place/context contain some CR.

Definition at line 161 of file exceptions.h.

◆ explanation()

const char * elementa::base::Exc::explanation ( void ) const

inlinenoexceptinherited

Return the explanation only. It will live as long as this exception.

Definition at line 164 of file exceptions.h.

◆ context()

const char * elementa::base::Exc::context ( void ) const

inlinenoexceptinherited

Return the place (EXC) or context (ERR) only. Will live as long as this.

Definition at line 167 of file exceptions.h.

◆ elementa::base::SerChErr_Loc

class elementa::base::SerChErr_Loc

Errors related to locations on channels.

Definition at line 622 of file basics.h.

Inheritance diagram for elementa::base::SerChErr_Loc:

[legend]

Collaboration diagram for elementa::base::SerChErr_Loc:

[legend]

Public Types
Types, consts., etc.
using	StdBase = std::runtime_error

Public Member Functions
	SerChErr_Loc (const std::string &explanation)

	ELE_CLASS_EXCOVERRIDE (SerChError)

Launching methods
virtual Exc &	asERR (const std::string &context) noexcept
	Transform it to be thrown as ERR with the given context. More...

virtual Exc &	asEXC (const std::string &place, const RTTextWithEnum::Combination &flags={RTTextWith::kAll_}) noexcept
	Transform it to be thrown as EXC with the given place and flags. More...

Catching methods
const char *	what (void) const noexcept override
	Return the complete message. It will live as long as this exception. More...

const char *	explanation (void) const noexcept
	Return the explanation only. It will live as long as this exception. More...

const char *	context (void) const noexcept
	Return the place (EXC) or context (ERR) only. Will live as long as this. More...

Member Typedef Documentation

◆ StdBase

using elementa::base::Exc::StdBase = std::runtime_error

inherited

Definition at line 119 of file exceptions.h.

Constructor & Destructor Documentation

◆ SerChErr_Loc()

elementa::base::SerChErr_Loc::SerChErr_Loc ( const std::string & explanation )

inline

Definition at line 626 of file basics.h.

Member Function Documentation

◆ asERR()

virtual Exc & elementa::base::Exc::asERR ( const std::string & context )

virtualnoexceptinherited

Transform it to be thrown as ERR with the given context.

Reimplemented in elementa::base::unimplemented, elementa::base::todo, elementa::base::notreach, elementa::base::invstate, elementa::base::internal_error, elementa::base::notfound, elementa::base::invarg, and elementa::base::outofrange.

◆ asEXC()

virtual Exc & elementa::base::Exc::asEXC	(	const std::string &	place,
		const RTTextWithEnum::Combination &	flags = `{RTTextWith::kAll_}`
	)

virtualnoexceptinherited

Transform it to be thrown as EXC with the given place and flags.

The flags are explained in debugging.h, runtime_src_place() function.

Referenced by elementa::base::Szer_Char::deser(), and elementa::base::Szer_NatBin< NatType >::deser().

◆ what()

const char * elementa::base::Exc::what ( void ) const

inlineoverridenoexceptinherited

Return the complete message. It will live as long as this exception.

The message will be one-line except if the explanation or place/context contain some CR.

Definition at line 161 of file exceptions.h.

◆ explanation()

const char * elementa::base::Exc::explanation ( void ) const

inlinenoexceptinherited

Return the explanation only. It will live as long as this exception.

Definition at line 164 of file exceptions.h.

◆ context()

const char * elementa::base::Exc::context ( void ) const

inlinenoexceptinherited

Return the place (EXC) or context (ERR) only. Will live as long as this.

Definition at line 167 of file exceptions.h.

◆ elementa::base::SerChErr_Cont

class elementa::base::SerChErr_Cont

Errors related to container-based channels.

Definition at line 635 of file basics.h.

Inheritance diagram for elementa::base::SerChErr_Cont:

[legend]

Collaboration diagram for elementa::base::SerChErr_Cont:

[legend]

Public Types
Types, consts., etc.
using	StdBase = std::runtime_error

Public Member Functions
	SerChErr_Cont (const std::string &explanation)

	ELE_CLASS_EXCOVERRIDE (SerChError)

Launching methods
virtual Exc &	asERR (const std::string &context) noexcept
	Transform it to be thrown as ERR with the given context. More...

virtual Exc &	asEXC (const std::string &place, const RTTextWithEnum::Combination &flags={RTTextWith::kAll_}) noexcept
	Transform it to be thrown as EXC with the given place and flags. More...

Catching methods
const char *	what (void) const noexcept override
	Return the complete message. It will live as long as this exception. More...

const char *	explanation (void) const noexcept
	Return the explanation only. It will live as long as this exception. More...

const char *	context (void) const noexcept
	Return the place (EXC) or context (ERR) only. Will live as long as this. More...

Member Typedef Documentation

◆ StdBase

using elementa::base::Exc::StdBase = std::runtime_error

inherited

Definition at line 119 of file exceptions.h.

Constructor & Destructor Documentation

◆ SerChErr_Cont()

elementa::base::SerChErr_Cont::SerChErr_Cont ( const std::string & explanation )

inline

Definition at line 639 of file basics.h.

Member Function Documentation

◆ asERR()

virtual Exc & elementa::base::Exc::asERR ( const std::string & context )

virtualnoexceptinherited

Transform it to be thrown as ERR with the given context.

Reimplemented in elementa::base::unimplemented, elementa::base::todo, elementa::base::notreach, elementa::base::invstate, elementa::base::internal_error, elementa::base::notfound, elementa::base::invarg, and elementa::base::outofrange.

◆ asEXC()

virtual Exc & elementa::base::Exc::asEXC	(	const std::string &	place,
		const RTTextWithEnum::Combination &	flags = `{RTTextWith::kAll_}`
	)

virtualnoexceptinherited

Transform it to be thrown as EXC with the given place and flags.

The flags are explained in debugging.h, runtime_src_place() function.

Referenced by elementa::base::Szer_Char::deser(), and elementa::base::Szer_NatBin< NatType >::deser().

◆ what()

const char * elementa::base::Exc::what ( void ) const

inlineoverridenoexceptinherited

Return the complete message. It will live as long as this exception.

The message will be one-line except if the explanation or place/context contain some CR.

Definition at line 161 of file exceptions.h.

◆ explanation()

const char * elementa::base::Exc::explanation ( void ) const

inlinenoexceptinherited

Return the explanation only. It will live as long as this exception.

Definition at line 164 of file exceptions.h.

◆ context()

const char * elementa::base::Exc::context ( void ) const

inlinenoexceptinherited

Return the place (EXC) or context (ERR) only. Will live as long as this.

Definition at line 167 of file exceptions.h.

◆ elementa::base::SerChLoc

class elementa::base::SerChLoc

Location in a channel, at least in linear form, either at reading or writing.

This class implements locations that can be both incremented and decremented. The location always points to the next character to read/write in the channel. This class can be derived to provided more sophisticated locations (rather than simply linear), as, e.g., in the SerChLocText class.

Note: - This class is not thread-safe.; - Implemented as a separate class from the channel and not as a mixin or derived class from it in order to respect the pre-existing channels in the STL, that could not be augmented with locations otherwise.

Definition at line 768 of file basics.h.

Inheritance diagram for elementa::base::SerChLoc:

[legend]

Collaboration diagram for elementa::base::SerChLoc:

[legend]

Public Types
Types, consts, etc.
using	Ptr = std::shared_ptr< SerChLoc >
	Safe pointer for polymorphic behaviours. More...

Public Member Functions
virtual Clonable *	emptyClone (void) const
	Derived classes can override this to provide a clone that is "empty". More...

Constructors
	SerChLoc (void) noexcept
	Default constructor: establish 0 as the current location in the channel. More...

	SerChLoc (const SerChLoc &oth)
	Copy constructor: the stored value is cleared. More...

SerChLoc &	operator= (const SerChLoc &oth)
	Copy assignment: the stored value is cleared. More...

	SerChLoc (SerChLoc &&oth)
	Move constructor: the stored value of OTH is moved to this. More...

SerChLoc &	operator= (SerChLoc &&oth)
	Move assignment: the stored value of OTH is moved to this. More...

virtual	~SerChLoc (void)
	Destructor. More...

Methods that can be overriden
virtual SerChLoc *	clone (void) const
	Clone the location. More...

virtual void	reset (void) noexcept
	Reset the location to the beginning. More...

virtual void	inc (char c=' ')
	Increment the location after reading/writing char C. More...

virtual void	inc (const char *t, SerChSize n)
	Increment the location after reading/writing a block T of N chars. More...

virtual void	dec (char c)
	Decrement the location after un-reading/un-writing char C. More...

virtual void	dec (const char *t, SerChSize n)
	Decrement the location after un-reading/un-writing a block T of N chars. More...

virtual bool	operator== (const SerChLoc &o) const
	Equality. More...

virtual bool	operator!= (const SerChLoc &o) const
	Unequality. More...

virtual std::string	to_string (bool compact=false) const noexcept
	Convert the location to a string. More...

Getters
SerChSize	linear (void) const noexcept
	Get the current location. More...

Member Typedef Documentation

◆ Ptr

using elementa::base::SerChLoc::Ptr = std::shared_ptr<SerChLoc>

Safe pointer for polymorphic behaviours.

Definition at line 776 of file basics.h.

Constructor & Destructor Documentation

◆ SerChLoc() [1/3]

elementa::base::SerChLoc::SerChLoc ( void )

inlinenoexcept

Default constructor: establish 0 as the current location in the channel.

Definition at line 785 of file basics.h.

References reset().

◆ SerChLoc() [2/3]

elementa::base::SerChLoc::SerChLoc ( const SerChLoc & oth )

inline

Copy constructor: the stored value is cleared.

Definition at line 788 of file basics.h.

◆ SerChLoc() [3/3]

elementa::base::SerChLoc::SerChLoc ( SerChLoc && oth )

inline

Move constructor: the stored value of OTH is moved to this.

Definition at line 796 of file basics.h.

◆ ~SerChLoc()

virtual elementa::base::SerChLoc::~SerChLoc ( void )

inlinevirtual

Destructor.

Definition at line 802 of file basics.h.

Member Function Documentation

◆ operator=() [1/2]

SerChLoc & elementa::base::SerChLoc::operator= ( const SerChLoc & oth )

inline

Copy assignment: the stored value is cleared.

Definition at line 792 of file basics.h.

◆ operator=() [2/2]

SerChLoc & elementa::base::SerChLoc::operator= ( SerChLoc && oth )

inline

Move assignment: the stored value of OTH is moved to this.

Definition at line 799 of file basics.h.

◆ linear()

SerChSize elementa::base::SerChLoc::linear ( void ) const

inlinenoexcept

Get the current location.

Definition at line 811 of file basics.h.

◆ clone()

virtual SerChLoc * elementa::base::SerChLoc::clone ( void ) const

inlinevirtual

Clone the location.

Implements elementa::patterns::Clonable.

Reimplemented in elementa::base::SerChLocText.

Definition at line 820 of file basics.h.

◆ reset()

virtual void elementa::base::SerChLoc::reset ( void )

inlinevirtualnoexcept

Reset the location to the beginning.

Reimplemented in elementa::base::SerChLocText.

Definition at line 824 of file basics.h.

Referenced by SerChLoc().

◆ inc() [1/2]

virtual void elementa::base::SerChLoc::inc ( char c = ' ' )

inlinevirtual

Increment the location after reading/writing char C.

Virtual for derived classes to enrich this behavior.

Reimplemented in elementa::base::SerChLocText.

Definition at line 829 of file basics.h.

◆ inc() [2/2]

virtual void elementa::base::SerChLoc::inc	(	const char *	t,
		SerChSize	n
	)

inlinevirtual

Increment the location after reading/writing a block T of N chars.

Virtual for derived classes to enrich this behavior.

Reimplemented in elementa::base::SerChLocText.

Definition at line 833 of file basics.h.

◆ dec() [1/2]

virtual void elementa::base::SerChLoc::dec ( char c )

virtual

Decrement the location after un-reading/un-writing char C.

Throw if that decrement is not possible according to the current location value.

Reimplemented in elementa::base::SerChLocText.

◆ dec() [2/2]

virtual void elementa::base::SerChLoc::dec	(	const char *	t,
		SerChSize	n
	)

virtual

Decrement the location after un-reading/un-writing a block T of N chars.

Throw if that decrement is not possible according to the current location value.

Reimplemented in elementa::base::SerChLocText.

◆ operator==()

virtual bool elementa::base::SerChLoc::operator== ( const SerChLoc & o ) const

inlinevirtual

Equality.

Reimplemented in elementa::base::SerChLocText.

Definition at line 848 of file basics.h.

◆ operator!=()

virtual bool elementa::base::SerChLoc::operator!= ( const SerChLoc & o ) const

inlinevirtual

Unequality.

Reimplemented in elementa::base::SerChLocText.

Definition at line 852 of file basics.h.

◆ to_string()

virtual std::string elementa::base::SerChLoc::to_string ( bool compact = false ) const

virtualnoexcept

Convert the location to a string.

If COMPACT == TRUE, return an equal or shorter string.

Reimplemented in elementa::base::SerChLocText.

◆ emptyClone()

virtual Clonable * elementa::patterns::Clonable::emptyClone ( void ) const

inlinevirtualinherited

Derived classes can override this to provide a clone that is "empty".

"Emptiness" here means that the clone is not actually a clone of the derived object, but a new object of the same class of the derived object, without no content (i.e., right after creation).

Reimplemented in elementa::adts::graphs::SparseGraph< Vertex, Edge >.

Definition at line 93 of file clonable.h.

References ELE_CODE_UNIMPLEMENTED.

◆ elementa::base::SerChLocText

class elementa::base::SerChLocText

A location into a text channel consisting of a row and a column.

Note: - Both coordinates begin in 1, not in 0, but the linear position begins in 0.; - Additional info about each row is stored as the location moves; that
info increases in memory linearly with the number of rows.

See also: SerChLoc.

Definition at line 897 of file basics.h.

Inheritance diagram for elementa::base::SerChLocText:

[legend]

Collaboration diagram for elementa::base::SerChLocText:

[legend]

Public Types
Types, consts, etc.
using	Ptr = std::shared_ptr< SerChLoc >
	Safe pointer for polymorphic behaviours. More...

Public Member Functions
	SerChLocText (char endofline='\n') noexcept
	Default constructor: location pointing to the 1st character of the text. More...

	SerChLocText (const SerChLocText &oth)
	Copy constructor: the stored value is cleared. More...

SerChLocText &	operator= (const SerChLocText &oth)
	Copy assignment: the stored value is cleared. More...

	SerChLocText (SerChLocText &&oth)
	Move constructor: the stored value of OTH is moved to this. More...

SerChLocText &	operator= (SerChLocText &&oth)
	Move assignment: the stored value of OTH is moved to this. More...

virtual	~SerChLocText (void)
	Destructor. More...

SerChSize	row (void) const noexcept
	Get current row. More...

SerChSize	column (void) const noexcept
	Get current column. More...

SerChLocText *	clone (void) const
	Clone the location. More...

void	reset (void) noexcept override
	Reset the location to the beginning. More...

void	inc (char c) override
	Increment the location after reading/writing char C. More...

void	inc (const char *t, SerChSize n) override
	Increment the location after reading/writing a block T of N chars. More...

void	dec (char c) override
	Decrement the location after un-reading/un-writing char C. More...

void	dec (const char *t, SerChSize n) override
	Decrement the location after un-reading/un-writing a block T of N chars. More...

bool	operator== (const SerChLocText &o)

bool	operator!= (const SerChLocText &o)

bool	operator== (const SerChLoc &o) const override
	Equality. More...

bool	operator!= (const SerChLoc &o) const override
	Unequality. More...

std::string	to_string (bool compact=false) const noexcept override
	Convert the location to a string. More...

virtual Clonable *	emptyClone (void) const
	Derived classes can override this to provide a clone that is "empty". More...

Getters
SerChSize	linear (void) const noexcept
	Get the current location. More...

Member Typedef Documentation

◆ Ptr

using elementa::base::SerChLoc::Ptr = std::shared_ptr<SerChLoc>

inherited

Safe pointer for polymorphic behaviours.

Definition at line 776 of file basics.h.

Constructor & Destructor Documentation

◆ SerChLocText() [1/3]

elementa::base::SerChLocText::SerChLocText ( char endofline = '\n' )

inlinenoexcept

Default constructor: location pointing to the 1st character of the text.

Definition at line 902 of file basics.h.

◆ SerChLocText() [2/3]

elementa::base::SerChLocText::SerChLocText ( const SerChLocText & oth )

inline

Copy constructor: the stored value is cleared.

Definition at line 906 of file basics.h.

◆ SerChLocText() [3/3]

elementa::base::SerChLocText::SerChLocText ( SerChLocText && oth )

inline

Move constructor: the stored value of OTH is moved to this.

Definition at line 914 of file basics.h.

◆ ~SerChLocText()

virtual elementa::base::SerChLocText::~SerChLocText ( void )

inlinevirtual

Destructor.

Definition at line 922 of file basics.h.

Member Function Documentation

◆ operator=() [1/2]

SerChLocText & elementa::base::SerChLocText::operator= ( const SerChLocText & oth )

inline

Copy assignment: the stored value is cleared.

Definition at line 910 of file basics.h.

◆ operator=() [2/2]

SerChLocText & elementa::base::SerChLocText::operator= ( SerChLocText && oth )

inline

Move assignment: the stored value of OTH is moved to this.

Definition at line 918 of file basics.h.

◆ row()

SerChSize elementa::base::SerChLocText::row ( void ) const

inlinenoexcept

Get current row.

Definition at line 925 of file basics.h.

◆ column()

SerChSize elementa::base::SerChLocText::column ( void ) const

inlinenoexcept

Get current column.

Definition at line 928 of file basics.h.

◆ clone()

SerChLocText * elementa::base::SerChLocText::clone ( void ) const

inlinevirtual

Clone the location.

Reimplemented from elementa::base::SerChLoc.

Definition at line 930 of file basics.h.

◆ reset()

void elementa::base::SerChLocText::reset ( void )

overridevirtualnoexcept

Reset the location to the beginning.

Reimplemented from elementa::base::SerChLoc.

◆ inc() [1/2]

void elementa::base::SerChLocText::inc ( char c )

overridevirtual

Increment the location after reading/writing char C.

Virtual for derived classes to enrich this behavior.

Reimplemented from elementa::base::SerChLoc.

◆ inc() [2/2]

void elementa::base::SerChLocText::inc	(	const char *	t,
		SerChSize	n
	)

overridevirtual

Increment the location after reading/writing a block T of N chars.

Virtual for derived classes to enrich this behavior.

Reimplemented from elementa::base::SerChLoc.

◆ dec() [1/2]

void elementa::base::SerChLocText::dec ( char c )

overridevirtual

Decrement the location after un-reading/un-writing char C.

Throw if that decrement is not possible according to the current location value.

Reimplemented from elementa::base::SerChLoc.

◆ dec() [2/2]

void elementa::base::SerChLocText::dec	(	const char *	t,
		SerChSize	n
	)

overridevirtual

Decrement the location after un-reading/un-writing a block T of N chars.

Throw if that decrement is not possible according to the current location value.

Reimplemented from elementa::base::SerChLoc.

◆ operator==() [1/2]

bool elementa::base::SerChLocText::operator== ( const SerChLocText & o )

inline

Definition at line 937 of file basics.h.

◆ operator!=() [1/2]

bool elementa::base::SerChLocText::operator!= ( const SerChLocText & o )

inline

Definition at line 939 of file basics.h.

◆ operator==() [2/2]

bool elementa::base::SerChLocText::operator== ( const SerChLoc & o ) const

inlineoverridevirtual

Equality.

Reimplemented from elementa::base::SerChLoc.

Definition at line 941 of file basics.h.

◆ operator!=() [2/2]

bool elementa::base::SerChLocText::operator!= ( const SerChLoc & o ) const

inlineoverridevirtual

Unequality.

Reimplemented from elementa::base::SerChLoc.

Definition at line 943 of file basics.h.

◆ to_string()

std::string elementa::base::SerChLocText::to_string ( bool compact = false ) const

overridevirtualnoexcept

Convert the location to a string.

If COMPACT == TRUE, return an equal or shorter string.

Reimplemented from elementa::base::SerChLoc.

◆ linear()

SerChSize elementa::base::SerChLoc::linear ( void ) const

inlinenoexceptinherited

Get the current location.

Definition at line 811 of file basics.h.

◆ emptyClone()

virtual Clonable * elementa::patterns::Clonable::emptyClone ( void ) const

inlinevirtualinherited

Derived classes can override this to provide a clone that is "empty".

"Emptiness" here means that the clone is not actually a clone of the derived object, but a new object of the same class of the derived object, without no content (i.e., right after creation).

Reimplemented in elementa::adts::graphs::SparseGraph< Vertex, Edge >.

Definition at line 93 of file clonable.h.

References ELE_CODE_UNIMPLEMENTED.

Typedef Documentation

◆ SerChSize

using elementa::base::SerChSize = typedef std::streamsize

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

Type of the size of any channel.

Note: - It must be the same as std::streamsize for compatibility of Elementa channels with existing STL streams.

Definition at line 178 of file basics.h.

◆ SerChDatum

using elementa::base::SerChDatum = typedef std::streambuf::int_type

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

Type that can hold either a char or eof.

Definition at line 181 of file basics.h.

◆ SerChCharTraits

using elementa::base::SerChCharTraits = typedef std::char_traits<char>

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

To have access to the methods of char_traits corresponding to these channs.

For instance: to_char_type, to_int_type to convert to/from char and SerChDatum.

Definition at line 186 of file basics.h.

◆ RootSerCh

using elementa::base::RootSerCh = typedef std::ios

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

Class that is at the root of any serial channel in Elementa.

This class is a base of any serial channel, but it does not provide any input/output methods, only the ones related to error management, thus it should not be used, in general, as a polymorphic representation of a serial channel.

Definition at line 195 of file basics.h.

◆ OutSerCh

using elementa::base::OutSerCh = typedef std::ostream

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

"Base class" that represents any output serial channel in Elementa.

The use of this enables polymorphic use of both Elementa serial channels and STL channels (within the Elementa minimized functionality) indistinctly.

The functionality of any OutSerCh must be the following, stolen from STL:

\code
OutSerCh & put(char c);  // declared non-virtual in ostream
// Write character c into the stream.
// Errors:
//  eofbit must be set if the channel is exhausted after this put.
//  failbit must be set if, at calling, the channel has eofbit or badbit, or
//      in other circumstances depending on the channel (e.g., when a file
//      channel cannot open the file in the case of STL fstreams).
//  badbit must be set if writing the char fails for any reason.
\endcode

\code
OutSerCh & write(const char* s, SerChSize n);  // non-virtual in ostream
// Inserts the first n characters of the array pointed by s into the stream.
// Errors:
//  eofbit must be set if the channel is exhausted after this write.
//  failbit must be set if, at calling, the channel has eofbit or badbit, or
//      in other circumstances depending on the channel (e.g., when a file
//      channel cannot open the file in the case of STL fstreams).
//  badbit must be set if writing any of the chars fails for any reason.
\endcode

\code
OutSerCh & flush(void);  // declared non-virtual in ostream
// If the channel has an internal buffer, this must write all of it to the
// associated device; otherwise it must do nothing.
// Errors:
//  failbit must be set if, at calling, the channel has eofbit or badbit.
//  badbit must be set if the synchronization operation failed.
\endcode

Note: - No thread-safeness is provided.; - There is no functionality to count the actually number of written items.; - OutSerCh derives (as std::ostream) from RootSerCh (std::ios).

Definition at line 247 of file basics.h.

◆ InSerCh

using elementa::base::InSerCh = typedef std::istream

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

"Base class" that represents any input serial channel in Elementa.

The use of this enables polymorphic use of both Elementa serial channels and STL channels (within the Elementa minimized functionality) indistinctly.

Its functionality must be the following, stolen from STL:

\code
SerChDatum get(void);  // non-virtually declared in istream
// Get a single character and return either it or kSerChEOF if the last
// char was already consumed previously. If a previous kSerChEOF was 
// returned, further kSerChEOF are returned indefinitely but the fail flag
// will be set in addition to the eof flag in the channel.

SerChDatum peek(void);  // non-virtually declared in istream
// Get a single character and return either it or kSerChEOF if the last
// char was already consumed previously. The difference with get() is that
// peek() does not consume the char itself (if any). If a previous kSerChEOF 
// was returned, further kSerChEOF are returned indefinitely but the fail 
// flag will be set in addition to the eof flag in the channel. 

InSerCh & get(char & c);  // non-virtually declared in istream
// Get a single character and store it into C, if available; if the channel
// has no more chars, set both eof and fail and does not update C.

// Errors in these methods:
//  eofbit is set AFTER a GET or a PEEK are done on an already exhausted ch.
//  failbit is set if the channel has eofbit or badbit already, or
//      in other circumstances depending on the channel (e.g., when a file
//      channel cannot open the file in the case of STL fstreams).
//  badbit is set if reading the char fails for other reasons.
\endcode

\code
InSerCh & read(char* s, SerChSize n); // non-virtually declared in istream
// Get up to N characters, storing them into S. Same behaviour as get(char&)
\endcode

\code
SerChSize gcount(void) const;  // non-virtually declared in istream
// Return the number of chars actually read in the last reading operation.
// No error is produced. Only the last operation is taken into account.
\endcode

\code
InSerCh & putback(char c);  // non-virtually declared in istream
// Tries to put back character C in the stream in order to be the next one
// to be read (not needed to be the same previously read). 
// NOTE: putback() is only intended to put back one char and never beyond
// the beginning of the channel (if any); other uses might be ok or fail, 
// depending on the channel.
// Errors:
//  eofbit is cleared after this call.
//  failbit is set if, at calling, the channel has eofbit or badbit, or
//      in other circumstances depending on the channel (e.g., when a file
//      channel cannot open the file in the case of STL fstreams).
//  badbit is set if the putback did not work.
\endcode

\code
InSerCh & unget(void); // non-virtually declared in istream
// The same as putback() but with using the last character that was got.

\code
int sync(void);  // non-virtually declared in istream
// If the channel has an internal buffer, this syncs the buffer with the
// device, which, for example, can consists in clearing all unread content
// of the buffer and discarding it (as it happens in std::cin.sync()).
// Return 0 if success (or if nothing has to be done) and -1 if error.
// Errors:
//  failbit is set if, at calling, the channel has eofbit or badbit.
//  badbit is set if the synchronization operation failed.
\endcode

Note: - No thread-safeness is provided.; - InSerCh derives (as std::istream) from RootSerCh (std::ios).

Definition at line 334 of file basics.h.

◆ InOutSerCh

using elementa::base::InOutSerCh = typedef std::iostream

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

"Base class" that represents any input + output serial channel in Elementa.

The use of this enables polymorphic use of both Elementa serial channels and STL channels (within the Elementa minimized functionality) indistinctly. Its functionality must be the merging of InSerCh and OutSerCh.

Note: - This class must derive from both InSerCh and OutSerCh.; - No thread-safeness is provided.; - InOutSerCh derives (as std::ostream) from both InSerCh (std::istream) and OutSerCh (std::ostream). Thus, you can use references/pointers to this class polimorphically both as InSerCh and OutSerCh.

Definition at line 356 of file basics.h.

Function Documentation

◆ serch_isgood()

void elementa::base::serch_isgood	(	RootSerCh &	serchconst,
		const std::string &	place = `""`,
		const RTTextWithEnum::Combination &	flags = `{RTTextWith::kAll_}`
	)

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

Throw an exception if the channel is not good; do nothing otherwise.

Throws a std::runtime_error.

Referenced by elementa::adts::graphs::Szer_GraphCompactText< Vertex, Edge >::ser(), elementa::adts::Szer_TreeText< Vertex, Edge >::ser(), elementa::base::Szer_Char::ser(), and elementa::base::Szer_NatBin< NatType >::ser().

◆ serch_iseofbutok()

bool elementa::base::serch_iseofbutok	(	RootSerCh &	serchconst,
		const std::string &	place = `""`,
		const RTTextWithEnum::Combination &	flags = `{RTTextWith::kAll_}`
	)

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

Return TRUE if the channel is eof() (maybe bad/fail); throw if !eof nor good.

Do nothing otherwise and return FALSE (the channel is good)

◆ serch_isexhausted()

bool elementa::base::serch_isexhausted	(	InSerCh &	serch,
		const std::string &	place = `""`,
		const RTTextWithEnum::Combination &	flags = `{RTTextWith::kAll_}`
	)

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

Return TRUE if it is eof or exhausted; then throw if the channel is bad/fail.

Otherwise do nothing and return FALSE. A channel is exhausted if is eof or after peeking the next char the eof flag is set.

Referenced by elementa::base::Szer_Char::deser(), and elementa::base::Szer_NatBin< NatType >::deser().

◆ serch_st_to_string() [1/2]

std::string elementa::base::serch_st_to_string ( std::ios_base::iostate st )

noexcept

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

Converts an io state into a string.

Since std::ios_base::iostate is usually an integral type, to avoid an implicit conversion to integer -and thus a call to a different to_string()- we have renamed this function.

Referenced by elementa::base::serch_filtered_pbackfail(), elementa::base::serch_filtered_uflow(), elementa::base::serch_filtered_underflow(), elementa::base::serch_st_to_string(), elementa::base::serch_transfer(), elementa::base::serch_transfer< SerChI_Memory, SerChIO_Memory >(), and elementa::base::serch_transfer< SerChIO_Memory, SerChIO_Memory >().

◆ serch_st_to_string() [2/2]

std::string elementa::base::serch_st_to_string ( RootSerCh & ch )

inlinenoexcept

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

Converts the state of a serial channel into a string.

Definition at line 515 of file basics.h.

References elementa::base::serch_st_to_string().

◆ serch_transfer() [1/2]

template<class SCOrg , class SCDest >

SerChSize elementa::base::serch_transfer	(	SCOrg &	chin,
		SCDest &	chout,
		SerChSize	count = `0`
	)

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

Write COUNT items read from channel CHIN into channel CHOUT.

If COUNT is 0 read until CHIN or CHOUT are in error or exhausted (do not throw if any error). Return the number of bytes transferred.

Return the actual number of items transferred (less than COUNT if any channel gets exhausted or, in general, not good).

Note: - More efficient overloads of this function can be defined for particular channels. This simply iterates over all elements until finished.; - It is defined as a template, even when that would not be necessary, for proper deduction of candidates to implement a call to the function: if any of the candidates would not be a template and others would, the non-template one would be preferred, according to the standard.

Definition at line 678 of file basics.h.

References ELE_CODE_TRACE_OFF, ELE_CODE_UNTRACE, elementa::base::serch_st_to_string(), and elementa::base::to_number().

Referenced by elementa::base::serch_transfer().

◆ serch_transfer() [2/2]

template<class SCOrg , class SCDest >

SerChSize elementa::base::serch_transfer	(	SCOrg &&	chin,
		SCDest &&	chout,
		SerChSize	count = `1`
	)

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

Version of serch_transfer for using rvalues (but without moving then).

No moves are involved; this is just for enabling calling the function with rvalues, and it just redirect the call to the appropriate version.

Note: - Using rvalues in serch_transfer is not directly possible since, as parameters, channels must be non-const, but rvalues, by default (if not using rvalue references), must go to const reference parameters.; - The other solution would have been to change the serch_transfer prototypes to have "const channel &" arguments and then const-cast inside the function those channels to "channel &", but I believe that is slightly more dangerous for the user, since it may think the function does not modify the channel. That modifier semantics is preserved with the current solution.

Definition at line 738 of file basics.h.

References ELE_CODE_TRACE_OFF, and elementa::base::serch_transfer().

Variable Documentation

◆ kSerChEOF

constexpr SerChDatum elementa::base::kSerChEOF = std::streambuf::traits_type::eof()

constexpr

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

Const that holds the eof value.

Definition at line 189 of file basics.h.

Referenced by elementa::base::serch_filtered_overflow(), elementa::base::serch_filtered_pbackfail(), elementa::base::serch_filtered_uflow(), and elementa::base::serch_filtered_underflow().

Description

Classes

Typedefs

Functions

Variables

Class Documentation

◆ elementa::base::is_InSerCh

Static Public Attributes

Member Data Documentation

◆ value

◆ elementa::base::is_In_InOut_SerCh

Static Public Attributes

Member Data Documentation

◆ value

◆ elementa::base::is_OutSerCh

Static Public Attributes

Member Data Documentation

◆ value

◆ elementa::base::is_Out_InOut_SerCh

Static Public Attributes

Member Data Documentation

◆ value

◆ elementa::base::is_InOutSerCh

Static Public Attributes

Member Data Documentation

◆ value

◆ elementa::base::is_SerCh

Static Public Attributes

Member Data Documentation

◆ value

◆ elementa::base::SerChError

Public Types

Public Member Functions

Member Typedef Documentation

◆ StdBase

Constructor & Destructor Documentation

◆ SerChError()

Member Function Documentation

◆ asERR()

◆ asEXC()

◆ what()

◆ explanation()

◆ context()

◆ elementa::base::SerChErr_Exhausted

Public Types

Public Member Functions

Member Typedef Documentation

◆ StdBase

Constructor & Destructor Documentation

◆ SerChErr_Exhausted()

Member Function Documentation

◆ asERR()

◆ asEXC()

◆ what()

◆ explanation()

◆ context()

◆ elementa::base::SerChErr_FewData

Public Types

Public Member Functions

Member Typedef Documentation

◆ StdBase

Constructor & Destructor Documentation

◆ SerChErr_FewData()

Member Function Documentation

◆ asERR()

◆ asEXC()

◆ what()

◆ explanation()

◆ context()

◆ elementa::base::SerChErr_TooManyData

Public Types

Public Member Functions

Member Typedef Documentation

◆ StdBase

Constructor & Destructor Documentation

◆ SerChErr_TooManyData()

Member Function Documentation

◆ asERR()

◆ asEXC()

◆ what()