Description

This module provides filters that can be attached to serial channels in order to extend their functionality by processing their inputs and/or outputs. A filter is an object that behaves as a channel; it is attached to another channel that produces or absorbes the data, while it only changes or monitorizes those data.

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

Date: 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 Filters for serial channels:

Classes
class	elementa::base::SerChIFilter< F >
	A filter for InSerCh. It filters their inputs after getting or putbacking'em. More...

class	elementa::base::SerChOFilter< F >
	A filter for output channels. It processes their outputs before writing them. More...

class	elementa::base::SerChIOFilter< FI, FO >
	A double filter for input/output channels. More...

class	elementa::base::SerChFilt_Loc
	A filter to keep a location on a channel. More...

class	elementa::base::SerChFilt_Demux
	A filter that serves data from multiple input channels. More...

class	elementa::base::SerChFilt_Divert
	A filter that sends a copy of the readings of an InSerCh to another channel. More...

Functions
	elementa::base::ELE_CLASS_ENUM (SerChBufOp, kUFlow, kUnderflow, kPBackFail, kOverflow)
	The different buffer operations that may produce the filter to be called.

template<class F >
SerChDatum	elementa::base::serch_filtered_uflow (InSerCh &wrappingchin_, InSerCh &chin_, F &filter_)
	Intended to implement uflow() in input or inout channels filtered by FILTER_. More...

template<class F >
SerChDatum	elementa::base::serch_filtered_underflow (InSerCh &wrappingchin_, InSerCh &chin_, F &filter_)
	Intended to implement underflow() in input/inout chnnels filtered by FILTER_. More...

template<class F >
SerChDatum	elementa::base::serch_filtered_pbackfail (InSerCh &wrappingchin_, InSerCh &chin_, F &filter_, SerChDatum c)
	Intended to implement pbackfail() in input/inout chnnels filtered by FILTER_. More...

template<class F >
SerChDatum	elementa::base::serch_filtered_overflow (OutSerCh &wrappingchout_, OutSerCh &chout_, F &filter_, SerChDatum c)
	Intended to implement overflow() in output/inout chnnels filtered by FILTER_. More...

template<class F >
SerChIFilter< F >	elementa::base::make_schfiltI (InSerCh &sch, const F &f)
	Creator of a SerChIFilter that deduces automatically the type of the filter. More...

template<class F >
SerChOFilter< F >	elementa::base::make_schfiltO (OutSerCh &sch, const F &f)
	Creator of a SerChOFilter that deduces automatically the type of the filter. More...

template<class FI , class FO >
SerChIOFilter< FI, FO >	elementa::base::make_schfiltIO (InOutSerCh &sch, const FI &f1, const FO &f2)
	Creator of a SerChIOFilter that deduces automatically the type of the filter. More...

Variables
std::function< SerChDatum(RootSerCh &, SerChBufOp, SerChDatum) >	elementa::base::serchfilt_null
	Change nothing in the flow of the channel.

std::function< SerChDatum(RootSerCh &, SerChBufOp, SerChDatum) >	elementa::base::serchfilt_toupper
	Change to uppercase everything flowing through the channel.

std::function< SerChDatum(RootSerCh &, SerChBufOp, SerChDatum) >	elementa::base::serchfilt_tolower
	Change to lowercase everything flowing through the channel.

Class Documentation

◆ elementa::base::SerChIFilter

class elementa::base::SerChIFilter

template<class F>
class elementa::base::SerChIFilter< F >

A filter for InSerCh. It filters their inputs after getting or putbacking'em.

Template Parameters

F	is the filter. It must be copy-constructible and callable with the prototype SerChDatum(InSerCh &, SerChBufOp, SerChDatum).

See also: make_schfiltI

Definition at line 124 of file filters.h.

Inheritance diagram for elementa::base::SerChIFilter< F >:

[legend]

Collaboration diagram for elementa::base::SerChIFilter< F >:

[legend]

Public Member Functions
	SerChIFilter (InSerCh &inch, const F &filter=F{})
	Constructor. More...

	SerChIFilter (SerChIFilter &&oth)
	Move constructor from another with same filters. Share same channel. More...

InSerCh &	channel (void) noexcept
	Getter for the referenced channel. More...

F &	filter (void) noexcept
	Getter for the internal filter function. More...

Constructor & Destructor Documentation

◆ SerChIFilter() [1/2]

