util::MappedContainer< Cont, Mapping > Class Template Reference

A meta-container providing transparent mapping on top of another. More...

#include <MappedContainer.h>

Inheritance diagram for util::MappedContainer< Cont, Mapping >:

Classes
class	IteratorBase

Public Types
using	DataContainer_t = Cont
	Type of the original container. More...
using	Mapping_t = Mapping
	Type of the mapping object. More...
using	MappedContainer_t = MappedContainer< DataContainer_t, Mapping_t >
	Type of this class. More...
using	DataIndex_t = util::collection_value_t< Mapping_t >
	Type of the index passed to the original container. More...
using	MappingIndex_t = std::size_t
	Type of the index passed to the mapping. More...
C++ standard container definitions
Type of datum in the container.
using	value_type = Value_t
using	size_type = std::size_t
using	difference_type = std::ptrdiff_t
using	reference = util::with_const_as_t< typename Storage_t::reference, util::collection_value_access_t< DataContainer_t > >
using	const_reference = typename Storage_t::const_reference
using	iterator = IteratorBase< MappedContainer_t, reference >
using	const_iterator = IteratorBase< MappedContainer_t const, const_reference >

Public Member Functions
void	setDefaultValue (value_type defValue)
Constructors
	MappedContainer ()=default
	Default constructor: container will be unusable until assigned to. More...
	MappedContainer (DataContainer_t const &cont, Mapping_t const &mapping, size_type size, value_type defValue)
	Constructor: acquires data, mapping and a default value. More...
	MappedContainer (DataContainer_t const &cont, Mapping_t const &mapping, size_type size)
	Constructor: acquires data and mapping. More...
	MappedContainer (DataContainer_t const &cont, Mapping_t const &mapping)
	Constructor: acquires data and mapping. More...
Container information
The size of the container after mapping is not strictly defined, since there might be elements not present in the original container, as well as those elements might appear more than once. On top of this, this object does not need to know the size to correctly operate, because no storage is used for the container data after mapping. Nevertheless, users may rightfully wonder and ask how many elements of the container are valid after the mapping. This class allows an answer to be provided at construction time, relying on the superior wisdom of the user. If the user does not care to impart such wisdom, a guess is made with using the minimal size needed to accommodate all the elements after mapping (see minimal_size()).
size_type	size () const
	Returns the nominal size of the container (after mapping). More...
size_type	minimal_size () const
	Returns the minimum size to include all mapped values. More...
size_type	max_size () const
	Returns the size of the largest possible container of this type. More...
bool	empty () const
	Returns whether the container has no elements. More...
reference	defaultValue ()
	Returns the default value for elements with no original content. More...
const_reference	defaultValue () const
Random access to elements
decltype(auto)	operator[] (MappingIndex_t index) const
	Returns the content corresponding to the specified index. More...
decltype(auto)	operator[] (MappingIndex_t index)
decltype(auto)	at (MappingIndex_t index) const
	Returns the content corresponding to the specified index. More...
decltype(auto)	at (MappingIndex_t index)
decltype(auto)	front () const
	Returns the first element in the container. More...
decltype(auto)	front ()
decltype(auto)	back () const
	Returns the last element in the container. More...
decltype(auto)	back ()
decltype(auto)	map_index (MappingIndex_t index) const
	Returns the index in the original data which is mapped to index. More...
decltype(auto)	map_index (MappingIndex_t index)
Iteration
const_iterator	cbegin () const
	Returns a constant iterator to the first mapped element. More...
const_iterator	begin () const
	Returns a constant iterator to the first mapped element. More...
iterator	begin ()
	Returns an iterator to the first mapped element. More...
const_iterator	cend () const
	Returns a constant iterator past the last mapped element. More...
const_iterator	end () const
	Returns a constant iterator past the last mapped element. More...
iterator	end ()
	Returns an iterator past the last mapped element. More...

Static Public Attributes
static constexpr DataIndex_t	InvalidIndex = invalidIndex<DataIndex_t>()

