SeveralBuilder< I, E, POL > Class Template Reference

#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<I>.

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 391 of file several-builder.hpp.

Public Member Functions
template<typename... ARGS, typename = meta::enable_if<std::is_constructible<Policy,ARGS&&...>>>
	SeveralBuilder (ARGS &&...alloInit)
	start Several build using a custom allocator
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)
Several< I >	build ()
	Terminal Builder: complete and lock the collection contents. More...
size_t	capacity () const
size_t	capReserve () const
template<class TY , typename... ARGS>
SeveralBuilder &&	emplace (ARGS &&...args)
	create a new content element within the managed storage
bool	empty () const
template<typename... ARGS>
SeveralBuilder &&	fillElm (size_t cntNew, ARGS &&...args)
	emplace a number of elements of the defined element type E
I &	operator[] (size_t idx)
	allow to peek into data emplaced thus far... More...
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. More...
size_t	size () const

Public Attributes
	Policy

Private Types
using	Bucket = several::ArrayBucket< I >
using	Coll = Several< I >
using	Deleter = typename Bucket::Deleter
enum	DestructionMethod {   UNKNOWN,   TRIVIAL,   ELEMENT,   VIRTUAL }
using	Policy = POL< I, E >
Private Types inherited from Several< I >
using	const_iterator = lib::IndexIter< const Several >
using	iterator = lib::IndexIter< Several >
using	Bucket = several::ArrayBucket< I > *

Private Member Functions
template<typename TY >
void	__ensureMark (DestructionMethod requiredKind)
void	adjustSpread (size_t newSpread)
	move existing data to accommodate spread
void	adjustStorage (size_t cnt, size_t spread)
	possibly grow storage and re-arrange elements to accommodate desired capacity
bool	canDynGrow ()
bool	canWildMove ()
template<class IT >
void	emplaceCopy (IT &dataSrc)
template<class TY , typename... ARGS>
void	emplaceNewElm (ARGS &&...args)
template<class TY >
void	ensureDeleter ()
	ensure clean-up can be handled properly. More...
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	fitStorage ()
template<typename TY >
void	probeMoveCapability ()
	mark that we're about to accept an otherwise unknown type, which can not be trivially moved. More...
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. More...
void	shiftStorage (size_t idx, size_t oldSpread, size_t newSpread)
Private Member Functions inherited from Several< I >
	Several ()=default
	usually to be created through SeveralBuilder
	Several (Several &&rr)
	Move-Assignment allowed...
I &	back ()
iterator	begin ()
const_iterator	begin () const
bool	empty () const
iterator	end ()
const_iterator	end () const
I &	front ()
Several &	operator= (Several &&rr)
I &	operator[] (size_t idx)
I const &	operator[] (size_t idx) const
size_t	size () const
bool	hasReserve (size_t requiredSize, size_t newElms=1) const
size_t	spread () const
size_t	storageBuffSiz () const
Private Member Functions inherited from MoveOnly
	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}

Member Function Documentation

shrinkFit()

SeveralBuilder&& shrinkFit ( )

inline

discard excess reserve capacity.

Warning

typically this requires re-allocation and copy

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

Referenced by SeveralBuilder_test::check_CustomAllocator().

Here is the caller graph for this function:

build()

Several<I> 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 509 of file several-builder.hpp.

Referenced by NodeBuilder< POL, DAT >::build(), and SeveralBuilder_test::check_CustomAllocator().

Here is the caller graph for this function:

operator[]()

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 523 of file several-builder.hpp.

ensureDeleter()

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 568 of file several-builder.hpp.

selectDestructor()

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 717 of file several-builder.hpp.

probeMoveCapability()

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 759 of file several-builder.hpp.

Member Data Documentation

Policy

Policy

Initial value:

{forward<ARGS> (alloInit)...}
        { }
      
      
      Policy& policyConnect() { return *this; }
      
      
      
      
      
      
      template<template<typename> class ALO  =std::void_t
              ,typename...ARGS>
      auto withAllocator (ARGS&& ...args)

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

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