#include <Mapping.h>

Inheritance diagram for Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >:

Classes
class	_IRep
	Implementation detail for Mapping<T> implementors. More...

struct	EqualsComparer
	Compare Mappings<>s for equality. Note this can be costly, as the Mappings are not necessarily in the same order. More...

Public Types
using	ArchetypeContainerType = Mapping

using	value_type = typename inherited::value_type

using	key_type = KEY_TYPE

using	mapped_type = MAPPED_VALUE_TYPE

using	KeyEqualsCompareFunctionType = Common::ComparisonRelationDeclaration< Common::ComparisonRelationType::eEquals, function< bool(ArgByValueType< key_type >, ArgByValueType< key_type >)> >

Public Types inherited from Stroika::Foundation::Traversal::Iterable< T >
using	value_type = T
	value_type is an alias for the type iterated over - like vector<T>::value_type

using	iterator = Iterator< T >

using	const_iterator = Iterator< T >

Public Member Functions
	Mapping ()

nonvirtual Iterable< key_type >	Keys () const

nonvirtual Iterable< mapped_type >	MappedValues () const

nonvirtual optional< mapped_type >	Lookup (ArgByValueType< key_type > key) const

template<typename THROW_IF_MISSING >
nonvirtual mapped_type	LookupChecked (ArgByValueType< key_type > key, const THROW_IF_MISSING &throwIfMissing) const

nonvirtual mapped_type	LookupValue (ArgByValueType< key_type > key, ArgByValueType< mapped_type > defaultValue=mapped_type{}) const

nonvirtual add_const_t< mapped_type >	operator[] (ArgByValueType< key_type > key) const

nonvirtual bool	ContainsKey (ArgByValueType< key_type > key) const

template<typename VALUE_EQUALS_COMPARER = equal_to<MAPPED_VALUE_TYPE>>
nonvirtual bool	ContainsMappedValue (ArgByValueType< mapped_type > v, VALUE_EQUALS_COMPARER &&valueEqualsComparer={}) const

nonvirtual bool	Add (ArgByValueType< key_type > key, ArgByValueType< mapped_type > newElt, AddReplaceMode addReplaceMode=AddReplaceMode::eAddReplaces)

template<IIterableOfTo< KeyValuePair< KEY_TYPE, MAPPED_VALUE_TYPE > > ITERABLE_OF_ADDABLE>
nonvirtual unsigned int	AddAll (ITERABLE_OF_ADDABLE &&items, AddReplaceMode addReplaceMode=AddReplaceMode::eAddReplaces)

nonvirtual void	Remove (ArgByValueType< key_type > key)
	Remove the given item (which must exist).

nonvirtual bool	RemoveIf (ArgByValueType< key_type > key)
	Remove the given item, if it exists. Return true if found and removed.

nonvirtual void	RemoveAll ()
	RemoveAll removes all, or all matching (predicate, iterator range, equals comparer or whatever) items.

nonvirtual void	Update (const Iterator< value_type > &i, ArgByValueType< mapped_type > newValue, Iterator< value_type > *nextI=nullptr)

template<IIterableOfTo< KEY_TYPE > ITERABLE_OF_KEY_TYPE>
nonvirtual void	RetainAll (const ITERABLE_OF_KEY_TYPE &items)

template<typename RESULT_CONTAINER = Mapping<KEY_TYPE, MAPPED_VALUE_TYPE>, invocable< KeyValuePair< KEY_TYPE, MAPPED_VALUE_TYPE > > ELEMENT_MAPPER> requires (convertible_to<invoke_result_t<ELEMENT_MAPPER, KeyValuePair<KEY_TYPE, MAPPED_VALUE_TYPE>>, typename RESULT_CONTAINER::value_type> or convertible_to<invoke_result_t<ELEMENT_MAPPER, KeyValuePair<KEY_TYPE, MAPPED_VALUE_TYPE>>, optional<typename RESULT_CONTAINER::value_type>>)
nonvirtual RESULT_CONTAINER	Map (ELEMENT_MAPPER &&elementMapper) const
	'override' Iterable<>::Map () function so container template defaults to Mapping, and improve that case to also clone properties like sort order from this mapping

template<derived_from< Iterable< KeyValuePair< KEY_TYPE, MAPPED_VALUE_TYPE > > > RESULT_CONTAINER = Mapping<KEY_TYPE, MAPPED_VALUE_TYPE>, typename INCLUDE_PREDICATE > requires (predicate<INCLUDE_PREDICATE, KEY_TYPE> or predicate<INCLUDE_PREDICATE, KeyValuePair<KEY_TYPE, MAPPED_VALUE_TYPE>>)
nonvirtual RESULT_CONTAINER	Where (INCLUDE_PREDICATE &&includeIfTrue) const

template<typename CONTAINER_OF_KEYS >
nonvirtual ArchetypeContainerType	WithKeys (const CONTAINER_OF_KEYS &includeKeys) const

template<typename CONTAINER_OF_Key_T >
nonvirtual CONTAINER_OF_Key_T	As () const