Static Protected Member Functions
static size_type	minimal_size (DataContainer_t const &cont, Mapping_t const &mapping)
	Returns the minimum size to include all mapped values. More...

Private Types
using	Storage_t = details::ContainerStorage< Cont >
	Type of object used for storage. More...
using	MappingStorage_t = details::ContainerStorage< Mapping >
	Type of object used for mapping storage. More...
using	Value_t = typename Storage_t::value_type
	Type of contained value. More...
using	Size_t = std::size_t
	Type for describing container size. More...

Private Member Functions
decltype(auto)	map_element (MappingIndex_t index)
	Returns the value mapped to the specified index. More...
decltype(auto)	map_element (MappingIndex_t index) const
	Returns the value mapped to the specified index. More...

Private Attributes
Storage_t	fData
	Data to be mapped. More...
MappingStorage_t	fMapping
	Mapping of stored data into final one. More...
Size_t	fSize = 0U
	Nominal size of the container. More...
std::remove_cv_t< Value_t >	fDefValue {}
	< Value returned for elements not mapped. More...

Additional Inherited Members
Static Private Member Functions inherited from util::MappedContainerBase
template<typename T = std::size_t>
static constexpr T	invalidIndex ()

Detailed Description

template<typename Cont, typename Mapping>
class util::MappedContainer< Cont, Mapping >

A meta-container providing transparent mapping on top of another.

Template Parameters

Cont	type of the underlying container
Mapping	type of the mapping to be applied

The mapped data is not permanently stored in memory, but rather the mapping is applied anew on each request. If a permanent mapped container is desired, a copy of this container into a standard one (e.g. a std::vector) can be used.

Note that the data itself is not modified by this container (although it may be just a copy of the original one: see note about storage below).

Example of usage:

constexpr auto InvalidIndex = util::MappedContainerBase::invalidIndex();

std::array<double, 4U> const data { 0.0, -1.0, -2.0, -3.0 };

std::array<std::size_t, 6U> const mapping = {
  1U, 0U, InvalidIndex,
  3U, 2U, InvalidIndex,
};

util::MappedContainer const mappedData
  (std::ref(data), mapping, 6U, std::numeric_limits<double>::quiet_NaN());

for (std::size_t i = 0; i < 6U; ++i) {
  std::cout
    << "Mapped element #" << i << ": " << mappedData[i] << std::endl;
}

which will print a list similar to: -1.0, 0.0, nan, -3.0, -2.0 and nan. Note that wrapping the original data into std::ref ensures that data is referenced rather than copied, while (in this example) the mapping is instead just copied. Wrapping it in std::cref would ensure the access to be in the const fashion even if the data array were not constant. The argument 6U ensures that the container can address 6 indices. In this example, it is needed only because then we specify a default value; MappedContainer is otherwise able to use as size the size of the mapping, if the mapping has one (see MappedContainer(DataContainer_t const&, Mapping_t const&)). Also note that in the example the C++17 template argument deduction is used and it's not necessary to specify those argument explicitly (it would be util::MappedContainer<std::array<double, 4U> const, std::array<std::size_t, 6U> const>).

Storage and ownership of the mapped data

If Cont is a C++ reference type, a C pointer, or a std::reference_wrapper object, the original container is referenced. Otherwise, a copy of it is internally stored with all data duplicated according to the container copy constructor.

C++ standard

This object fulfills most of the "Container" requirements, except for:

• container comparisons: they can be implemented if needed, but they would be slow
• swap(): did nor really bother to...

It also fulfills most of the "SequentialContainer" requirements that are not about construction or modification of the container size.

Definition at line 123 of file MappedContainer.h.

Member Typedef Documentation

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::const_iterator = IteratorBase<MappedContainer_t const, const_reference>

Definition at line 183 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::const_reference = typename Storage_t::const_reference

Definition at line 179 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::DataContainer_t = Cont

Type of the original container.

Definition at line 153 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::DataIndex_t = util::collection_value_t<Mapping_t>

