tuple-helper.hpp File Reference

Go to the source code of this file.

Description

Metaprogramming with tuples-of-types and the std::tuple record.

The metaprogramming part of this header complements typelist.hpp and allows some additional manipulations on type sequences, especially to integrate with the Tuples provided by the standard library.

Warning

the metaprogramming part of Lumiera to deal with type sequences is in a state of transition, since C++11 now offers direct language support for processing of flexible template parameter sequences ("parameter packs"). It is planned to regroup and simplify our homemade type sequence framework to rely on variadic templates and integrate better with std::tuple. It is clear that we will retain some parts of our own framework, since programming with Loki-style typelists is way more obvious and straight forward than handling of template parameter packs, since the latter can only be rebound through pattern matching.

Todo:

transition lib::meta::Types to variadic parameters /////////////////////////////////TICKET #987

See also

control::CommandDef usage example

TupleHelper_test

typelist.hpp

function.hpp

generator.hpp

Definition in file tuple-helper.hpp.

#include "lib/meta/typelist.hpp"
#include "lib/meta/typelist-util.hpp"
#include "lib/meta/typeseq-util.hpp"
#include "lib/meta/variadic-helper.hpp"
#include "lib/meta/util.hpp"
#include <tuple>
#include <utility>

Classes
class	BuildTupleAccessor< _X_, TYPES, TUP, i >
	Decorating a tuple type with auxiliary data access operations. More...
class	BuildTupleAccessor< _X_, Types<>, TUP, i >
struct	BuildTupleType< SEQ >
struct	BuildTupleType< Node< H, TAIL > >
struct	BuildTupleType< NullType >
struct	BuildTupleType< Types< TYPES... > >
	temporary workaround: strip trailing NullType entries prior to rebinding to the std::tuple type. More...
struct	BuildTupleType< TySeq< TYPES... > >
struct	ElementExtractor< SRC, TAR >
	Generic converter to somehow extract values from the "source" type to fill and initialise a tuple of given target type. More...
struct	is_Tuple< T >
	trait to detect tuple types More...
struct	is_Tuple< const std::tuple< TYPES... > >
struct	is_Tuple< std::tuple< TYPES... > >
struct	RebindTupleTypes< TYPES >
	temporary workaround: match and rebind the type sequence from a tuple More...
struct	RebindTupleTypes< std::tuple< TYPES... > >
struct	StringConv< std::tuple< TYPES... > >
struct	TupleConstructor< TYPES, _ElmMapper_ >
	Extensible Adapter to construct a distinct tuple from some arbitrary source type. More...
struct	TupleElementDisplayer< TY, BASE, TUP, idx >
	Helper to dump tuple contents. More...
struct	TupleElementDisplayer< NullType, TUP, TUP, n >

Typedefs
template<class TUP >
using	disable_if_Tuple = lib::meta::disable_if< lib::meta::is_Tuple< std::remove_reference_t< TUP > >>
template<class TUP >
using	enable_if_Tuple = lib::meta::enable_if< lib::meta::is_Tuple< std::remove_reference_t< TUP > >>
template<class SRC , class TAR , size_t i>
using	ExtractArg = typename ElementExtractor< SRC, TAR >::template Access< i >
template<typename TYPES >
using	Tuple = typename BuildTupleType< TYPES >::Type
	Build a std::tuple from types given as type sequence. More...

Functions
template<typename TYPES , class SRC >
Tuple< TYPES >	buildTuple (SRC values)
	convenience shortcut to build a tuple from some suitable source data. More...
template<typename... TYPES>
std::string	dump (std::tuple< TYPES... > const &tuple)
	convenience function to dump a given tuple's contents. More...
template<class TUP , class FUN , typename = enable_if_Tuple<TUP>>
void	forEach (TUP &&tuple, FUN fun)
	Tuple iteration: perform some arbitrary operation on each element of a tuple. More...
template<class TUP , class FUN , typename = enable_if_Tuple<TUP>>
auto	mapEach (TUP &&tuple, FUN fun)
	Apply some arbitrary function onto all elements of a tuple. More...
template<typename TY >
std::string	toString (TY const &val) noexcept
	get some string representation of any object, reliably. More...

Namespaces
	lib
	Implementation namespace for support and library code.

Typedef Documentation

Tuple

using Tuple = typename BuildTupleType<TYPES>::Type

Build a std::tuple from types given as type sequence.

Remarks

for Lumiera, we deliberately use a dedicated template Types to mark a type sequence of types as such. This allows to pass such a sequence as first-class citizen. The standard library often (ab)uses the std::tuple for this purpose, which is an understandable, yet inferior design choice. We should always favour dedicated types over clever re-use of existing types.

Examples:

/Werk/devel/lumi/src/lib/hetero-data.hpp.

Definition at line 186 of file tuple-helper.hpp.

---

Class Documentation

lib::meta::anonymous_namespace{tuple-helper.hpp}::BuildTupleType< Node< H, TAIL > >

struct lib::meta::anonymous_namespace{tuple-helper.hpp}::BuildTupleType< Node< H, TAIL > >