template<class F >

elementa::base::SerChIFilter< F >::SerChIFilter	(	InSerCh &	inch,
		const F &	filter = `F{}`
	)

inline

Constructor.

The channel must outlive this object, since a reference is kept internally. The filter or bank of filters is copied internally.

Definition at line 131 of file filters.h.

◆ SerChIFilter() [2/2]

template<class F >

elementa::base::SerChIFilter< F >::SerChIFilter ( SerChIFilter< F > && oth )

inline

Move constructor from another with same filters. Share same channel.

Definition at line 139 of file filters.h.

Member Function Documentation

◆ channel()

template<class F >

InSerCh & elementa::base::SerChIFilter< F >::channel ( void )

inlinenoexcept

Getter for the referenced channel.

Definition at line 146 of file filters.h.

◆ filter()

template<class F >

F & elementa::base::SerChIFilter< F >::filter ( void )

inlinenoexcept

Getter for the internal filter function.

Definition at line 149 of file filters.h.

Referenced by elementa::base::SerChFilt_Loc::get_loc().

◆ elementa::base::SerChOFilter

class elementa::base::SerChOFilter

template<class F>
class elementa::base::SerChOFilter< F >

A filter for output channels. It processes their outputs before writing them.

Template Parameters

F	is the filter. It must be copy-constructible and callable with the prototype SerChDatum(InSerCh &, SerChBufOp, SerChDatum).

See also: make_schfiltO

Definition at line 204 of file filters.h.

Inheritance diagram for elementa::base::SerChOFilter< F >:

[legend]

Collaboration diagram for elementa::base::SerChOFilter< F >:

[legend]

Public Member Functions
	SerChOFilter (OutSerCh &chout, const F &filter=F{})
	Constructor. More...

	SerChOFilter (SerChOFilter &&oth)
	Move constructor from another with same filters. Share same channel. More...

OutSerCh &	channel (void) noexcept
	Getter for the referenced channel. More...

F &	filter (void) noexcept
	Getter for the internal filter function. More...

Constructor & Destructor Documentation

◆ SerChOFilter() [1/2]

template<class F >

elementa::base::SerChOFilter< F >::SerChOFilter	(	OutSerCh &	chout,
		const F &	filter = `F{}`
	)

inline

Constructor.

The channel must outlive this object, since a reference is kept internally. The filter or bank of filters is copied internally.

Definition at line 211 of file filters.h.

◆ SerChOFilter() [2/2]

template<class F >

elementa::base::SerChOFilter< F >::SerChOFilter ( SerChOFilter< F > && oth )

inline

Move constructor from another with same filters. Share same channel.

Definition at line 221 of file filters.h.

Member Function Documentation

◆ channel()

template<class F >

OutSerCh & elementa::base::SerChOFilter< F >::channel ( void )

inlinenoexcept

Getter for the referenced channel.

Definition at line 228 of file filters.h.

◆ filter()

template<class F >

F & elementa::base::SerChOFilter< F >::filter ( void )

inlinenoexcept

Getter for the internal filter function.

Definition at line 231 of file filters.h.

Referenced by elementa::base::SerChFilt_Loc::get_loc().

◆ elementa::base::SerChIOFilter

class elementa::base::SerChIOFilter

template<class FI, class FO>
class elementa::base::SerChIOFilter< FI, FO >

A double filter for input/output channels.

Template Parameters

FI,FO are the filters. They must be copy-constructible and
callable with the prototype SerChDatum(InSerCh &, SerChBufOp, SerChDatum).

See also: make_schfiltIO

Definition at line 282 of file filters.h.

Inheritance diagram for elementa::base::SerChIOFilter< FI, FO >:

[legend]

Collaboration diagram for elementa::base::SerChIOFilter< FI, FO >:

[legend]

Public Member Functions
	SerChIOFilter (InOutSerCh &chinout, const FI &filterin=FI{}, const FO &filterout=FO{})
	Constructor More...

	SerChIOFilter (SerChIOFilter &&oth)
	Move constructor from another with same filters. Share same channel. More...

OutSerCh &	channel (void) noexcept
	Getter for the referenced channel. More...

FI &	filterIn (void) noexcept
	Getter for the internal input filter function. More...

FO &	filterOut (void) noexcept
	Getter for the internal output filter function. More...

Constructor & Destructor Documentation

◆ SerChIOFilter() [1/2]