Type of the index passed to the original container.

Definition at line 160 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::difference_type = std::ptrdiff_t

Definition at line 173 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::iterator = IteratorBase<MappedContainer_t, reference>

Definition at line 181 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::MappedContainer_t = MappedContainer<DataContainer_t, Mapping_t>

Type of this class.

Definition at line 157 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::Mapping_t = Mapping

Type of the mapping object.

Definition at line 154 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::MappingIndex_t = std::size_t

Type of the index passed to the mapping.

Definition at line 163 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::MappingStorage_t = details::ContainerStorage<Mapping>

private

Type of object used for mapping storage.

Definition at line 129 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::reference = util::with_const_as_t< typename Storage_t::reference, util::collection_value_access_t<DataContainer_t> >

Definition at line 178 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::Size_t = std::size_t

private

Type for describing container size.

Definition at line 134 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::size_type = std::size_t

Definition at line 172 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::Storage_t = details::ContainerStorage<Cont>

private

Type of object used for storage.

Definition at line 126 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::Value_t = typename Storage_t::value_type

private

Type of contained value.

Definition at line 132 of file MappedContainer.h.

template<typename Cont, typename Mapping>

using util::MappedContainer< Cont, Mapping >::value_type = Value_t

Definition at line 170 of file MappedContainer.h.

Constructor & Destructor Documentation

template<typename Cont, typename Mapping>

util::MappedContainer< Cont, Mapping >::MappedContainer ( )

default

Default constructor: container will be unusable until assigned to.

template<typename Cont, typename Mapping>

util::MappedContainer< Cont, Mapping >::MappedContainer ( DataContainer_t const &  cont, Mapping_t const &  mapping, size_type  size, value_type  defValue  )

inline

Constructor: acquires data, mapping and a default value.

Parameters

cont	container with the data to be mapped
mapping	the mapping to be used
size	the size of the container after mapping
defValue	value to be used as default

The defValue value is returned for the requested elements which are not mapped to the original container (InvalidIndex).

Definition at line 212 of file MappedContainer.h.

      : fData(cont), fMapping(mapping), fSize(size), fDefValue(defValue)
      {}

template<typename Cont, typename Mapping>

util::MappedContainer< Cont, Mapping >::MappedContainer ( DataContainer_t const &  cont, Mapping_t const &  mapping, size_type  size  )

inline

Constructor: acquires data and mapping.

Parameters

cont	container with the data to be mapped
mapping	the mapping to be used
size	the size of the container after mapping

The default value is a default-constructed value_type (0 for numeric types, nullptr for pointers).

Definition at line 231 of file MappedContainer.h.

      : MappedContainer(cont, mapping, size, {})
      {}

template<typename Cont, typename Mapping>

util::MappedContainer< Cont, Mapping >::MappedContainer ( DataContainer_t const &  cont, Mapping_t const &  mapping  )

inline

Constructor: acquires data and mapping.

Parameters

cont	container with the data to be mapped
mapping	the mapping to be used

The size of the container is declared to be the minimal one (see minimal_size()). The default value is a default-constructed value_type (0 for numeric types, nullptr for pointers).

Definition at line 245 of file MappedContainer.h.

      : MappedContainer(cont, mapping, minimal_size(cont, mapping))
      {}

Member Function Documentation

template<typename Cont, typename Mapping>

decltype(auto) util::MappedContainer< Cont, Mapping >::at

(

MappingIndex_t

index

)

const

Returns the content corresponding to the specified index.

Parameters

index

the index of the data to be retrieved

Returns

the mapped value (some decoration of value_type)

Exceptions

std::out_of_range

if the index is not in the container

template<typename Cont, typename Mapping>

decltype(auto) util::MappedContainer< Cont, Mapping >::at

(

MappingIndex_t

index

)

template<typename Cont, typename Mapping>

decltype(auto) util::MappedContainer< Cont, Mapping >::back ( ) const

inline