Class Members
typedef typename Types< Node < H, TAIL > >::Seq	Seq
typedef typename BuildTupleType< Seq >::Type	Type

Collaboration diagram for BuildTupleType< Node< H, TAIL > >:

lib::meta::anonymous_namespace{tuple-helper.hpp}::BuildTupleType< NullType >

struct lib::meta::anonymous_namespace{tuple-helper.hpp}::BuildTupleType< NullType >

Class Members
typedef typename BuildTupleType< Types <> >::Type	Type

Collaboration diagram for BuildTupleType< NullType >:

lib::meta::anonymous_namespace{tuple-helper.hpp}::BuildTupleType< Types< TYPES... > >

struct lib::meta::anonymous_namespace{tuple-helper.hpp}::BuildTupleType< Types< TYPES... > >

Class Members
	VariadicSeq
typedef typename BuildTupleType< VariadicSeq > ::Type	Type

Collaboration diagram for BuildTupleType< Types< TYPES... > >:

lib::meta::anonymous_namespace{tuple-helper.hpp}::BuildTupleType< TySeq< TYPES... > >

struct lib::meta::anonymous_namespace{tuple-helper.hpp}::BuildTupleType< TySeq< TYPES... > >

Class Members
	Type

Collaboration diagram for BuildTupleType< TySeq< TYPES... > >:

Function Documentation

toString()

std::string toString ( TY const &  val )

inlinenoexcept

get some string representation of any object, reliably.

A custom string conversion operator is invoked, if applicable, while all lexically convertible types (numbers etc) are treated by boost::lexical_cast. For double or float values, hard wired rounding to a fixed number of digits will be performed, to yield a predictable display of printed unit-test results.

Remarks

while the actual parameter is passed by const-ref, cv-qualifiactions and references are stripped from the type

Note

Deliberately there is no magic detection/support for pointers. This function must not be overloaded (to avoid ambiguities in more elaborate template instantiations).

Remarks

Since 10/2023 an attempt was made to solve this problem down in StringConf<TY>, yet this solution might be brittle. If you want pointers to be indicated (with address), consider using util::showPtr explicitly.

Examples:

/Werk/devel/lumi/src/lib/test/test-helper.hpp.

Definition at line 191 of file format-obj.hpp.

References util::toString().

Referenced by FormatHelper_test::check2String(), and util::toString().

Here is the call graph for this function:

Here is the caller graph for this function:

forEach()

void lib::meta::forEach	(	TUP &&	tuple,
		FUN	fun
	)

Tuple iteration: perform some arbitrary operation on each element of a tuple.

Note

the given functor must be generic, since each position of the tuple may hold a data element of different type.

Remarks

credits to David Vandevoorde (member of C++ committee) for using std::apply to unpack the tuple's contents into an argument pack and then employ a fold expression with the comma operator.

Definition at line 98 of file tuple-helper.hpp.

References lib::meta::forEach().

Referenced by lib::meta::forEach().

Here is the call graph for this function:

Here is the caller graph for this function:

mapEach()

auto lib::meta::mapEach	(	TUP &&	tuple,
		FUN	fun
	)

Apply some arbitrary function onto all elements of a tuple.

Returns

a new tuple constructed from the results of this function

Note

the functor must be generic and able to work with all element types

Warning

pay attention to references; the function can take arguments by-ref and manipulate them (side-effect), and it may return references, which will be placed as such into the result tuple; furthermore, the argument tuple can also be taken as reference...

Remarks

The tuple constructor invocation is preceded by a regular argument evaluation, which has unspecified evaluation order (even in C++17); no assumptions can be made regarding the order the functor will see the source tuple elements. Notably this differs from #forEach, where a fold-expression with comma-operator is used, which is guaranteed to evaluate from left to right.

Definition at line 123 of file tuple-helper.hpp.

References lib::meta::mapEach().

Referenced by lib::meta::mapEach().

Here is the call graph for this function:

Here is the caller graph for this function:

buildTuple()

Tuple<TYPES> lib::meta::buildTuple

(

SRC

values

)

convenience shortcut to build a tuple from some suitable source data.

For this to work, there needs to be a partial specialisation for (ElementExtractor) to deal with the concrete source type given.

Note

we provide such a specialisation for Record<GenNode>, which allows us to fill an (argument) tuple from a sequence of generic data values, with run-time type compatibility check.

See also

tuple-record-init.hpp

Definition at line 286 of file tuple-helper.hpp.

References lib::meta::buildTuple().

Referenced by lib::meta::buildTuple().

Here is the call graph for this function:

Here is the caller graph for this function:

dump()

std::string lib::meta::dump ( std::tuple< TYPES... > const &  tuple )

inline

convenience function to dump a given tuple's contents.

Using the BuildTupleAccessor, we layer a stack of Instantiations of the TupleElementDisplayer temporarily on top of the given tuple, just to invoke a recursive call chain through these layers and get a string representation of each element in the tuple.

Definition at line 409 of file tuple-helper.hpp.

References lib::meta::dump().

Referenced by lib::meta::dump(), and LateBindInstance_test::verify_cornerCases().

Here is the call graph for this function:

Here is the caller graph for this function: