#include "lib/several-builder.hpp"

Description

template<class I, class E = I, template< class, class > class POL = allo::HeapOwn>
class lib::SeveralBuilder< I, E, POL >

Builder to create and populate a lib::Several.

Content elements can be of the interface type I, or the default element type E. When possible, even elements of an ad-hoc given, unrelated type can be used. The expected standard usage is to place elements of a subclass of I — but in fact the only limitation is that later, when using the created lib::Several, all content will be accessed through a (forced) cast to type I. Data (and metadata) will be placed into an extent, which lives at a different location, as managed by an Allocator (With default configuration, data is heap allocated). The expansion behaviour is similar to std::vector, meaning that the buffer grows with exponential stepping. However, other than std::vector, even non-copyable objects can be handled, using reserve to prepare a suitable allocation.

Warning: due to the flexibility and possible low-level usage patterns, consistency checks may throw at runtime, when attempting to add an unsuitable element.

Definition at line 395 of file several-builder.hpp.

Public Member Functions
	SeveralBuilder ()=default

template<typename... ARGS, typename = meta::enable_if<std::is_constructible<Policy,ARGS&&...>>>
	SeveralBuilder (ARGS &&...alloInit)
	start Several build using a custom allocator

Policy &	policyConnect ()
	expose policy to configure other ServeralBuilder

template<template< typename > class ALO = std::void_t, typename... ARGS>
auto	withAllocator (ARGS &&...args)
	cross-builder to use a custom allocator for the lib::Several container

template<typename TY = E>
SeveralBuilder &&	reserve (size_t cntElm=1, size_t elmSiz=reqSiz< TY >())
	ensure up-front that a desired capacity is allocated

SeveralBuilder &&	shrinkFit ()
	discard excess reserve capacity.

template<typename VAL , typename... VALS>
SeveralBuilder &&	append (VAL &&val, VALS &&...vals)
	append copies of one or several arbitrary elements

template<class IT >
SeveralBuilder &&	appendAll (IT &&data)
	append a copy of all values exposed through an iterator

template<class X >
SeveralBuilder &&	appendAll (std::initializer_list< X > ili)

template<class SEQ >
SeveralBuilder &&	moveAll (SEQ &dataSrc)
	consume all values exposed through an iterator by moving into the builder

template<typename... ARGS>
SeveralBuilder &&	fillElm (size_t cntNew, ARGS &&...args)
	emplace a number of elements of the defined element type E

template<class TY , typename... ARGS>
SeveralBuilder &&	emplace (ARGS &&...args)
	create a new content element within the managed storage

Several< I >	build ()
	Terminal Builder: complete and lock the collection contents.

size_t	size () const

bool	empty () const

size_t	capacity () const

size_t	capReserve () const

I &	operator[] (size_t idx)
	allow to peek into data emplaced thus far...

Private Types
enum	DestructionMethod { UNKNOWN , TRIVIAL , ELEMENT , VIRTUAL }

using	Coll = Several< I >

using	Policy = POL< I, E >

using	Bucket = several::ArrayBucket< I >

using	Deleter = Bucket::Deleter

Private Types inherited from Several< I >
using	iterator = lib::IndexIter< Several >

using	const_iterator = lib::IndexIter< const Several >

using	value_type = meta::RefTraits< I >::Value

using	reference = meta::RefTraits< I >::Reference

using	const_reference = value_type const &

using	Bucket = several::ArrayBucket< I > *

Private Member Functions
template<class IT >
void	emplaceCopy (IT &dataSrc)

template<class IT >
void	emplaceMove (IT &dataSrc)

template<class TY , typename... ARGS>
void	emplaceNewElm (ARGS &&...args)

template<class TY >
void	ensureDeleter ()
	ensure clean-up can be handled properly.

template<class TY >
void	ensureElementCapacity (size_t requiredSiz=reqSiz< TY >())
	ensure sufficient element capacity or the ability to adapt element spread

template<class TY >
void	ensureStorageCapacity (size_t requiredSiz=reqSiz< TY >(), size_t newElms=1)
	ensure sufficient storage reserve for newElms or verify the ability to re-allocate

void	adjustStorage (size_t cnt, size_t spread)
	possibly grow storage and re-arrange elements to accommodate desired capacity

void	fitStorage ()

void	adjustSpread (size_t newSpread)
	move existing data to accommodate spread

void	shiftStorage (size_t idx, size_t oldSpread, size_t newSpread)

template<typename TY >
Deleter	selectDestructor ()
	Select a suitable method for invoking the element destructors and build a λ-object to be stored as deleter function alongside with the data; this includes a copy of the embedded allocator, which in many cases is a monostate empty base class.

template<typename TY >
void	__ensureMark (DestructionMethod requiredKind)

template<typename TY >
void	probeMoveCapability ()
	mark that we're about to accept an otherwise unknown type, which can not be trivially moved.

bool	canWildMove ()

bool	canDynGrow ()

Private Member Functions inherited from Several< I >
	Several ()=default
	usually to be created through SeveralBuilder

	~Several () noexcept

	Several (Several &&rr)
	Move-Assignment allowed...

Several &	operator= (Several &&rr)

	operator std::string () const
	generic string rendering delegated to `util::toString(elm)`

size_t	size () const

bool	empty () const

I &	operator[] (size_t idx)

I const &	operator[] (size_t idx) const

I &	front ()

I &	back ()

iterator	begin ()

iterator	end ()

const_iterator	begin () const

const_iterator	end () const

size_t	spread () const

size_t	storageBuffSiz () const

bool	hasReserve (size_t requiredSize, size_t newElms=1) const

Private Member Functions inherited from MoveOnly
	~MoveOnly ()=default

	MoveOnly ()=default

	MoveOnly (MoveOnly &&)=default

	MoveOnly (MoveOnly const &)=delete

MoveOnly &	operator= (MoveOnly &&)=delete

MoveOnly &	operator= (MoveOnly const &)=delete

Static Private Member Functions
static Literal	render (DestructionMethod m)

Private Attributes
DestructionMethod	destructor {UNKNOWN}

bool	lock_move {false}

Private Attributes inherited from Several< I >
Bucket	data_ {nullptr}

Constructor & Destructor Documentation

◆ SeveralBuilder() [1/2]

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

SeveralBuilder ( )

default

◆ SeveralBuilder() [2/2]

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<typename... ARGS, typename = meta::enable_if<std::is_constructible<Policy,ARGS&&...>>>

SeveralBuilder ( ARGS &&... alloInit )

inline

start Several build using a custom allocator

Definition at line 411 of file several-builder.hpp.

Member Typedef Documentation

◆ Coll

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

using Coll = Several

private

Definition at line 400 of file several-builder.hpp.

◆ Policy

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

using Policy = POL<I,E>

private

Definition at line 401 of file several-builder.hpp.

◆ Bucket

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

using Bucket = several::ArrayBucket

private

Definition at line 403 of file several-builder.hpp.

◆ Deleter

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

using Deleter = Bucket::Deleter

private

Definition at line 404 of file several-builder.hpp.

Member Enumeration Documentation

◆ DestructionMethod

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

enum DestructionMethod

private

Enumerator
UNKNOWN
TRIVIAL
ELEMENT
VIRTUAL

Definition at line 704 of file several-builder.hpp.

Member Function Documentation

◆ policyConnect()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

Policy & policyConnect ( )

inline

expose policy to configure other ServeralBuilder

Definition at line 417 of file several-builder.hpp.

Referenced by WeavingBuilder< POL, PROT >::build().

Here is the caller graph for this function:

◆ withAllocator()

template<class I , class E , template< class, class > class POL>

template<template< typename > class ALO, typename... ARGS>

auto withAllocator ( ARGS &&... args )

inline

cross-builder to use a custom allocator for the lib::Several container

Remarks: this builder notation configures the new lib::Several container to perform memory management through a standard conformant allocation adapter. Moreover, optionally the behaviour can be configured through an extension point lib::allo::SetupSeveral, for which the custom allocator may provide an explicit template specialisation.