Returns the last element in the container.

Returns

the last element in the container, undefined if empty()

Definition at line 364 of file MappedContainer.h.

{ return map_element(size() - 1); }

template<typename Cont, typename Mapping>

decltype(auto) util::MappedContainer< Cont, Mapping >::back ( )

inline

Definition at line 365 of file MappedContainer.h.

{ return map_element(size() - 1); }

template<typename Cont, typename Mapping>

const_iterator util::MappedContainer< Cont, Mapping >::begin ( ) const

inline

Returns a constant iterator to the first mapped element.

Definition at line 392 of file MappedContainer.h.

{ return cbegin(); }

template<typename Cont, typename Mapping>

iterator util::MappedContainer< Cont, Mapping >::begin ( )

inline

Returns an iterator to the first mapped element.

Definition at line 395 of file MappedContainer.h.

{ return { *this, 0U }; }

template<typename Cont, typename Mapping>

const_iterator util::MappedContainer< Cont, Mapping >::cbegin ( ) const

inline

Returns a constant iterator to the first mapped element.

Definition at line 389 of file MappedContainer.h.

{ return { *this, 0U }; }

template<typename Cont, typename Mapping>

const_iterator util::MappedContainer< Cont, Mapping >::cend ( ) const

inline

Returns a constant iterator past the last mapped element.

Definition at line 398 of file MappedContainer.h.

{ return { *this, size() }; }

template<typename Cont, typename Mapping>

reference util::MappedContainer< Cont, Mapping >::defaultValue ( )

inline

Returns the default value for elements with no original content.

Note that changing it will change at the same time the value returned for all unmapped elements afterwards.

Definition at line 305 of file MappedContainer.h.

{ return fDefValue; }

template<typename Cont, typename Mapping>

const_reference util::MappedContainer< Cont, Mapping >::defaultValue ( ) const

inline

Definition at line 306 of file MappedContainer.h.

{ return fDefValue; }

template<typename Cont, typename Mapping>

bool util::MappedContainer< Cont, Mapping >::empty ( ) const

inline

Returns whether the container has no elements.

Definition at line 295 of file MappedContainer.h.

{ return size() == 0U; }

template<typename Cont, typename Mapping>

const_iterator util::MappedContainer< Cont, Mapping >::end ( ) const

inline

Returns a constant iterator past the last mapped element.

Definition at line 401 of file MappedContainer.h.

{ return cend(); }

template<typename Cont, typename Mapping>

iterator util::MappedContainer< Cont, Mapping >::end ( )

inline

Returns an iterator past the last mapped element.

Definition at line 404 of file MappedContainer.h.

{ return { *this, size() }; }

template<typename Cont, typename Mapping>

decltype(auto) util::MappedContainer< Cont, Mapping >::front ( ) const

inline

Returns the first element in the container.

Returns

the first element in the container, undefined if empty()

Definition at line 355 of file MappedContainer.h.

{ return map_element(0U); }

template<typename Cont, typename Mapping>

decltype(auto) util::MappedContainer< Cont, Mapping >::front ( )

inline

Definition at line 356 of file MappedContainer.h.

{ return map_element(0U); }

template<typename Cont, typename Mapping>

decltype(auto) util::MappedContainer< Cont, Mapping >::map_element ( MappingIndex_t  index )

private

Returns the value mapped to the specified index.

template<typename Cont, typename Mapping>

decltype(auto) util::MappedContainer< Cont, Mapping >::map_element ( MappingIndex_t  index ) const

private

Returns the value mapped to the specified index.

template<typename Cont, typename Mapping>

decltype(auto) util::MappedContainer< Cont, Mapping >::map_index

(

MappingIndex_t

index

)

const

Returns the index in the original data which is mapped to index.

Parameters

index

the index to be mapped (like e.g. in at())

Returns

the index in the original data container, or InvalidIndex

template<typename Cont, typename Mapping>

decltype(auto) util::MappedContainer< Cont, Mapping >::map_index

