An Association pairs key values with (possibly multiple or none) mapped_type values. Like Mapping<>, but allowing multiple items associated with 'key'. More...

#include <Association.h>

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

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

struct	EqualsComparer
	Compare Associations<>s for equality. More...

Public Types
using	ArchetypeContainerType = Association

using	value_type = typename inherited::value_type

using	key_type = KEY_TYPE

using	mapped_type = MAPPED_VALUE_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
	Association ()

nonvirtual Iterable< key_type >	Keys () const

nonvirtual Iterable< mapped_type >	MappedValues () const

nonvirtual Traversal::Iterable< mapped_type >	Lookup (ArgByValueType< key_type > key) const
	Return an Iterable<mapped_type> of all the associated items (can be empty if none). This iterable is a snapshot at the time of call (but maybe lazy COW copied snapshot so still cheap)

nonvirtual optional< mapped_type >	LookupOne (ArgByValueType< key_type > key) const
	Lookup and return the first (maybe arbitrarily chosen which is first) value with this key, and throw if there are none.

template<typename THROW_IF_MISSING >
nonvirtual mapped_type	LookupOneChecked (ArgByValueType< key_type > key, const THROW_IF_MISSING &throwIfMissing) const
	Lookup and return the first (maybe arbitrarily chosen which is first) value with this key, and throw if there are none.

nonvirtual mapped_type	LookupOneValue (ArgByValueType< key_type > key, ArgByValueType< mapped_type > defaultValue=mapped_type{}) const
	Lookup and return the first (maybe arbitrarily chosen which is first) value with this key, and otherwise return argument value as default.

nonvirtual const Iterable< mapped_type >	operator[] (ArgByValueType< key_type > key) const
	Shortcut for Lookup.

nonvirtual bool	ContainsKey (ArgByValueType< key_type > key) const

nonvirtual size_t	OccurrencesOf (ArgByValueType< key_type > item) const

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

nonvirtual void	Add (ArgByValueType< key_type > key, ArgByValueType< mapped_type > newElt)

template<IIterableOfTo< KeyValuePair< KEY_TYPE, MAPPED_VALUE_TYPE > > ITERABLE_OF_ADDABLE>
nonvirtual void	AddAll (ITERABLE_OF_ADDABLE &&items)

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 = Association<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 RESULT_CONTAINER defaults to Association, and improve that case to clone properties from this rep (such is rep type, comparisons etc).

template<derived_from< Iterable< KeyValuePair< KEY_TYPE, MAPPED_VALUE_TYPE > > > RESULT_CONTAINER = Association<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 Association &rhs) const

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	erase (ArgByValueType< key_type > key)
	STL-ish alias for Remove ().

nonvirtual void	clear ()
	STL-ish alias for RemoveAll ().

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::Association< KEY_TYPE, MAPPED_VALUE_TYPE >

An Association pairs key values with (possibly multiple or none) mapped_type values. Like Mapping<>, but allowing multiple items associated with 'key'.

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

a value. Unlike a Mapping<>, this association may not be unique..

See also: SortedAssociation<Key,T>

Aliases: MultiMap

Note: The term 'KEY' usually implies a UNIQUE mapping to the associated value, but DOES NOT do so in this container ArcheType. Though databases generally use key to imply unique, https://en.cppreference.com/w/cpp/container/multimap, for example, does not.; 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::Association_Array<> o; Concrete::Association_LinkedList<> o; Concrete::SortedAssociation_stdmap<> o; Concrete::SortedAssociation_SkipList<>

Factory:

See also: <> to see default implementations.

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

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

Similarly for std::initializer_list.

Note

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

Comparisons: o operator==(Association& rhs) requires (equality_comparable<MAPPED_VALUE_TYPE>);

Two Associations 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 Associations to
be equal. There is no need for the backends to be of the same underlying representation either (stlmap
vers LinkedList).

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

@todo - document computational complexity

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

Definition at line 113 of file Association.h.

Member Typedef Documentation

◆ ArchetypeContainerType

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

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

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

Definition at line 124 of file Association.h.

◆ value_type

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

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

See also: inherited::value_type

Definition at line 130 of file Association.h.

◆ key_type

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

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

like std::multimap<>::key_type

Definition at line 136 of file Association.h.

◆ mapped_type

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

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

like std::multimap<>::mapped_type

Definition at line 142 of file Association.h.

Constructor & Destructor Documentation

◆ Association()

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

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

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

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

See also: Factory::Association_Factory<>

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

std::map<int,int> m;

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

Association<int,int> m2 = m1;

Association<int,int> m3{ m1 };

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

Association<int,int> m5{ c };

Association<int,int> m6{ m };

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

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

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

Stroika::Foundation::Containers::Association
An Association pairs key values with (possibly multiple or none) mapped_type values....
Definition Association.h:113

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::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 Association.inl.

Member Function Documentation

◆ Keys()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

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

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

Note: Keys () 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 key fields.

Note the returned Iterable is detached from the original, and doesn't see any changes to it, and its lifetime is like a copy of a shared_ptr - lasts as long as the reference.

Design Note: The analagous 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 Association.inl.

◆ MappedValues()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

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

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

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.

