a cross between Mapping<KEY, T> and Collection<T> and Set<T> More...

#include <KeyedCollection.h>

Inheritance diagram for Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >:

Classes
class	_IRep
	Implementation detail for KeyedCollection<KEY_TYPE, T, TRAITS> implementors. More...

struct	EqualsComparer

Public Types
using	value_type = typename inherited::value_type

using	TraitsType = TRAITS

using	ArchetypeContainerType = KeyedCollection

using	KeyExtractorType = typename TRAITS::KeyExtractorType

using	KeyEqualityComparerType = 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
template<IEqualsComparer< KEY_TYPE > KEY_EQUALS_COMPARER = equal_to<KEY_TYPE>> requires (IKeyedCollection_ExtractorCanBeDefaulted<T, KEY_TYPE, TRAITS>)
	KeyedCollection (KEY_EQUALS_COMPARER &&keyComparer=KEY_EQUALS_COMPARER{})

nonvirtual KeyExtractorType	GetKeyExtractor () const

nonvirtual KeyEqualityComparerType	GetKeyEqualityComparer () const

nonvirtual Iterable< KeyType >	Keys () const

nonvirtual bool	Contains (ArgByValueType< KeyType > item) const

nonvirtual optional< value_type >	Lookup (ArgByValueType< KeyType > key) const

template<typename THROW_IF_MISSING >
nonvirtual value_type	LookupChecked (ArgByValueType< KeyType > key, THROW_IF_MISSING &&throwIfMissing) const

nonvirtual value_type	LookupValue (ArgByValueType< KeyType > key, ArgByValueType< value_type > defaultValue=value_type{}) const

nonvirtual bool	Add (ArgByValueType< value_type > item)

template<IInputIterator< T > ITERATOR_OF_ADDABLE, sentinel_for< remove_cvref_t< ITERATOR_OF_ADDABLE > > ITERATOR_OF_ADDABLE2>
nonvirtual unsigned int	AddAll (ITERATOR_OF_ADDABLE &&start, ITERATOR_OF_ADDABLE2 &&end)

nonvirtual void	Remove (const Iterator< value_type > &i, const Iterator< value_type > *nextI=nullptr)
	Remove the argument value (which must exist) from the KeyedCollection.

nonvirtual bool	RemoveIf (ArgByValueType< KeyType > item)

template<IInputIterator< T > ITERATOR_OF_ADDABLE>
nonvirtual size_t	RemoveAll (ITERATOR_OF_ADDABLE &&start, ITERATOR_OF_ADDABLE &&end)
	RemoveAll removes all, or all matching (predicate, iterator range, equals comparer or whatever) items.

template<typename RESULT_CONTAINER = KeyedCollection<T, KEY_TYPE, TRAITS>, 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
	'override' Iterable<>::Map () function so RESULT_CONTAINER defaults to KeyedCollection, and improve that case to clone properties from this rep (such is rep type, extractor etc).

template<derived_from< Iterable< T > > RESULT_CONTAINER = KeyedCollection<T, KEY_TYPE, TRAITS>, predicate< T > INCLUDE_PREDICATE>
nonvirtual RESULT_CONTAINER	Where (INCLUDE_PREDICATE &&includeIfTrue) const

nonvirtual bool	operator== (const KeyedCollection &rhs) const

nonvirtual KeyedCollection &	operator+= (ArgByValueType< value_type > item)

nonvirtual KeyedCollection &	operator-= (ArgByValueType< value_type > item)

nonvirtual void	clear ()

nonvirtual void	erase (ArgByValueType< value_type > item)

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 T, typename KEY_TYPE, typename TRAITS = KeyedCollection_DefaultTraits<T, KEY_TYPE>>
class Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >

a cross between Mapping<KEY, T> and Collection<T> and Set<T>