template<class FI , class FO >

elementa::base::SerChIOFilter< FI, FO >::SerChIOFilter	(	InOutSerCh &	chinout,
		const FI &	filterin = `FI{}`,
		const FO &	filterout = `FO{}`
	)

inline

Constructor

The channel must outlive this object, since a reference is kept internally. The filters or banks of filters are copied internally.

Definition at line 289 of file filters.h.

◆ SerChIOFilter() [2/2]

template<class FI , class FO >

elementa::base::SerChIOFilter< FI, FO >::SerChIOFilter ( SerChIOFilter< FI, FO > && oth )

inline

Move constructor from another with same filters. Share same channel.

Definition at line 300 of file filters.h.

Member Function Documentation

◆ channel()

template<class FI , class FO >

OutSerCh & elementa::base::SerChIOFilter< FI, FO >::channel ( void )

inlinenoexcept

Getter for the referenced channel.

Definition at line 309 of file filters.h.

◆ filterIn()

template<class FI , class FO >

FI & elementa::base::SerChIOFilter< FI, FO >::filterIn ( void )

inlinenoexcept

Getter for the internal input filter function.

Definition at line 312 of file filters.h.

◆ filterOut()

template<class FI , class FO >

FO & elementa::base::SerChIOFilter< FI, FO >::filterOut ( void )

inlinenoexcept

Getter for the internal output filter function.

Definition at line 315 of file filters.h.

◆ elementa::base::SerChFilt_Loc

class elementa::base::SerChFilt_Loc

A filter to keep a location on a channel.

The specific kind of location class to use is in the constructor.

Definition at line 435 of file filters.h.

Collaboration diagram for elementa::base::SerChFilt_Loc:

[legend]

Static Public Member Functions
template<class L >
static SerChIFilter< SerChFilt_Loc >	make_filtch (InSerCh &isch)
	Return a SerChIFilter that uses a new location object of class L. More...

template<class L >
static SerChOFilter< SerChFilt_Loc >	make_filtch (OutSerCh &osch)
	Return a SerChOFilter that uses a new location object of class L. More...

template<class L >
static L &	get_loc (SerChIFilter< SerChFilt_Loc > &fch)
	Get the downcast location object of class L from the filtered channel. More...

template<class L >
static L &	get_loc (SerChOFilter< SerChFilt_Loc > &fch)
	Get the downcast location object of class L from the filtered channel. More...

Public Attributes
SerChLoc::Ptr	ploc
	Location object, updated by the () operator. More...

Public Member Functions
	SerChFilt_Loc (const SerChLoc &loc=SerChLocText{})
	Default constructor. By default, SerChLocText is used for locations. More...

	SerChFilt_Loc (const SerChLoc::Ptr &pl)
	Constructor from an already existing location object. More...

SerChDatum	operator() (RootSerCh &, SerChBufOp op, SerChDatum c)

Constructor & Destructor Documentation

◆ SerChFilt_Loc() [1/2]

elementa::base::SerChFilt_Loc::SerChFilt_Loc ( const SerChLoc & loc = SerChLocText{} )

inline

Default constructor. By default, SerChLocText is used for locations.

A clone of the given location object is stored here.

Definition at line 465 of file filters.h.

◆ SerChFilt_Loc() [2/2]

elementa::base::SerChFilt_Loc::SerChFilt_Loc ( const SerChLoc::Ptr & pl )

inline

Constructor from an already existing location object.

For the case you need to re-use some location.

Definition at line 469 of file filters.h.

Member Function Documentation

◆ make_filtch() [1/2]

template<class L >

static SerChIFilter< SerChFilt_Loc > elementa::base::SerChFilt_Loc::make_filtch ( InSerCh & isch )

inlinestatic

Return a SerChIFilter that uses a new location object of class L.

Definition at line 441 of file filters.h.

◆ make_filtch() [2/2]

template<class L >

static SerChOFilter< SerChFilt_Loc > elementa::base::SerChFilt_Loc::make_filtch ( OutSerCh & osch )

inlinestatic

Return a SerChOFilter that uses a new location object of class L.

Definition at line 446 of file filters.h.

◆ get_loc() [1/2]

template<class L >

static L & elementa::base::SerChFilt_Loc::get_loc ( SerChIFilter< SerChFilt_Loc > & fch )

inlinestatic

Get the downcast location object of class L from the filtered channel.