Template Parameters

ALO	a C++ standard conformant allocator template, which can be instantiated for creating various data elements. Notably, this will be instantiated as `ALO<std::byte>` to create and destroy the memory buffer for content data

Parameters

args	optional dependency wiring arguments, to be passed to the allocator

Returns: a new empty SeveralBuilder, configured to use the custom allocator.

See also: lib::AllocationCluster (which provides a custom adaptation); SeveralBuilder_test::check_CustomAllocator()

Definition at line 873 of file several-builder.hpp.

◆ reserve()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<typename TY = E>

SeveralBuilder && reserve	(	size_t	cntElm = `1`,
		size_t	elmSiz = `reqSiz<TY>()`
	)

inline

ensure up-front that a desired capacity is allocated

Definition at line 432 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::adjustStorage().

Referenced by SeveralBuilder_test::check_ErrorHandling(), and lib::makeSeveral().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ shrinkFit()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

SeveralBuilder && shrinkFit ( )

inline

discard excess reserve capacity.

Warning: typically this requires re-allocation and copy

Definition at line 447 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::capacity(), SeveralBuilder< I, E, POL >::fitStorage(), and SeveralBuilder< I, E, POL >::size().

Here is the call graph for this function:

◆ append()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<typename VAL , typename... VALS>

SeveralBuilder && append	(	VAL &&	val,
		VALS &&...	vals
	)

inline

append copies of one or several arbitrary elements

Definition at line 458 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::append().

Referenced by SeveralBuilder< I, E, POL >::append(), SeveralBuilder_test::check_Builder(), and SeveralBuilder_test::check_ErrorHandling().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ appendAll() [1/2]

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<class IT >

SeveralBuilder && appendAll ( IT && data )

inline

append a copy of all values exposed through an iterator

Definition at line 470 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::emplaceCopy(), and lib::explore().

Referenced by SeveralBuilder_test::check_Builder(), SeveralBuilder_test::check_ErrorHandling(), and lib::makeSeveral().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ appendAll() [2/2]

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<class X >

SeveralBuilder && appendAll ( std::initializer_list< X > ili )

inline

Definition at line 478 of file several-builder.hpp.

◆ moveAll()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<class SEQ >

SeveralBuilder && moveAll ( SEQ & dataSrc )

inline

consume all values exposed through an iterator by moving into the builder

Definition at line 489 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::emplaceMove(), and lib::explore().

Here is the call graph for this function:

◆ fillElm()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<typename... ARGS>

SeveralBuilder && fillElm	(	size_t	cntNew,
		ARGS &&...	args
	)

inline

emplace a number of elements of the defined element type E

Definition at line 498 of file several-builder.hpp.

Referenced by SeveralBuilder_test::check_Builder(), and SeveralBuilder_test::check_ErrorHandling().

Here is the caller graph for this function:

◆ emplace()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<class TY , typename... ARGS>

SeveralBuilder && emplace ( ARGS &&... args )

inline

create a new content element within the managed storage

Definition at line 508 of file several-builder.hpp.

Referenced by SeveralBuilder_test::check_Builder(), and SeveralBuilder_test::check_ErrorHandling().

Here is the caller graph for this function:

◆ build()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

Several build ( )

inline

Terminal Builder: complete and lock the collection contents.

Note: the SeveralBuilder is sliced away, effectively returning only the pointer to the ArrayBucket.

Definition at line 522 of file several-builder.hpp.

Referenced by SeveralBuilder_test::check_Builder(), and SeveralBuilder_test::check_ErrorHandling().

Here is the caller graph for this function:

◆ size()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

size_t size ( ) const

inline

Definition at line 527 of file several-builder.hpp.

Referenced by SeveralBuilder< I, E, POL >::capReserve(), SeveralBuilder_test::check_Builder(), SeveralBuilder_test::check_ErrorHandling(), WeavingBuilder< POL, PROT >::connectRemainingInputs(), and SeveralBuilder< I, E, POL >::shrinkFit().

Here is the caller graph for this function:

◆ empty()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