KeyedCollection adds most access patterns used in Mapping to a Collection, but stores only a single
object. The idea is to have the ID (from a Mapping<ID,Obj>) stored directly in the 'Obj', but still
be able to do lookups based on the ID.

This can also be thought of as much like a Set<T> - where the element T has a known KEY field.
You could easily make a Set<T> like this, but then lookups would require you passed in a 'T' instead
of just the Key. That lookup by key is basically the 'feature' that KeyedCollection provides.

Note: Considered using Set<T> (to avoid using this concept) with helper mkComparerByIDExtract. auto Set<T>::mkComparerByIDExtract (const function<ID (T)>& idExtractor) -> ElementEqualityComparerType { return [idExtractor] (const T& lhs, const T& rhs) { return idExtractor (lhs) == idExtractor (rhs); }; } This is close (for adding/removing items works fine). But - you need to be able to lookup items by ID, and that required forcing the type T to be constructible just from an ID (awkward and potentially expensive).; you can only Add a T/value_type, not a KEY_TYPE, but 'lookup-style' operations can operate on KEY_TYPE.; Not based on, but useful to refer to .Net KeyedCollection<KEY,T>

See also: https://msdn.microsoft.com/en-us/library/ms132438%28v=vs.110%29.aspx?f=255&MSPPError=-2147217396

Note: Important that KeyedCollection<>::Add () will REPLACE the value, unlike with set.

Concrete Implementations: o

See also: Concrete::KeyedCollection_Array<> o; Concrete::KeyedCollection_LinkedList<> o; Concrete::KeyedCollection_stdhashset<> o; Concrete::SortedKeyedCollection_stdset<> o; Concrete::SortedKeyedCollection_SkipList<>

Factory:

See also: Concrete::KeyedCollection_Factory<> to see default implementations.

Note: Container Element comparisons: See about ElementInOrderComparerType, ElementThreeWayComparerType and GetElementThreeWayComparer etc; Design Choice: Could either embed the 'extractor' function in the container type TRAITS or passed in as a constructor argument to the container. As-part-of-TRAITS: Logically cannot change for a given container type, so unambiguous how stuff pulled out of T (extractor etc) THis makes the most sense, but its inconvenient in usage. As constructor argument to container: This might appear slightly more loosie goosy - but no more so than having different comparers for Set<T>. And its more convenient in use/practice.; See ReadMe.md for common features of all Stroika containers (especially constructors, iterators, etc)

TODO:

Definition at line 146 of file KeyedCollection.h.

Member Typedef Documentation

◆ value_type

template<typename T , typename KEY_TYPE , typename TRAITS = KeyedCollection_DefaultTraits<T, KEY_TYPE>>

using Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::value_type = typename inherited::value_type

See also: inherited::value_type - this is 'T' (not KEY_TYPE)

Definition at line 158 of file KeyedCollection.h.

◆ TraitsType

template<typename T , typename KEY_TYPE , typename TRAITS = KeyedCollection_DefaultTraits<T, KEY_TYPE>>

using Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::TraitsType = TRAITS

Just a short-hand for the 'TRAITS' part of KeyedCollection<T,KEY_TYPE,TRAITS>. This is often handy to use in building other templates.

Definition at line 165 of file KeyedCollection.h.

◆ ArchetypeContainerType

template<typename T , typename KEY_TYPE , typename TRAITS = KeyedCollection_DefaultTraits<T, KEY_TYPE>>

using Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::ArchetypeContainerType = KeyedCollection

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

Definition at line 171 of file KeyedCollection.h.

◆ KeyExtractorType

template<typename T , typename KEY_TYPE , typename TRAITS = KeyedCollection_DefaultTraits<T, KEY_TYPE>>

using Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::KeyExtractorType = typename TRAITS::KeyExtractorType

This is the type of the 'extractor' function, which can be static (so occupy no space) but defaults to function<KEY_TYPE (ArgByValueType<T>)>> - specified in the TRAITS argument to KeyedCollection<>