Definition at line 451 of file filters.h.

References elementa::base::SerChIFilter< F >::filter().

◆ get_loc() [2/2]

template<class L >

static L & elementa::base::SerChFilt_Loc::get_loc ( SerChOFilter< SerChFilt_Loc > & fch )

inlinestatic

Get the downcast location object of class L from the filtered channel.

Definition at line 456 of file filters.h.

References elementa::base::SerChOFilter< F >::filter().

Member Data Documentation

◆ ploc

SerChLoc::Ptr elementa::base::SerChFilt_Loc::ploc

Location object, updated by the () operator.

Definition at line 460 of file filters.h.

◆ elementa::base::SerChFilt_Demux

class elementa::base::SerChFilt_Demux

A filter that serves data from multiple input channels.

The user selects which channel is providing data at each time through a predicate function.

Note: When creating a filter out of this, you need to provide the SerChIFIlter object with an input channel. DO NOT USE any of the channels involved in the demuxing, since the SerChIFilter will use them first, and therefore when the filter is called the input channel has already been used, duplicating the action and possibly disturbing the status and the results. You can use an auxiliary SerChIConstant as a dummy channel for that purpose.

Definition at line 493 of file filters.h.

Public Types
using	SelPred = std::function< InSerCh &(void) >
	Prototype of the predicate used for selecting a channel from the list. More...

Public Member Functions
	SerChFilt_Demux (SelPred pred)
	Constructor: it admits the selection predicate. More...

SerChDatum	operator() (RootSerCh &, SerChBufOp op, SerChDatum c)
	Each time this method is called, the predicate function is called.

Member Typedef Documentation

◆ SelPred

using elementa::base::SerChFilt_Demux::SelPred = std::function< InSerCh & (void) >

Prototype of the predicate used for selecting a channel from the list.

The function will be called right before serving the next char required and must return the input channel from which the char must be got

Definition at line 500 of file filters.h.

Constructor & Destructor Documentation

◆ SerChFilt_Demux()

elementa::base::SerChFilt_Demux::SerChFilt_Demux ( SelPred pred )

inline

Constructor: it admits the selection predicate.

A copy of the selection function object will be kept inside this channel.

Definition at line 505 of file filters.h.

◆ elementa::base::SerChFilt_Divert

class elementa::base::SerChFilt_Divert

A filter that sends a copy of the readings of an InSerCh to another channel.

The channel is used normally as an input channel, but, in addition to serve chars to the user, sends those very chars to another output channel. If the user calls peek() or pbackfail(), the result will not be diverted to the other output channel; that only happens if the user calls get() or read().

Definition at line 529 of file filters.h.

Public Member Functions
	SerChFilt_Divert (OutSerCh &div)
	Constructor. More...

SerChDatum	operator() (RootSerCh &, SerChBufOp op, SerChDatum c)

Constructor & Destructor Documentation

◆ SerChFilt_Divert()

elementa::base::SerChFilt_Divert::SerChFilt_Divert ( OutSerCh & div )

inline

Constructor.

The divert channel must outlive this channel.

Definition at line 535 of file filters.h.

Function Documentation

◆ serch_filtered_uflow()

template<class F >

SerChDatum elementa::base::serch_filtered_uflow	(	InSerCh &	wrappingchin_,
		InSerCh &	chin_,
		F &	filter_
	)

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

Intended to implement uflow() in input or inout channels filtered by FILTER_.

This function is of private use of the SerCh*Filter classes, not intended to be called by the final user. It is here since it is needed by the template classes SerCh*Filter.

Template Parameters

F	must be a FunctionObject callable like SerChFilterProc.

Definition at line 563 of file filters.h.

References ELE_CODE_TRACE_OFF, elementa::base::kSerChEOF, elementa::base::serch_copy_st(), and elementa::base::serch_st_to_string().

◆ serch_filtered_underflow()

template<class F >

SerChDatum elementa::base::serch_filtered_underflow	(	InSerCh &	wrappingchin_,
		InSerCh &	chin_,
		F &	filter_
	)

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

Intended to implement underflow() in input/inout chnnels filtered by FILTER_.

This function is of private use of the SerCh*Filter classes, not intended to be called by the final user. It is here since it is needed by the template classes SerCh*Filter.

Template Parameters

F	must be a FunctionObject callable like SerChFilterProc.

Definition at line 586 of file filters.h.