Note the returned Iterable is detached from the original, and doesn't see any changes to it, and its lifetime is like a copy of a shared_ptr - lasts as long as the reference.

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 Association.inl.

◆ LookupOne()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

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

Lookup and return the first (maybe arbitrarily chosen which is first) value with this key, and throw if there are none.

Aliases: LookupOrException

Definition at line 128 of file Association.inl.

◆ LookupOneChecked()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

template<typename THROW_IF_MISSING >

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

Lookup and return the first (maybe arbitrarily chosen which is first) value with this key, and throw if there are none.

Aliases: LookupOrException

◆ LookupOneValue()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

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

Lookup and return the first (maybe arbitrarily chosen which is first) value with this key, and otherwise return argument value as default.

Aliases: LookupOneOrDefault

Definition at line 148 of file Association.inl.

◆ operator[]()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

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

Shortcut for Lookup.

if key is not in the container, an empty iterable will be returned.

Definition at line 158 of file Association.inl.

◆ ContainsKey()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

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

Synonym for Lookup (key).has_value ()

Note: same as OccurrencesOf (key) != 0

Definition at line 163 of file Association.inl.

◆ OccurrencesOf()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

size_t Stroika::Foundation::Containers::Association< KEY_TYPE, MAPPED_VALUE_TYPE >::OccurrencesOf ( ArgByValueType< key_type > item ) const

OccurrencesOf() returns the number of occurrences of 'item' in the association.

Definition at line 168 of file Association.inl.

◆ ContainsMappedValue()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

template<Common::IEqualsComparer< MAPPED_VALUE_TYPE > VALUE_EQUALS_COMPARER = equal_to<MAPPED_VALUE_TYPE>>

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

Likely inefficient, 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 >

void Stroika::Foundation::Containers::Association< KEY_TYPE, MAPPED_VALUE_TYPE >::Add	(	ArgByValueType< key_type >	key,
		ArgByValueType< mapped_type >	newElt
	)

Add the association between key and newElt. Note, this increases teh size of the container by one, even if key was already present in the association.

Note: mutates container

Definition at line 180 of file Association.inl.

◆ AddAll()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

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

nonvirtual void Stroika::Foundation::Containers::Association< KEY_TYPE, MAPPED_VALUE_TYPE >::AddAll ( ITERABLE_OF_ADDABLE && items )

\summary Add all the argument (container or bound range of iterators) elements.

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

Note: AddAll () does not return the number of items added because all items are added (so the count can be made on the iterators/diff or items.size(); mutates container

◆ Remove()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

void Stroika::Foundation::Containers::Association< 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 212 of file Association.inl.

◆ RemoveIf()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

bool Stroika::Foundation::Containers::Association< 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 224 of file Association.inl.

◆ RemoveAll()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

void Stroika::Foundation::Containers::Association< 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 229 of file Association.inl.

◆ Update()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

void Stroika::Foundation::Containers::Association< 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 Association, 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 299 of file Association.inl.

◆ RetainAll()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

template<IIterableOfTo< KEY_TYPE > ITERABLE_OF_KEY_TYPE>

nonvirtual void Stroika::Foundation::Containers::Association< 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 Association to the argument data, but preserving any associations.

Note: Java comparison association.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 Association<> 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 = Association<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::Association< KEY_TYPE, MAPPED_VALUE_TYPE >::Where ( INCLUDE_PREDICATE && includeIfTrue ) const

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

Note: Alias - this could have been called 'Subset' - as it constructs a subset association (filtering on key or key-value pairs)

See also: Iterable<T>::Where

Example Usage: Association<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); }) == Association<int, int>{{2, 4}, {3, 5}, {5, 7}}));

EXPECT_TRUE ((m.Where ([](int key) { return Math::IsPrime (key); }) == Association<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::Association< KEY_TYPE, MAPPED_VALUE_TYPE >::WithKeys ( const CONTAINER_OF_KEYS & includeKeys ) const

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

Note: Alias - this could have been called 'Subset' - as it constructs a subset Association (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: Association<int, int> m{{1, 3}, {2, 4}, {3, 5}, {4, 5}, {5, 7}};

EXPECT_TRUE ((m.WithKeys ({2, 5}) == Association<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::Association< 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::Association< 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 448 of file Association.inl.

◆ operator==()

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

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

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

Note: since the order of iteration for an association is undefined, two associations maybe equal, but not enumerate out the same way.

Definition at line 468 of file Association.inl.

◆ Accumulate()

template<typename KEY_TYPE , typename MAPPED_VALUE_TYPE >

void Stroika::Foundation::Containers::Association< 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 402 of file Association.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

Constructor & Destructor Documentation

◆ Association()

Member Function Documentation

◆ Keys()

◆ MappedValues()

◆ LookupOne()

◆ LookupOneChecked()

◆ LookupOneValue()

◆ operator[]()

◆ ContainsKey()

◆ OccurrencesOf()

◆ ContainsMappedValue()

◆ Add()

◆ AddAll()

◆ Remove()

◆ RemoveIf()

◆ RemoveAll()

◆ Update()

◆ RetainAll()

◆ Where()

◆ WithKeys()

◆ As()

◆ _GetWritableRepAndPatchAssociatedIterator()

◆ operator==()

◆ Accumulate()