(

MappingIndex_t

index

)

template<typename Cont, typename Mapping>

size_type util::MappedContainer< Cont, Mapping >::max_size ( ) const

inline

Returns the size of the largest possible container of this type.

Definition at line 292 of file MappedContainer.h.

{ return std::numeric_limits<size_type>::max(); }

template<typename Cont , typename Mapping >

auto util::MappedContainer< Cont, Mapping >::minimal_size

(

)

const

Returns the minimum size to include all mapped values.

This method is available only if the mapping type (Mapping_t) answers a std::size() call, which is expected to return the number of elements the original data can be mapped into.

Definition at line 763 of file MappedContainer.h.

  { return minimal_size(fData.container(), fMapping.container()); }

template<typename Cont , typename Mapping >

auto util::MappedContainer< Cont, Mapping >::minimal_size ( DataContainer_t const &  cont, Mapping_t const &  mapping  )

staticprotected

Returns the minimum size to include all mapped values.

Definition at line 820 of file MappedContainer.h.

{
  /*
   * Obscure compiler errors are expected if the `Mapping_t` type does not
   * support `std::size`. In that case, very simply, `minimal_size()` can't be
   * used and the caller must specify the size of the container.
   */

  using std::size;
  return size(util::collection_from_reference(mapping));
} // util::MappedContainer<>::minimal_size(DataContainer_t, Mapping_t)

template<typename Cont, typename Mapping>

decltype(auto) util::MappedContainer< Cont, Mapping >::operator[] ( MappingIndex_t  index ) const

inline

Returns the content corresponding to the specified index.

Parameters

index

the index of the data to be retrieved

Returns

the mapped value (some decoration of value_type)

The content requested for index is fetched from the original data, at the element resulting from the mapping of the index argument.

Definition at line 332 of file MappedContainer.h.

      { return map_element(index); }

template<typename Cont, typename Mapping>

decltype(auto) util::MappedContainer< Cont, Mapping >::operator[] ( MappingIndex_t  index )

inline

Definition at line 334 of file MappedContainer.h.

      { return map_element(index); }

template<typename Cont, typename Mapping>

void util::MappedContainer< Cont, Mapping >::setDefaultValue ( value_type  defValue )

inline

Changes the default value. The new value will be used for all following mappings.

Definition at line 312 of file MappedContainer.h.

{ fDefValue = defValue; }

template<typename Cont, typename Mapping>

size_type util::MappedContainer< Cont, Mapping >::size ( void  ) const

inline

Returns the nominal size of the container (after mapping).

This is the value provided at construction time, or the minimal_size() at that time if no value was provided.

Definition at line 280 of file MappedContainer.h.

{ return fSize; }

Member Data Documentation

template<typename Cont, typename Mapping>

Storage_t util::MappedContainer< Cont, Mapping >::fData

private

Data to be mapped.

Definition at line 136 of file MappedContainer.h.

template<typename Cont, typename Mapping>

std::remove_cv_t<Value_t> util::MappedContainer< Cont, Mapping >::fDefValue {}

private

< Value returned for elements not mapped.

Definition at line 144 of file MappedContainer.h.

template<typename Cont, typename Mapping>

MappingStorage_t util::MappedContainer< Cont, Mapping >::fMapping

private

Mapping of stored data into final one.

Definition at line 138 of file MappedContainer.h.

template<typename Cont, typename Mapping>

Size_t util::MappedContainer< Cont, Mapping >::fSize = 0U

private

Nominal size of the container.

Definition at line 140 of file MappedContainer.h.

template<typename Cont, typename Mapping>

constexpr DataIndex_t util::MappedContainer< Cont, Mapping >::InvalidIndex = invalidIndex<DataIndex_t>()

static

Invalid index to be returned by the mapping when the required index is not mapped back to the original container; in that case, a defaultValue() is mapped instead.

Definition at line 192 of file MappedContainer.h.

---

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

• lardataalg/lardataalg/Utilities/MappedContainer.h