References ELE_CODE_TRACE_OFF, elementa::base::kSerChEOF, elementa::base::serch_copy_st(), and elementa::base::serch_st_to_string().

◆ serch_filtered_pbackfail()

template<class F >

SerChDatum elementa::base::serch_filtered_pbackfail	(	InSerCh &	wrappingchin_,
		InSerCh &	chin_,
		F &	filter_,
		SerChDatum	c
	)

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

Intended to implement pbackfail() in input/inout chnnels filtered by FILTER_.

This function is of private use of the SerCh*Filter classes, not intended to be called by the final user. It is here since it is needed by the template classes SerCh*Filter.

Template Parameters

F	must be a FunctionObject callable like SerChFilterProc.

Definition at line 609 of file filters.h.

References ELE_CODE_TRACE_OFF, elementa::base::kSerChEOF, elementa::base::serch_copy_st(), and elementa::base::serch_st_to_string().

◆ serch_filtered_overflow()

template<class F >

SerChDatum elementa::base::serch_filtered_overflow	(	OutSerCh &	wrappingchout_,
		OutSerCh &	chout_,
		F &	filter_,
		SerChDatum	c
	)

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

Intended to implement overflow() in output/inout chnnels filtered by FILTER_.

This function is of private use of the SerCh*Filter classes, not intended to be called by the final user. It is here since it is needed by the template classes SerCh*Filter.

Template Parameters

F	must be a FunctionObject callable like SerChFilterProc.

Definition at line 641 of file filters.h.

References elementa::base::kSerChEOF, and elementa::base::serch_copy_st().

◆ make_schfiltI()

template<class F >

SerChIFilter< F > elementa::base::make_schfiltI	(	InSerCh &	sch,
		const F &	f
	)

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

Creator of a SerChIFilter that deduces automatically the type of the filter.

Definition at line 384 of file filters.h.

◆ make_schfiltO()

template<class F >

SerChOFilter< F > elementa::base::make_schfiltO	(	OutSerCh &	sch,
		const F &	f
	)

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

Creator of a SerChOFilter that deduces automatically the type of the filter.

Definition at line 389 of file filters.h.

◆ make_schfiltIO()

template<class FI , class FO >

SerChIOFilter< FI, FO > elementa::base::make_schfiltIO	(	InOutSerCh &	sch,
		const FI &	f1,
		const FO &	f2
	)

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

Creator of a SerChIOFilter that deduces automatically the type of the filter.

Definition at line 394 of file filters.h.

Description

Classes

Functions

Variables

Class Documentation

◆ elementa::base::SerChIFilter

Public Member Functions

Constructor & Destructor Documentation

◆ SerChIFilter() [1/2]

◆ SerChIFilter() [2/2]

Member Function Documentation

◆ channel()

◆ filter()

◆ elementa::base::SerChOFilter

Public Member Functions

Constructor & Destructor Documentation

◆ SerChOFilter() [1/2]

◆ SerChOFilter() [2/2]

Member Function Documentation

◆ channel()

◆ filter()

◆ elementa::base::SerChIOFilter

Public Member Functions

Constructor & Destructor Documentation

◆ SerChIOFilter() [1/2]

◆ SerChIOFilter() [2/2]

Member Function Documentation

◆ channel()

◆ filterIn()

◆ filterOut()

◆ elementa::base::SerChFilt_Loc

Static Public Member Functions

Public Attributes

Public Member Functions

Constructor & Destructor Documentation

◆ SerChFilt_Loc() [1/2]

◆ SerChFilt_Loc() [2/2]

Member Function Documentation

◆ make_filtch() [1/2]

◆ make_filtch() [2/2]

◆ get_loc() [1/2]

◆ get_loc() [2/2]

Member Data Documentation

◆ ploc

◆ elementa::base::SerChFilt_Demux

Public Types

Public Member Functions

Member Typedef Documentation

◆ SelPred

Constructor & Destructor Documentation

◆ SerChFilt_Demux()

◆ elementa::base::SerChFilt_Divert

Public Member Functions

Constructor & Destructor Documentation

◆ SerChFilt_Divert()

Function Documentation

◆ serch_filtered_uflow()

◆ serch_filtered_underflow()

◆ serch_filtered_pbackfail()

◆ serch_filtered_overflow()

◆ make_schfiltI()

◆ make_schfiltO()

◆ make_schfiltIO()