Definition at line 188 of file KeyedCollection.h.

◆ KeyEqualityComparerType

template<typename T , typename KEY_TYPE , typename TRAITS = KeyedCollection_DefaultTraits<T, KEY_TYPE>>

using Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::KeyEqualityComparerType = Common::ComparisonRelationDeclaration<Common::ComparisonRelationType::eEquals, function<bool (ArgByValueType<KEY_TYPE>, ArgByValueType<KEY_TYPE>)> >

Note

See also: also EqualsComparer{} to compare whole KeyedCollection<>s

Definition at line 195 of file KeyedCollection.h.

Constructor & Destructor Documentation

◆ KeyedCollection()

template<typename T , typename KEY_TYPE , typename TRAITS >
requires (IKeyedCollection_ExtractorCanBeDefaulted<T, KEY_TYPE, TRAITS>)

template<IEqualsComparer< KEY_TYPE > KEY_EQUALS_COMPARER>
requires (IKeyedCollection_ExtractorCanBeDefaulted<T, KEY_TYPE, TRAITS>)

Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::KeyedCollection ( KEY_EQUALS_COMPARER && keyComparer = KEY_EQUALS_COMPARER{} )

For the CTOR overload with ITERABLE_OF_ADDABLE, its anything that supports c.begin(), c.end () to find all the elements and for which the result of c.begin ().

All constructors either copy their source comparer (copy/move CTOR), or use the provided argument comparer (which in turn defaults to equal_to<T>).

If TRAITS (TraitsType) has a valid default extractor, enable certain constructors.