nonvirtual bool	operator== (const Mapping &rhs) const
	compares if the two mappings have the same keys, and corresponding values (doesn't check ordering same). Note this can be costly, as the Mappings are not necessarily in the same order

nonvirtual void	Accumulate (ArgByValueType< key_type > key, ArgByValueType< mapped_type > newValue, const function< mapped_type(ArgByValueType< mapped_type >, ArgByValueType< mapped_type >)> &f=[](ArgByValueType< mapped_type > l, ArgByValueType< mapped_type > r) -> mapped_type { return l+r;}, mapped_type initialValue={})
	like Add (key, newValue) - BUT newValue is COMBINED with the 'f' argument.

nonvirtual void	insert (ArgByValueType< value_type > kvp)

nonvirtual void	erase (ArgByValueType< key_type > key)

nonvirtual void	clear ()

Public Member Functions inherited from Stroika::Foundation::Traversal::Iterable< T >
	Iterable (const Iterable &) noexcept=default
	Iterable are safely copyable (by value). Since Iterable uses COW, this just copies the underlying pointer and increments the reference count.

	Iterable (Iterable &&) noexcept=default
	Iterable are safely moveable.

template<IIterableOfTo< T > CONTAINER_OF_T> requires (not derived_from<remove_cvref_t<CONTAINER_OF_T>, Iterable<T>>)
	Iterable (CONTAINER_OF_T &&from)

	Iterable (const initializer_list< T > &from)

nonvirtual	operator bool () const

nonvirtual Iterator< T >	MakeIterator () const
	Create an iterator object which can be used to traverse the 'Iterable'.

nonvirtual size_t	size () const
	Returns the number of items contained.

nonvirtual bool	empty () const
	Returns true iff size() == 0.

template<Common::IPotentiallyComparer< T > EQUALS_COMPARER = equal_to<T>>
nonvirtual bool	Contains (ArgByValueType< T > element, EQUALS_COMPARER &&equalsComparer=EQUALS_COMPARER{}) const

nonvirtual Iterator< T >	begin () const
	Support for ranged for, and STL syntax in general.

nonvirtual void	Apply (const function< void(ArgByValueType< T > item)> &doToElement, Execution::SequencePolicy seq=Execution::SequencePolicy::eDEFAULT) const
	Run the argument function (or lambda) on each element of the container.

template<predicate< T > THAT_FUNCTION>
nonvirtual Iterator< T >	Find (THAT_FUNCTION &&that, Execution::SequencePolicy seq=Execution::SequencePolicy::eDEFAULT) const
	Run the argument bool-returning function (or lambda) on each element of the container, and return an iterator pointing at the first element (depending on seq) found true. (or use First() to do same thing but return optional<>)

template<IIterableOfFrom< T > CONTAINER_OF_T, typename... CONTAINER_OF_T_CONSTRUCTOR_ARGS>
nonvirtual CONTAINER_OF_T	As (CONTAINER_OF_T_CONSTRUCTOR_ARGS... args) const

nonvirtual T	Nth (ptrdiff_t n) const
	Find the Nth element of the Iterable<>

nonvirtual T	NthValue (ptrdiff_t n, ArgByValueType< T > defaultValue={}) const
	Find the Nth element of the Iterable<>, but allow for n to be out of range, and just return argument default-value.

template<derived_from< Iterable< T > > RESULT_CONTAINER = Iterable<T>, predicate< T > INCLUDE_PREDICATE>
nonvirtual RESULT_CONTAINER	Where (INCLUDE_PREDICATE &&includeIfTrue) const
	produce a subset of this iterable where argument function returns true

template<Common::IPotentiallyComparer< T > EQUALS_COMPARER = equal_to<T>>
nonvirtual Iterable< T >	Distinct (EQUALS_COMPARER &&equalsComparer=EQUALS_COMPARER{}) const

template<ranges::range RESULT_CONTAINER = Iterable<T>, invocable< T > ELEMENT_MAPPER> requires (convertible_to<invoke_result_t<ELEMENT_MAPPER, T>, typename RESULT_CONTAINER::value_type> or convertible_to<invoke_result_t<ELEMENT_MAPPER, T>, optional<typename RESULT_CONTAINER::value_type>>)
nonvirtual RESULT_CONTAINER	Map (ELEMENT_MAPPER &&elementMapper) const
	functional API which iterates over all members of an Iterable, applies a map function to each element, and collects the results in a new Iterable

template<typename REDUCED_TYPE = T>
nonvirtual optional< REDUCED_TYPE >	Reduce (const function< REDUCED_TYPE(ArgByValueType< T >, ArgByValueType< T >)> &op) const
	Walk the entire list of items, and use the argument 'op' to combine (reduce) items to a resulting single item.

template<typename REDUCED_TYPE = T>
nonvirtual REDUCED_TYPE	ReduceValue (const function< REDUCED_TYPE(ArgByValueType< T >, ArgByValueType< T >)> &op, ArgByValueType< REDUCED_TYPE > defaultValue={}) const

template<typename RESULT_T = Characters::String, invocable< T > CONVERT_TO_RESULT = decltype (kDefaultToStringConverter<>), invocable< RESULT_T, RESULT_T, bool > COMBINER = decltype (Characters::kDefaultStringCombiner)> requires (convertible_to<invoke_result_t<CONVERT_TO_RESULT, T>, RESULT_T> and convertible_to<invoke_result_t<COMBINER, RESULT_T, RESULT_T, bool>, RESULT_T>)
nonvirtual RESULT_T	Join (const CONVERT_TO_RESULT &convertToResult=kDefaultToStringConverter<>, const COMBINER &combiner=Characters::kDefaultStringCombiner) const
	ape the JavaScript/python 'join' function - take the parts of 'this' iterable and combine them into a new object (typically a string)

nonvirtual Iterable< T >	Skip (size_t nItems) const

nonvirtual Iterable< T >	Take (size_t nItems) const

nonvirtual Iterable< T >	Slice (size_t from, size_t to) const

nonvirtual Iterable< T >	Top () const
	return the top/largest (possibly just top N) values from this Iterable<T>

template<Common::IPotentiallyComparer< T > INORDER_COMPARER_TYPE = less<T>>
nonvirtual Iterable< T >	OrderBy (INORDER_COMPARER_TYPE &&inorderComparer=INORDER_COMPARER_TYPE{}, Execution::SequencePolicy seq=Execution::SequencePolicy::ePar) const

template<Common::IPotentiallyComparer< T > INORDER_COMPARER_TYPE = less<T>>
nonvirtual bool	IsOrderedBy (INORDER_COMPARER_TYPE &&inorderComparer=INORDER_COMPARER_TYPE{}) const

nonvirtual optional< T >	First () const
	return first element in iterable, or if 'that' specified, first where 'that' is true, (or return nullopt if none)

nonvirtual T	FirstValue (ArgByValueType< T > defaultValue={}) const
	return first element in iterable provided default

nonvirtual optional< T >	Last () const
	return last element in iterable, or if 'that' specified, last where 'that' is true, (or return missing)

nonvirtual T	LastValue (ArgByValueType< T > defaultValue={}) const

nonvirtual bool	All (const function< bool(ArgByValueType< T >)> &testEachElt) const
	return true iff argument predicate returns true for each element of the iterable

nonvirtual optional< T >	Min () const

template<typename RESULT_TYPE = T>
nonvirtual RESULT_TYPE	MinValue (ArgByValueType< RESULT_TYPE > defaultValue={}) const

nonvirtual optional< T >	Max () const

template<typename RESULT_TYPE = T>
nonvirtual RESULT_TYPE	MaxValue (ArgByValueType< RESULT_TYPE > defaultValue={}) const

template<typename RESULT_TYPE = T>
nonvirtual optional< RESULT_TYPE >	Mean () const

template<typename RESULT_TYPE = T>
nonvirtual RESULT_TYPE	MeanValue (ArgByValueType< RESULT_TYPE > defaultValue={}) const

template<typename RESULT_TYPE = T>
nonvirtual optional< RESULT_TYPE >	Sum () const

template<typename RESULT_TYPE = T>
nonvirtual RESULT_TYPE	SumValue (ArgByValueType< RESULT_TYPE > defaultValue={}) const

template<constructible_from< T > RESULT_TYPE = T, Common::IPotentiallyComparer< RESULT_TYPE > INORDER_COMPARE_FUNCTION = less<RESULT_TYPE>>
nonvirtual optional< RESULT_TYPE >	Median (const INORDER_COMPARE_FUNCTION &compare={}) const

template<constructible_from< T > RESULT_TYPE = T>
nonvirtual RESULT_TYPE	MedianValue (ArgByValueType< RESULT_TYPE > defaultValue={}) const

nonvirtual Iterable< T >	Repeat (size_t count) const

nonvirtual bool	Any () const
	Any() same as not empty (); Any (includeIfTrue) returns true iff includeIfTrue returns true on any values in iterable.

nonvirtual size_t	Count () const
	with no args, same as size, with function filter arg, returns number of items that pass.

nonvirtual size_t	length () const
	STL-ish alias for size() - really in STL only used in string, I think, but still makes sense as an alias.

Protected Member Functions
nonvirtual tuple< _IRep *, Iterator< value_type > >	_GetWritableRepAndPatchAssociatedIterator (const Iterator< value_type > &i)
	Utility to get WRITABLE underlying shared_ptr (replacement for what we normally do - _SafeReadWriteRepAccessor<_IRep>{this}._GetWriteableRep ()) but where we also handle the cloning/patching of the associated iterator.

Protected Member Functions inherited from Stroika::Foundation::Traversal::Iterable< T >
	Iterable (const shared_ptr< _IRep > &rep) noexcept
	Iterable's are typically constructed as concrete subtype objects, whose CTOR passed in a shared copyable rep.

nonvirtual Memory::SharedByValue_State	_GetSharingState () const

Additional Inherited Members
Static Public Member Functions inherited from Stroika::Foundation::Traversal::Iterable< T >
template<ranges::range LHS_CONTAINER_TYPE, ranges::range RHS_CONTAINER_TYPE, IEqualsComparer< T > EQUALS_COMPARER = equal_to<T>>
static bool	SetEquals (const LHS_CONTAINER_TYPE &lhs, const RHS_CONTAINER_TYPE &rhs, EQUALS_COMPARER &&equalsComparer=EQUALS_COMPARER{})

template<ranges::range LHS_CONTAINER_TYPE, ranges::range RHS_CONTAINER_TYPE, IEqualsComparer< T > EQUALS_COMPARER = equal_to<T>>
static bool	MultiSetEquals (const LHS_CONTAINER_TYPE &lhs, const RHS_CONTAINER_TYPE &rhs, EQUALS_COMPARER &&equalsComparer=EQUALS_COMPARER{})

template<ranges::range LHS_CONTAINER_TYPE, ranges::range RHS_CONTAINER_TYPE, IEqualsComparer< T > EQUALS_COMPARER = equal_to<T>>
static bool	SequentialEquals (const LHS_CONTAINER_TYPE &lhs, const RHS_CONTAINER_TYPE &rhs, EQUALS_COMPARER &&equalsComparer=EQUALS_COMPARER{}, bool useIterableSize=false)

static constexpr default_sentinel_t	end () noexcept
	Support for ranged for, and STL syntax in general.

Static Public Attributes inherited from Stroika::Foundation::Traversal::Iterable< T >
template<same_as< Characters::String > RESULT_T = Characters::String>
static const function< RESULT_T(T)>	kDefaultToStringConverter

Protected Types inherited from Stroika::Foundation::Traversal::Iterable< T >
using	_SharedByValueRepType = Memory::SharedByValue< _IRep, Memory::SharedByValue_Traits< _IRep, shared_ptr< _IRep >, Rep_Cloner_ > >
	Lazy-copying smart pointer mostly used by implementors (can generally be ignored by users). However, protected because manipulation needed in some subclasses (rarely) - like UpdatableIteratable.

Protected Attributes inherited from Stroika::Foundation::Traversal::Iterable< T >
_SharedByValueRepType	_fRep

Detailed Description

template<typename KEY_TYPE, typename MAPPED_VALUE_TYPE>
class Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >

Mapping which allows for the association of two elements: a key and

a value. The key UNIQUELY specifies its associated value.

See also: SortedMapping<Key,T>

Note: Design Note:; We used Iterable<KeyValuePair<Key,T>> instead of Iterable<pair<Key,T>> because it makes for more readable usage (foo.fKey versus foo.first, and foo.fValue versus foo.second).; Thread-Safety C++-Standard-Thread-Safety

Concrete Implementations: o

See also: Concrete::Mapping_Array<> o; Concrete::Mapping_LinkedList<> o; Concrete::Mapping_stdhashmap<> o; Concrete::SortedMapping_SkipList<> o; Concrete::SortedMapping_stdmap<>

Factory:

See also: Mapping_Factory<> to see default implementations.

Design Note: Included <map> and have explicit CTOR for map<> so that Stroika Mapping can be used more interoperably with map<> - and used without an explicit CTOR. Use Explicit CTOR to avoid accidental conversions. But if you declare an API with Mapping<KEY_TYPE,MAPPED_VALUE_TYPE> arguments, its important STL sources passing in map<> work transparently.

Similarly for std::initializer_list.

Note

Container Element comparisons: See about ElementInOrderComparerType, ElementThreeWayComparerType and GetElementThreeWayComparer etc

See ReadMe.md for common features of all Stroika containers (especially constructors, iterators, etc)

Comparisons: o static_assert (equality_comparable<VALUE_TYPE> ==> equality_comparable<Mapping<KEY, VALUE_TYPE>>);

Two Mappings are considered equal if they contain the same elements (keys) and each key is associated
with the same value. There is no need for the items to appear in the same order for the two Mappings to
be equal. There is no need for the backends to be of the same underlying representation either (stl map
vers linked list).

\pre lhs and rhs arguments must have the same (or equivalent) EqualsComparers.

@todo - document computational complexity

ThreeWayComparer support is NOT provided for Mapping, because there is no intrinsic ordering among the elements
of the mapping (keys) - even if there was some way to compare the values.

Definition at line 114 of file Mapping.h.

Member Typedef Documentation

◆ ArchetypeContainerType

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

using Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::ArchetypeContainerType = Mapping

Use this typedef in templates to recover the basic functional container pattern of concrete types.

Definition at line 133 of file Mapping.h.

◆ value_type

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

using Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::value_type = typename inherited::value_type

See also: inherited::value_type

Definition at line 139 of file Mapping.h.

◆ key_type

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

using Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::key_type = KEY_TYPE

like std::map<>::key_type

Definition at line 145 of file Mapping.h.

◆ mapped_type

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

using Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::mapped_type = MAPPED_VALUE_TYPE

like std::map<>::mapped_type

Definition at line 151 of file Mapping.h.

◆ KeyEqualsCompareFunctionType

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

using Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::KeyEqualsCompareFunctionType = Common::ComparisonRelationDeclaration<Common::ComparisonRelationType::eEquals, function<bool (ArgByValueType<key_type>, ArgByValueType<key_type>)> >

This is the type returned by GetKeyEqualsComparer () and CAN be used as the argument to a Mapping<> as KeyEqualityComparer, but we allow any template in the Mapping<> CTOR for a keyEqualityComparer that follows the IEqualsComparer concept.

Definition at line 158 of file Mapping.h.

Constructor & Destructor Documentation

◆ Mapping()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >
requires (IEqualsComparer<equal_to<KEY_TYPE>, KEY_TYPE>)

Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::Mapping ( )

This constructor creates a concrete mapping object, either empty, or initialized with any argument values.

The underlying data structure (and performance characteristics) of the Mapping is defined by

See also: Factory::Mapping_Factory<>

Example Usage: Collection<pair<int,int>> c;

std::map<int,int> m;

Mapping<int,int> m1 = {pair<int, int>{1, 1}, pair<int, int>{2, 2}, pair<int, int>{3, 2}};

Mapping<int,int> m2 = m1;

Mapping<int,int> m3{ m1 };

Mapping<int,int> m4{ m1.begin (), m1.end () };

Mapping<int,int> m5{ c };

Mapping<int,int> m6{ m };

Mapping<int,int> m7{ m.begin (), m.end () };

Mapping<int,int> m8{ move (m1) };

Mapping<int,int> m9{ Common::DeclareEqualsComparer ([](int l, int r) { return l == r; }) };

Stroika::Foundation::Containers::Collection
A Collection<T> is a container to manage an un-ordered collection of items, without equality defined ...
Definition Collection.h:102

Stroika::Foundation::Containers::Mapping
Definition Mapping.h:114

Stroika::Foundation::Traversal::Iterable::begin
nonvirtual Iterator< T > begin() const
Support for ranged for, and STL syntax in general.
Definition Iterable.inl:1099

Stroika::Foundation::Traversal::Iterable::end
static constexpr default_sentinel_t end() noexcept
Support for ranged for, and STL syntax in general.
Definition Iterable.inl:1104

Stroika::Foundation::Common::DeclareEqualsComparer
constexpr Common::ComparisonRelationDeclaration< ComparisonRelationType::eEquals, remove_cvref_t< FUNCTOR > > DeclareEqualsComparer(FUNCTOR &&f)
DeclareEqualsComparer () marks a FUNCTOR (lambda or not) as being a FUNCTOR which compares for equali...
Definition Compare.inl:31

Note: Even though the initializer_list<> is of KeyValuePair, you can pass along pair<> objects just as well.; See general information about container constructors that applies here

Definition at line 25 of file Mapping.inl.

Member Function Documentation

◆ Keys()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

Iterable< KEY_TYPE > Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::Keys ( ) const

Keys () returns an Iterable object with just the key part of the Mapping.

Note: Keys () will return a an Iterable producing (iterating) elements in the same order as the Mapping it is created from.

It is equivalent to copying the underlying Mapping and 'projecting' the key fields (so the result will be sorted in a SortedMapping).

This means that Keys() is detached from the original Mapping (should that change) and its lifetime may extend past the lifetime of the original mapping.

Design Note: The analogous method in C#.net - Dictionary<TKey, TValue>.KeyCollection (http://msdn.microsoft.com/en-us/library/yt2fy5zk(v=vs.110).aspx) returns a live reference to the underlying keys. We could have (fairly easily) done that, but I didn't see the point.

In .net, the typical model is that you have a pointer to an object, and pass around that pointer (so by reference semantics) - so this returning a live reference makes more sense there.

Since Stroika containers are logically copy-by-value (even though lazy-copied), it made more sense to apply that lazy-copy (copy-on-write) paradigm here, and make the returned set of keys a logical copy at the point 'keys' is called.

See:

See also: MappedValues ()

Definition at line 113 of file Mapping.inl.

◆ MappedValues()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

Iterable< MAPPED_VALUE_TYPE > Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::MappedValues ( ) const

MappedValues () returns an Iterable object with just the value part of the Mapping.

Note: MappedValues () will return a an Iterable producing (iterating) elements in the same order as the collection it is created from.

It is equivalent to copying the underlying collection and 'projecting' the value fields.

This means that Keys() is detached from the original Mapping (should that change) and its lifetime may extend past the lifetime of the original mapping.

Design Note: The analogous method in C#.net - Dictionary<TKey, TValue>.ValueCollection (https://msdn.microsoft.com/en-us/library/x8bctb9c%28v=vs.110%29.aspx).aspx) returns a live reference to the underlying keys. We could have (fairly easily) done that, but I didn't see the point.

In .net, the typical model is that you have a pointer to an object, and pass around that pointer (so by reference semantics) - so this returning a live reference makes more sense there.

Since Stroika containers are logically copy-by-value (even though lazy-copied), it made more sense to apply that lazy-copy (copy-on-write) paradigm here, and make the returned set of keys a logical copy at the point 'keys' is called.

Aliases: Image ()

See:

See also: Keys ()

Definition at line 118 of file Mapping.inl.

◆ Lookup()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

optional< MAPPED_VALUE_TYPE > Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::Lookup ( ArgByValueType< key_type > key ) const

Note - as since Lookup/1 returns an optional<T> - it can be used very easily to provide a default value on Lookup (so for case where not present) - as in: return m.Lookup (key).Value (putDefaultValueHere);

Note - for both overloads taking an item pointer, the pointer may be nullptr (in which case not assigned to). But if present, will always be assigned to if Lookup returns true (found). And for the optional overload

Precondition: Ensure (item == nullptr or returnValue == item->has_value());

Aliases: Lookup (key, mapped_type* value) - is equivalent to .Net TryGetValue ()

@todo http://stroika-bugs.sophists.com/browse/STK-928 - add overload 'returning' Iterator<>, so can use with Update method

Definition at line 144 of file Mapping.inl.

◆ LookupChecked()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

template<typename THROW_IF_MISSING >

nonvirtual mapped_type Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::LookupChecked	(	ArgByValueType< key_type >	key,
		const THROW_IF_MISSING &	throwIfMissing
	)		const

Aliases: LookupOrException

◆ LookupValue()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

MAPPED_VALUE_TYPE Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::LookupValue	(	ArgByValueType< key_type >	key,
		ArgByValueType< mapped_type >	defaultValue = `mapped_type{}`
	)		const

Always safe to call. If result of Lookup () !has_value, returns argument 'default' or 'sentinel' value.

Aliases: LookupOrDefault

Definition at line 168 of file Mapping.inl.

◆ operator[]()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

auto Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::operator[] ( ArgByValueType< key_type > key ) const

Precondition: ContainsKey (key);

Note: Design Note: Defined operator[](KEY_TYPE) const - to return const MAPPED_VALUE_TYPE, instead of optional<MAPPED_VALUE_TYPE> because this adds no value - you can always use Lookup or LookupValue. The reason to use operator[] is as convenient syntactic sugar. But if you have to check (the elt not necessarily present) - then you may as well use Lookup () - cuz the code's going to look ugly anyhow.

Defined operator[](KEY_TYPE) const - to return MAPPED_VALUE_TYPE instead of MAPPED_VALUE_TYPE& because we then couldn't control the lifetime of that reference, and it would be unsafe as the underlying object was changed.

And therefore we return CONST of that type so that code like m["xx"].a = 3 won't compile (and wont just assign to a temporary that disappears leading to confusion).

Note: In the future, it may make sense to have operator[] return a PROXY OBJECT, so that it MIGHT be assignable. But that wouldn't work with cases like Mapping<String,OBJ> where you wanted to access OBJs fields as in m["xx"].a = 3

Definition at line 174 of file Mapping.inl.

◆ ContainsKey()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

bool Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::ContainsKey ( ArgByValueType< key_type > key ) const

Synonym for Lookup (key).has_value ()

Definition at line 179 of file Mapping.inl.

◆ ContainsMappedValue()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

template<typename VALUE_EQUALS_COMPARER = equal_to<MAPPED_VALUE_TYPE>>

nonvirtual bool Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::ContainsMappedValue	(	ArgByValueType< mapped_type >	v,
		VALUE_EQUALS_COMPARER &&	valueEqualsComparer = `{}`
	)		const

Likely inefficient for a map, but perhaps helpful. Walks entire list of entires and applies VALUE_EQUALS_COMPARER (defaults to operator==) on each value, and returns true if contained. Perhaps not very useful but symmetric to ContainsKey().

◆ Add()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

bool Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::Add	(	ArgByValueType< key_type >	key,
		ArgByValueType< mapped_type >	newElt,
		AddReplaceMode	addReplaceMode = `AddReplaceMode::eAddReplaces`
	)

Add the association between key and newElt.

If key was already associated with something, consult argument addReplaceMode (defaults to AddReplaceMode::eAddReplaces). if 'replaces' then replace, and if 'addif' then do nothing on Add ()

Returns: bool: The (generally ignored) return value boolean indicates if a new item was added (so size of iterable increased). This value returned is FALSE for the case of when the value remains unchanged or even if the value is updated (overwriting the previous association).

Also - we guarantee that even if the association is different, if the key has not changed, then the iteration order is not changed (helpful for AddAll() semantics, and perhaps elsewhere).

Note: This behavior when the entry already exists differs from the behavior of std::map::insert (

See also: http://en.cppreference.com/w/cpp/container/map/insert) "Inserts element(s) into the container, if the container doesn't already contain an element with an equivalent key". This behavior is analogous to the new std-c++17 std::map::insert_or_assign () -; http://en.cppreference.com/w/cpp/container/map/insert_or_assign

Note: mutates container; - this returns true if a CLEAR change happened. But mappings don't have a VALUE_COMPARER by default. So no way to return if the MAPPING ITSELF changed.

Note: Similar to Set<>::AddIf() - but here there is the ambiguity about whether to change what is mapped to (which we do differently between Add and AddIf) and no such issue exists with Set<>::AddIf. But return true if they make a change.

Definition at line 190 of file Mapping.inl.

◆ AddAll()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

template<IIterableOfTo< KeyValuePair< KEY_TYPE, MAPPED_VALUE_TYPE > > ITERABLE_OF_ADDABLE>

nonvirtual unsigned int Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::AddAll	(	ITERABLE_OF_ADDABLE &&	items,
		AddReplaceMode	addReplaceMode = `AddReplaceMode::eAddReplaces`
	)

\summary Add all the argument (container or bound range of iterators) elements; if replaceExistingMapping true (default) force replace on each. Return count of added items (not count of updated items)

Aliases: AddAll/2 is alias for .net AddRange ()

Note: mutates container

◆ Remove()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

void Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::Remove ( ArgByValueType< key_type > key )

Remove the given item (which must exist).

Note: - for the argument 'key' overload, this is a change in Stroika 2.1b14: before it was legal and silently ignored if you removed an item that didn't exist.

Parameters

nextI - if provided (not null) - will be filled in with the next value after where iterator i is pointing - since i is invalidated by changing the container)

Note: mutates container

Definition at line 225 of file Mapping.inl.

◆ RemoveIf()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

bool Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::RemoveIf ( ArgByValueType< key_type > key )

Remove the given item, if it exists. Return true if found and removed.

Note: mutates container

Definition at line 237 of file Mapping.inl.

◆ RemoveAll()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

void Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::RemoveAll ( )

RemoveAll removes all, or all matching (predicate, iterator range, equals comparer or whatever) items.

The no-arg overload removes all (quickly).

The overloads that remove some subset of the items returns the number of items so removed, and use RemoveIf() so that the argument items designated to be removed MAY not be present.

Note: mutates container

Definition at line 242 of file Mapping.inl.

◆ Update()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

void Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::Update	(	const Iterator< value_type > &	i,
		ArgByValueType< mapped_type >	newValue,
		Iterator< value_type > *	nextI = `nullptr`
	)

Update the value associated with the iterator 'i', without changing iteration order in any way (cuz the key not changed). Note - if iterating, because this modifies the underlying container, the caller should pass 'i' in as a reference parameter to 'nextI' to have it updated to safely continue iterating.

Note: mutates container; As with ALL methods that modify the Mapping, this invalidates the iterator 'i', but if you pass nextI (can be same variable as i) - it will be updated with a valid iterator pointing to the same location.

Definition at line 312 of file Mapping.inl.

◆ RetainAll()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

template<IIterableOfTo< KEY_TYPE > ITERABLE_OF_KEY_TYPE>

nonvirtual void Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::RetainAll ( const ITERABLE_OF_KEY_TYPE & items )

Remove all items from this container UNLESS they are in the argument set to RetainAll().

This restricts the 'Keys' list of Mapping to the argument data, but preserving any associations.

Note: Java comparison mapping.keySet.retainAll (collection);

Example Usage: fStaticProcessStatsForThisSpill_.RetainAll (fDynamicProcessStatsForThisSpill_.Keys ()); // lose static data for processes no longer running

Note: Something of an alias for 'Subset()' or 'Intersects', as this - in-place computes the subset of the Mapping<> that intersects with the argument keys.

Note: mutates container

◆ Where()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

template<derived_from< Iterable< KeyValuePair< KEY_TYPE, MAPPED_VALUE_TYPE > > > RESULT_CONTAINER = Mapping<KEY_TYPE, MAPPED_VALUE_TYPE>, typename INCLUDE_PREDICATE >
requires (predicate<INCLUDE_PREDICATE, KEY_TYPE> or predicate<INCLUDE_PREDICATE, KeyValuePair<KEY_TYPE, MAPPED_VALUE_TYPE>>)

nonvirtual RESULT_CONTAINER Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::Where ( INCLUDE_PREDICATE && includeIfTrue ) const

Apply the function function to each element, and return a subset Mapping including just the ones for which it was true.

Aliases: 'Subset' - as it constructs a subset mapping (filtering on key or key-value pairs)

See also: Iterable<T>::Where

Example Usage: Mapping<int, int> m{{1, 3}, {2, 4}, {3, 5}, {4, 5}, {5, 7}};

EXPECT_TRUE ((m.Where ([] (const KeyValuePair<int, int>& value) { return Math::IsPrime (value.fKey); }) == Mapping<int, int>{{2, 4}, {3, 5}, {5, 7}}));

EXPECT_TRUE ((m.Where ([] (int key) { return Math::IsPrime (key); }) == Mapping<int, int>{{2, 4}, {3, 5}, {5, 7}}));

◆ WithKeys()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

template<typename CONTAINER_OF_KEYS >

nonvirtual ArchetypeContainerType Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::WithKeys ( const CONTAINER_OF_KEYS & includeKeys ) const

Return a subset of this Mapping<> where the keys are included in the argument includeKeys set..

Aliases: Subset - as it constructs a subset mapping (where the given keys intersect)

See also: Iterable<T>::Where; Where

Note: CONCEPT - CONTAINER_OF_KEYS must support the 'Contains' API - not that set, and Iterable<> do this.

Example Usage: Mapping<int, int> m{{1, 3}, {2, 4}, {3, 5}, {4, 5}, {5, 7}};

EXPECT_TRUE ((m.WithKeys ({2, 5}) == Mapping<int, int>{{2, 4}, {5, 7}}));

◆ As()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

template<typename CONTAINER_OF_Key_T >

nonvirtual CONTAINER_OF_Key_T Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::As ( ) const

This function should work for any container which accepts (ITERATOR_OF<KeyValuePair<Key,Value>>,ITERATOR_OF<KeyValuePair<Key,Value>>) OR (ITERATOR_OF<pair<Key,Value>>,ITERATOR_OF<pair<Key,Value>>).

These As<> overloads also may require the presence of an insert(ITERATOR, Value) method of CONTAINER_OF_Key_T.

So - for example, Sequence<KeyValuePair<key_type,ValueType>>, map<key_type,ValueType>, vector<pair<key_type,ValueType>>, etc...

◆ _GetWritableRepAndPatchAssociatedIterator()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

auto Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::_GetWritableRepAndPatchAssociatedIterator ( const Iterator< value_type > & i )

protected

Utility to get WRITABLE underlying shared_ptr (replacement for what we normally do - _SafeReadWriteRepAccessor<_IRep>{this}._GetWriteableRep ()) but where we also handle the cloning/patching of the associated iterator.

When you have a non-const operation (such as Remove) with an argument of an Iterator<>, then due to COW, you may end up cloning the container rep, and yet the Iterator<> contains a pointer to the earlier rep (and so maybe unusable).

Prior to Stroika 2.1b14, this was handled elegantly, and automatically, by the iterator patching mechanism. But that was deprecated (due to cost, and rarity of use), in favor of this more restricted feature, where we just patch the iterators on an as-needed basis.

Definition at line 470 of file Mapping.inl.

◆ operator==()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >
requires (equality_comparable<MAPPED_VALUE_TYPE>)

bool Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::operator== ( const Mapping< KEY_TYPE, MAPPED_VALUE_TYPE > & rhs ) const

compares if the two mappings have the same keys, and corresponding values (doesn't check ordering same). Note this can be costly, as the Mappings are not necessarily in the same order

simply indirect to @Mapping<>::EqualsComparer; only defined if there is a default equals comparer for mapped_type

Definition at line 490 of file Mapping.inl.

◆ Accumulate()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

void Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::Accumulate	(	ArgByValueType< key_type >	key,
		ArgByValueType< mapped_type >	newValue,
		const function< mapped_type(ArgByValueType< mapped_type >, ArgByValueType< mapped_type >)> &	f = `[] (ArgByValueType<mapped_type> l, ArgByValueType<mapped_type> r) -> mapped_type { return l + r; }`,
		mapped_type	initialValue = `{}`
	)

like Add (key, newValue) - BUT newValue is COMBINED with the 'f' argument.

The accumulator function combines the previous value associated with the new value given (using initialValue if key was not already present in the map).

Definition at line 419 of file Mapping.inl.

◆ insert()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

void Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::insert ( ArgByValueType< value_type > kvp )

Aliases: Add ().

See also: https://en.cppreference.com/w/cpp/container/map/insert

Note: - we only provide a very small subset of the possible variations of insert from STL, but this is probably the most common

Definition at line 426 of file Mapping.inl.

◆ erase()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

void Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::erase ( ArgByValueType< key_type > key )

Aliases: Remove ().

Note: - beware of using erase(iterator) - probably should use Stroika 'Remove' so you can pass extra parameter to get iterator patched. At any rate, beware its illegal to use 'i' after erasing at i (detected by Stroika when use use it).

Definition at line 431 of file Mapping.inl.

◆ clear()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

void Stroika::Foundation::Containers::Mapping< KEY_TYPE, MAPPED_VALUE_TYPE >::clear ( )

Aliases: RemoveAll ().

Definition at line 443 of file Mapping.inl.

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

Classes

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ArchetypeContainerType

◆ value_type

◆ key_type

◆ mapped_type

◆ KeyEqualsCompareFunctionType

Constructor & Destructor Documentation

◆ Mapping()

Member Function Documentation

◆ Keys()

◆ MappedValues()

◆ Lookup()

◆ LookupChecked()

◆ LookupValue()

◆ operator[]()

◆ ContainsKey()

◆ ContainsMappedValue()

◆ Add()

◆ AddAll()

◆ Remove()

◆ RemoveIf()

◆ RemoveAll()

◆ Update()

◆ RetainAll()

◆ Where()

◆ WithKeys()

◆ As()

◆ _GetWritableRepAndPatchAssociatedIterator()

◆ operator==()

◆ Accumulate()

◆ insert()

◆ erase()

◆ clear()