bool empty ( ) const

inline

Definition at line 528 of file several-builder.hpp.

◆ capacity()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

size_t capacity ( ) const

inline

Definition at line 529 of file several-builder.hpp.

Referenced by SeveralBuilder< I, E, POL >::capReserve(), SeveralBuilder_test::check_ErrorHandling(), SeveralBuilder< I, E, POL >::ensureStorageCapacity(), and SeveralBuilder< I, E, POL >::shrinkFit().

Here is the caller graph for this function:

◆ capReserve()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

size_t capReserve ( ) const

inline

Definition at line 530 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::capacity(), and SeveralBuilder< I, E, POL >::size().

Referenced by SeveralBuilder_test::check_ErrorHandling().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator[]()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

I & operator[] ( size_t idx )

inline

allow to peek into data emplaced thus far...

Warning: contents may be re-allocated until the final build()

Definition at line 536 of file several-builder.hpp.

References LERR_.

◆ emplaceCopy()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<class IT >

void emplaceCopy ( IT & dataSrc )

inlineprivate

Definition at line 550 of file several-builder.hpp.

Referenced by SeveralBuilder< I, E, POL >::appendAll().

Here is the caller graph for this function:

◆ emplaceMove()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<class IT >

void emplaceMove ( IT & dataSrc )

inlineprivate

Definition at line 558 of file several-builder.hpp.

Referenced by SeveralBuilder< I, E, POL >::moveAll().

Here is the caller graph for this function:

◆ emplaceNewElm()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<class TY , typename... ARGS>

void emplaceNewElm ( ARGS &&... args )

inlineprivate

Definition at line 566 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::adjustStorage().

Here is the call graph for this function:

◆ ensureDeleter()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<class TY >

void ensureDeleter ( )

inlineprivate

ensure clean-up can be handled properly.

Exceptions

err::Invalid when TY requires a different style of deleter than was established for this instance

Definition at line 589 of file several-builder.hpp.

◆ ensureElementCapacity()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<class TY >

void ensureElementCapacity ( size_t requiredSiz = reqSiz<TY>() )

inlineprivate

ensure sufficient element capacity or the ability to adapt element spread

Definition at line 599 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::canWildMove().

Here is the call graph for this function:

◆ ensureStorageCapacity()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<class TY >

void ensureStorageCapacity	(	size_t	requiredSiz = `reqSiz<TY>()`,
		size_t	newElms = `1`
	)

inlineprivate

ensure sufficient storage reserve for newElms or verify the ability to re-allocate

Definition at line 610 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::canDynGrow(), and SeveralBuilder< I, E, POL >::capacity().

Here is the call graph for this function:

◆ adjustStorage()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

void adjustStorage	(	size_t	cnt,
		size_t	spread
	)

inlineprivate

possibly grow storage and re-arrange elements to accommodate desired capacity

Definition at line 625 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::adjustSpread(), SeveralBuilder< I, E, POL >::canWildMove(), LERR_, LUMIERA_MAX_ORDINAL_NUMBER, and Several::spread().

Referenced by SeveralBuilder< I, E, POL >::emplaceNewElm(), and SeveralBuilder< I, E, POL >::reserve().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fitStorage()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

void fitStorage ( )

inlineprivate

Definition at line 657 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::canDynGrow().

Referenced by SeveralBuilder< I, E, POL >::shrinkFit().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ adjustSpread()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

void adjustSpread ( size_t newSpread )

inlineprivate

move existing data to accommodate spread

Definition at line 669 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::shiftStorage().

Referenced by SeveralBuilder< I, E, POL >::adjustStorage().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ shiftStorage()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

void shiftStorage	(	size_t	idx,
		size_t	oldSpread,
		size_t	newSpread
	)

inlineprivate

Definition at line 687 of file several-builder.hpp.

References util::min().

Referenced by SeveralBuilder< I, E, POL >::adjustSpread().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ render()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

static Literal render ( DestructionMethod m )

inlinestaticprivate