Note: For efficiency sake, the base constructor takes a templated EQUALS_COMPARER (avoiding translation to function<bool(T,T)>> so the REP can see the actual type, but the container API itself erases this specific type using std::function.

Precondition: EqualsComparer<KEY_TYPE> KEY_EQUALS_COMPARER - for constructors with that type parameter

Example Usage: struct T1 {

int key;

int value;

};

struct T1_Key_Extractor {

int operator() (const T1& t) const { return t.key; };

};

using T1_Traits = KeyedCollection_DefaultTraits<T1, int, T1_Key_Extractor>;

KeyedCollection<T1, int> kc1 {[] (T1 e) { return e.key; }}; // specify extractor explicitly

KeyedCollection<T1, int, T1_Traits> kc2 {[] (T1 e) { return e.key; }};

KeyedCollection<T1, int, T1_Traits> kc3{}; // get the extractor from the TRAITS

Note: The constructor argument KEY_EQUALS_COMPARER must be declared to be an equals_comparers to avoid ambiguity/accidental mixups between inorder and equals (or three way) comparers. Consider wrapping lambdas with Common::DeclareEqualsComparer

Example Usage: KeyedCollection<DiskInfoType, filesystem::path> result{[] (DiskInfoType e) { return e.fDeviceName; }};

Stroika::Foundation::Containers::KeyedCollection
a cross between Mapping<KEY, T> and Collection<T> and Set<T>
Definition KeyedCollection.h:146

Note: See general information about container constructors that applies here

Definition at line 23 of file KeyedCollection.inl.

Member Function Documentation

◆ GetKeyExtractor()

template<typename T , typename KEY_TYPE , typename TRAITS >

auto Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::GetKeyExtractor ( ) const

Returns the extractor.

Definition at line 125 of file KeyedCollection.inl.

◆ GetKeyEqualityComparer()

template<typename T , typename KEY_TYPE , typename TRAITS >

auto Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::GetKeyEqualityComparer ( ) const

Returns the key equality comparer (but wrapped as a function<> object, so perhaps slightly less efficient to use than the type passed in via CTOR). Actually - could be MUCH less efficient if what was passed in was less<T> for example, an ordered comparer, and that gets mapped to an equality comparer. But this will work.

Definition at line 130 of file KeyedCollection.inl.

◆ Keys()

template<typename T , typename KEY_TYPE , typename TRAITS >

Iterable< KEY_TYPE > Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::Keys ( ) const

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

Note this method may not return a collection which is sorted. Note also, the returned value is a copy of the keys (by value) - at least logically (implementations maybe smart enough to use lazy copying).

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: Values ()

Definition at line 135 of file KeyedCollection.inl.

◆ Contains()

template<typename T , typename KEY_TYPE , typename TRAITS >

bool Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::Contains ( ArgByValueType< KeyType > item ) const

Note: Contains (T) is same as Contains (KeyExtractor(t)) - it only looks at the key, not the rest of the value

Definition at line 140 of file KeyedCollection.inl.

◆ Lookup()

template<typename T , typename KEY_TYPE , typename TRAITS >

auto Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::Lookup ( ArgByValueType< KeyType > key ) const

Like Contains - but a Set<> can use a comparison that only examines a part of T, making it useful to be able to return the rest of T.

Definition at line 151 of file KeyedCollection.inl.

◆ LookupChecked()

template<typename T , typename KEY_TYPE , typename TRAITS = KeyedCollection_DefaultTraits<T, KEY_TYPE>>

template<typename THROW_IF_MISSING >

nonvirtual value_type Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::LookupChecked	(	ArgByValueType< KeyType >	key,
		THROW_IF_MISSING &&	throwIfMissing
	)		const

Aliases: LookupOrException

◆ LookupValue()

template<typename T , typename KEY_TYPE , typename TRAITS >

auto Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::LookupValue	(	ArgByValueType< KeyType >	key,
		ArgByValueType< value_type >	defaultValue = `value_type{}`
	)		const

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

Aliases: LookupOrDefault

Definition at line 203 of file KeyedCollection.inl.

◆ Add()

template<typename T , typename KEY_TYPE , typename TRAITS >

bool Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::Add ( ArgByValueType< value_type > item )

Add when T is already present has may have no effect (logically has no effect) on the container (not an error or exception) (except that if T contains fields not part of comparison, those will be updated).

So for a user-defined type T (or any type where the caller specifies the compare function) it is left undefined whether or not the new (not included) attributes associated with the added item make it into the Set.

return true if new item, and false if simply updated

Note: - because Add and Update logic are identical, KeyedCollection<> has no explicit Update (iterator) method. it COULD someday add an overload with optional Iterator<> hint argument, like in STL; mutates container

Definition at line 209 of file KeyedCollection.inl.

◆ AddAll()

template<typename T , typename KEY_TYPE , typename TRAITS = KeyedCollection_DefaultTraits<T, KEY_TYPE>>

template<IInputIterator< T > ITERATOR_OF_ADDABLE, sentinel_for< remove_cvref_t< ITERATOR_OF_ADDABLE > > ITERATOR_OF_ADDABLE2>

nonvirtual unsigned int Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::AddAll	(	ITERATOR_OF_ADDABLE &&	start,
		ITERATOR_OF_ADDABLE2 &&	end
	)

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

Returns the number if items actually added (not necessarily same as end-start)

Note: mutates container

◆ Remove()

template<typename T , typename KEY_TYPE , typename TRAITS >

void Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::Remove	(	const Iterator< value_type > &	i,
		const Iterator< value_type > *	nextI = `nullptr`
	)

Remove the argument value (which must exist) from the KeyedCollection.

See also: RemoveIf () for when the argument might not exist

Note: mutates container

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)

Definition at line 253 of file KeyedCollection.inl.

◆ RemoveIf()

template<typename T , typename KEY_TYPE , typename TRAITS >

bool Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::RemoveIf ( ArgByValueType< KeyType > item )

RemoveIf item if present. Whether present or not it does the same thing and assures the item is no longer present, but returns true iff the call made a change (removed the item).

Note - we chose to return true in the case of removal because this is the case most likely when a caller would want to take action.

Example Usage: if (s.RemoveIf (n)) {

write_to_disk(n);

}

See also: Remove ()

Note: mutates container

Definition at line 260 of file KeyedCollection.inl.

◆ RemoveAll()

template<typename T , typename KEY_TYPE , typename TRAITS = KeyedCollection_DefaultTraits<T, KEY_TYPE>>

template<IInputIterator< T > ITERATOR_OF_ADDABLE>

nonvirtual size_t Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::RemoveAll	(	ITERATOR_OF_ADDABLE &&	start,
		ITERATOR_OF_ADDABLE &&	end
	)

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.

Note: mutates container

◆ Where()

template<typename T , typename KEY_TYPE , typename TRAITS = KeyedCollection_DefaultTraits<T, KEY_TYPE>>

template<derived_from< Iterable< T > > RESULT_CONTAINER = KeyedCollection<T, KEY_TYPE, TRAITS>, predicate< T > INCLUDE_PREDICATE>

nonvirtual RESULT_CONTAINER Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::Where ( INCLUDE_PREDICATE && includeIfTrue ) const

Apply the function function to each element, and return all the ones for which it was true.

Aliases: Subset - as it constructs a subset.

See also: Iterable<T>::Where

◆ operator==()

template<typename T , typename KEY_TYPE , typename TRAITS >

bool Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::operator== ( const KeyedCollection< T, KEY_TYPE, TRAITS > & rhs ) const

Simply indirect to KeyedCollection<>::EqualsComparer

Definition at line 345 of file KeyedCollection.inl.

◆ operator+=()

template<typename T , typename KEY_TYPE , typename TRAITS >

KeyedCollection< T, KEY_TYPE, TRAITS > & Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::operator+= ( ArgByValueType< value_type > item )

Synonym for Add/AddAll.

Design note use Addll/RemoveAll() for CONTAINER variant - since can easily lead to ambiguity/confusion

Note: mutates container

Definition at line 355 of file KeyedCollection.inl.

◆ operator-=()

template<typename T , typename KEY_TYPE , typename TRAITS >

KeyedCollection< T, KEY_TYPE, TRAITS > & Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::operator-= ( ArgByValueType< value_type > item )

Synonym for Remove/RemoveAll.

Design note use Addll/RemoveAll() for CONTAINER variant - since can easily lead to ambiguity/confusion

Note: mutates container

Definition at line 367 of file KeyedCollection.inl.

◆ clear()

template<typename T , typename KEY_TYPE , typename TRAITS >

void Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::clear ( )

Aliases: RemoveAll ().

Note: mutates container

Definition at line 379 of file KeyedCollection.inl.

◆ erase()

template<typename T , typename KEY_TYPE , typename TRAITS >

void Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::erase ( ArgByValueType< value_type > item )

Aliases: Remove ().

Note: mutates container

Definition at line 384 of file KeyedCollection.inl.

◆ _GetWritableRepAndPatchAssociatedIterator()

template<typename T , typename KEY_TYPE , typename TRAITS >

auto Stroika::Foundation::Containers::KeyedCollection< T, KEY_TYPE, TRAITS >::_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 396 of file KeyedCollection.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

◆ value_type

◆ TraitsType

◆ ArchetypeContainerType

◆ KeyExtractorType

◆ KeyEqualityComparerType

Constructor & Destructor Documentation

◆ KeyedCollection()

Member Function Documentation

◆ GetKeyExtractor()

◆ GetKeyEqualityComparer()

◆ Keys()

◆ Contains()

◆ Lookup()

◆ LookupChecked()

◆ LookupValue()

◆ Add()

◆ AddAll()

◆ Remove()

◆ RemoveIf()

◆ RemoveAll()

◆ Where()

◆ operator==()

◆ operator+=()

◆ operator-=()

◆ clear()

◆ erase()

◆ _GetWritableRepAndPatchAssociatedIterator()