Definition at line 710 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::ELEMENT, SeveralBuilder< I, E, POL >::TRIVIAL, and SeveralBuilder< I, E, POL >::VIRTUAL.

Referenced by SeveralBuilder< I, E, POL >::__ensureMark().

Here is the caller graph for this function:

◆ selectDestructor()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<typename TY >

Deleter selectDestructor ( )

inlineprivate

Select a suitable method for invoking the element destructors and build a λ-object to be stored as deleter function alongside with the data; this includes a copy of the embedded allocator, which in many cases is a monostate empty base class.

Note: this collection is primed by the first element added, causing to lock into one of the possible destructor schemes; the reason is, we do not retain the information of the individual element types and thus we must employ one coherent scheme for all.

Definition at line 738 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::ELEMENT, SeveralBuilder< I, E, POL >::TRIVIAL, and SeveralBuilder< I, E, POL >::VIRTUAL.

◆ __ensureMark()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<typename TY >

void __ensureMark ( DestructionMethod requiredKind )

inlineprivate

Definition at line 767 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::destructor, SeveralBuilder< I, E, POL >::render(), and SeveralBuilder< I, E, POL >::UNKNOWN.

Here is the call graph for this function:

◆ probeMoveCapability()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

template<typename TY >

void probeMoveCapability ( )

inlineprivate

mark that we're about to accept an otherwise unknown type, which can not be trivially moved.

This irrevocably disables relocations by low-level memove for this container instance

Definition at line 784 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::lock_move.

◆ canWildMove()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

bool canWildMove ( )

inlineprivate

Definition at line 794 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::lock_move.

Referenced by SeveralBuilder< I, E, POL >::adjustStorage(), and SeveralBuilder< I, E, POL >::ensureElementCapacity().

Here is the caller graph for this function:

◆ canDynGrow()

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

bool canDynGrow ( )

inlineprivate

Definition at line 801 of file several-builder.hpp.

References SeveralBuilder< I, E, POL >::lock_move.

Referenced by SeveralBuilder< I, E, POL >::ensureStorageCapacity(), and SeveralBuilder< I, E, POL >::fitStorage().

Here is the caller graph for this function:

Member Data Documentation

◆ destructor

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

DestructionMethod destructor {UNKNOWN}

private

Definition at line 722 of file several-builder.hpp.

Referenced by SeveralBuilder< I, E, POL >::__ensureMark().

◆ lock_move

template<class I , class E = I, template< class, class > class POL = allo::HeapOwn>

bool lock_move {false}

private

Definition at line 723 of file several-builder.hpp.

Referenced by SeveralBuilder< I, E, POL >::canDynGrow(), SeveralBuilder< I, E, POL >::canWildMove(), and SeveralBuilder< I, E, POL >::probeMoveCapability().

Inheritance diagram for SeveralBuilder< I, E, POL >:

Collaboration diagram for SeveralBuilder< I, E, POL >:

The documentation for this class was generated from the following file:

several-builder.hpp

Description

Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ SeveralBuilder() [1/2]

◆ SeveralBuilder() [2/2]

Member Typedef Documentation

◆ Coll

◆ Policy

◆ Bucket

◆ Deleter

Member Enumeration Documentation

◆ DestructionMethod

Member Function Documentation

◆ policyConnect()

◆ withAllocator()

◆ reserve()

◆ shrinkFit()

◆ append()

◆ appendAll() [1/2]

◆ appendAll() [2/2]

◆ moveAll()

◆ fillElm()

◆ emplace()

◆ build()

◆ size()

◆ empty()

◆ capacity()

◆ capReserve()

◆ operator[]()

◆ emplaceCopy()

◆ emplaceMove()

◆ emplaceNewElm()

◆ ensureDeleter()

◆ ensureElementCapacity()

◆ ensureStorageCapacity()

◆ adjustStorage()

◆ fitStorage()

◆ adjustSpread()

◆ shiftStorage()

◆ render()

◆ selectDestructor()

◆ __ensureMark()

◆ probeMoveCapability()

◆ canWildMove()

◆ canDynGrow()

Member Data Documentation

◆ destructor

◆ lock_move