Bijection allows for the bijective (1-1) association of two elements. More...

#include <Bijection.h>

Inheritance diagram for Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >:

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

Public Types
using	ArchetypeContainerType = Bijection

using	value_type = typename inherited::value_type

using	DomainEqualsCompareFunctionType = Common::ComparisonRelationDeclaration< Common::ComparisonRelationType::eEquals, function< bool(ArgByValueType< DomainType >, ArgByValueType< DomainType >)> >

using	RangeEqualsCompareFunctionType = Common::ComparisonRelationDeclaration< Common::ComparisonRelationType::eEquals, function< bool(RangeType, RangeType)> >

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
	Bijection ()

nonvirtual Iterable< DomainType >	Preimage () const

nonvirtual Iterable< RangeType >	Image () const

nonvirtual optional< RangeType >	Lookup (ArgByValueType< DomainType > key) const

nonvirtual RangeType	LookupValue (ArgByValueType< DomainType > key, ArgByValueType< RangeType > defaultValue=RangeType()) const

nonvirtual optional< DomainType >	InverseLookup (ArgByValueType< RangeType > key) const

nonvirtual DomainType	InverseLookupValue (ArgByValueType< RangeType > key, ArgByValueType< DomainType > defaultValue=DomainType()) const

nonvirtual Iterable< RangeType >	MapToRange (const Iterable< DomainType > &values) const

nonvirtual Iterable< DomainType >	MapToDomain (const Iterable< RangeType > &values) const

template<typename RESULT_CONTAINER = Bijection<DOMAIN_TYPE, RANGE_TYPE>, invocable< pair< DOMAIN_TYPE, RANGE_TYPE > > ELEMENT_MAPPER> requires (convertible_to<invoke_result_t<ELEMENT_MAPPER, pair<DOMAIN_TYPE, RANGE_TYPE>>, typename RESULT_CONTAINER::value_type> or convertible_to<invoke_result_t<ELEMENT_MAPPER, pair<DOMAIN_TYPE, RANGE_TYPE>>, optional<typename RESULT_CONTAINER::value_type>>)
nonvirtual RESULT_CONTAINER	Map (ELEMENT_MAPPER &&elementMapper) const
	'override' Iterable<>::Map () function so RESULT_CONTAINER defaults to Bijection, and improve that case to clone properties from this rep (such is rep type, etc).

template<derived_from< Iterable< pair< DOMAIN_TYPE, RANGE_TYPE > > > RESULT_CONTAINER = Bijection<DOMAIN_TYPE, RANGE_TYPE>, predicate< pair< DOMAIN_TYPE, RANGE_TYPE > > INCLUDE_PREDICATE>
nonvirtual RESULT_CONTAINER	Where (INCLUDE_PREDICATE &&includeIfTrue) const
	Like Iterable<T>::Where, but returning a bijection - subset of this bijection where includeIfTrue is true.

nonvirtual Bijection	WhereDomainIntersects (const Iterable< DomainType > &domainValues) const

nonvirtual Bijection	WhereRangeIntersects (const Iterable< RangeType > &rangeValues) const

nonvirtual bool	ContainsDomainElement (ArgByValueType< DomainType > key) const

nonvirtual bool	ContainsRangeElement (ArgByValueType< RangeType > v) const

nonvirtual void	Add (ArgByValueType< DomainType > key, ArgByValueType< RangeType > newElt)

template<IIterableOfTo< KeyValuePair< DOMAIN_TYPE, RANGE_TYPE > > CONTAINER_OF_KEYVALUE>
nonvirtual void	AddAll (const CONTAINER_OF_KEYVALUE &items)

nonvirtual void	Remove (const Iterator< value_type > &i, Iterator< value_type > *nextI=nullptr)

nonvirtual void	RemoveDomainElement (ArgByValueType< DomainType > d)

nonvirtual void	RemoveRangeElement (ArgByValueType< RangeType > r)

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

template<typename CONTAINER_PAIR_RANGE_DOMAIN >
nonvirtual CONTAINER_PAIR_RANGE_DOMAIN	As () const

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

nonvirtual void	clear ()

nonvirtual Iterator< value_type >	erase (const Iterator< value_type > &i)
	STL-ish alias for Remove ().

template<IIterableOfTo< KeyValuePair< DOMAIN_TYPE, RANGE_TYPE > > ITERABLE_OF_ADDABLE>
nonvirtual Bijection &	operator+= (const ITERABLE_OF_ADDABLE &items)

template<IIterableOfTo< KeyValuePair< DOMAIN_TYPE, RANGE_TYPE > > ITERABLE_OF_ADDABLE>
nonvirtual Bijection &	operator-= (const ITERABLE_OF_ADDABLE &items)

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 DOMAIN_TYPE, typename RANGE_TYPE>
class Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >

Bijection allows for the bijective (1-1) association of two elements.

Bijection allows for the bijective (1-1) association of two elements. This means that one element of the domain maps to exactly one element of the range, and that one element of the range maps uniquely to one element of the domain, and these mappings happen in a way that the mapping is fully invertible.

See also: http://en.wikipedia.org/wiki/Bijection

Design Notes:

Note: We used Iterable<pair<DOMAIN_TYPE,RANGE_TYPE>> instead of Iterable<KeyValuePairType<DOMAIN_TYPE,RANGE_TYPE>> because its completely symmetric - both directions the values are keys.; Thread-Safety C++-Standard-Thread-Safety; Bijection could not inherit from Mapping<> because the semantics of Removing a value are incompatible, and because (depending on the policy we adopt about error checking for invalid value in add) - we can have legit behavior on a Mapping BE illegal on the Bijection<>

Concrete Implementations: o

See also: Concrete::Bijection_LinkedList<>

Factory:

See also: Bijection_Factory<> to see default implementations.

Note: See ReadMe.md for common features of all Stroika containers (especially constructors, iterators, etc); Container Element comparisons: See about ElementInOrderComparerType, ElementThreeWayComparerType and GetElementThreeWayComparer etc; Comparisons: o static_assert (equality_comparable<Bijection<...>>);

o All Bijections MUST have = comparable DOMAIN_TYPE and RANGE_TYPE, so operator== for the bijection is well-defined.

Two Bijections are considered equal if they contain the same elements (Preimage) 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 Bijections to
be equal. There is no need for the backends to be of the same underlying representation either (STL map
vers linked-list).

Since a Bijection is not necessarily sorted, or in any particular order, < and > are not well defined.

Definition at line 103 of file Bijection.h.

Member Typedef Documentation

◆ ArchetypeContainerType

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

using Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::ArchetypeContainerType = Bijection

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

Definition at line 114 of file Bijection.h.

◆ value_type

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

using Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::value_type = typename inherited::value_type

See also: inherited::value_type

Definition at line 120 of file Bijection.h.

◆ DomainEqualsCompareFunctionType

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

using Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::DomainEqualsCompareFunctionType = Common::ComparisonRelationDeclaration<Common::ComparisonRelationType::eEquals, function<bool (ArgByValueType<DomainType>, ArgByValueType<DomainType>)> >

This is the type returned by GetDomainEqualsComparer () and CAN be used as the argument to a Bijection<> as EqualityComparer, but we allow any template in the Bijection<> CTOR for an equalityComparer that follows the Common::IEqualsComparer concept.

Definition at line 137 of file Bijection.h.

◆ RangeEqualsCompareFunctionType

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

using Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::RangeEqualsCompareFunctionType = Common::ComparisonRelationDeclaration<Common::ComparisonRelationType::eEquals, function<bool (RangeType, RangeType)> >

This is the type returned by GetRangeEqualsComparer () and CAN be used as the argument to a Bijection<> as EqualityComparer, but we allow any template in the Bijection<> CTOR for an equalityComparer that follows the IEqualsComparer concept

Definition at line 146 of file Bijection.h.

Constructor & Destructor Documentation

◆ Bijection()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >
requires (IEqualsComparer<equal_to<DOMAIN_TYPE>, DOMAIN_TYPE> and IEqualsComparer<equal_to<RANGE_TYPE>, RANGE_TYPE>)

Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::Bijection ( )

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

The underlying data structure of the Bijection is defined by

See also: Factory::Bijection_Factory<>

Note: The constructor arguments DOMAIN_EQUALS_COMPARER or RANGE_EQUALS_COMPARER must be declared to be equals_comparers, to avoid ambiguity/accidental mix-ups between inorder and equals (or three way) comparers. Consider wrapping lambdas with Common::DeclareEqualsComparer; See general information about container constructors that applies here

Definition at line 32 of file Bijection.inl.

Member Function Documentation

◆ Preimage()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

Iterable< DOMAIN_TYPE > Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::Preimage ( ) const

Preimage () returns an Iterable object with just the domain (first) part of the Bijection.

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).

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.

Definition at line 135 of file Bijection.inl.

◆ Image()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

Iterable< RANGE_TYPE > Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::Image ( ) const

Image () returns an Iterable object with just the range part of the Bijection.

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

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 (https://msdn.microsoft.com/en-us/library/ekcfxy3x(v=vs.110).aspx) returns a live reference to the underlying values. 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.

Definition at line 142 of file Bijection.inl.

◆ Lookup()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

optional< RANGE_TYPE > Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::Lookup ( ArgByValueType< DomainType > 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: returm 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, RangeType* value) - is equivalent to .Net TryGetValue ()

See also: LookupValue (); InverseLookup (); InverseLookupValue ()

Definition at line 169 of file Bijection.inl.

◆ LookupValue()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

RANGE_TYPE Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::LookupValue	(	ArgByValueType< DomainType >	key,
		ArgByValueType< RangeType >	defaultValue = `RangeType ()`
	)		const

Always safe to call. If result empty/missing, returns argument 'default' or 'sentinel' value.

See also: Lookup (); InverseLookup (); InverseLookupValue ()

Definition at line 182 of file Bijection.inl.

◆ InverseLookup()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

optional< DOMAIN_TYPE > Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::InverseLookup ( ArgByValueType< RangeType > key ) const

Note - as since InverseLookup/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: returm m.InverseLookup (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());

See also: Lookup (); LookupValue (); InverseLookupValue ()

Definition at line 208 of file Bijection.inl.

◆ InverseLookupValue()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

DOMAIN_TYPE Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::InverseLookupValue	(	ArgByValueType< RangeType >	key,
		ArgByValueType< DomainType >	defaultValue = `DomainType ()`
	)		const

Always safe to call. If result empty/missing, returns argument 'default' or 'sentinel' value.

See also: Lookup (); LookupValue (); InverseLookup ()

Definition at line 221 of file Bijection.inl.

◆ MapToRange()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

auto Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::MapToRange ( const Iterable< DomainType > & values ) const

For each value in the source set, map it back using the bijection to the target set.

Precondition: that each element be present in the bijection

Definition at line 227 of file Bijection.inl.

◆ MapToDomain()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

auto Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::MapToDomain ( const Iterable< RangeType > & values ) const

For each value in the source set, map it back using the bijection to the target set.

Precondition: that each element be present in the bijection

Definition at line 237 of file Bijection.inl.

◆ WhereDomainIntersects()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

auto Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::WhereDomainIntersects ( const Iterable< DomainType > & domainValues ) const

essentially 'intersect but just comparing domain'

Definition at line 275 of file Bijection.inl.

◆ WhereRangeIntersects()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

auto Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::WhereRangeIntersects ( const Iterable< RangeType > & rangeValues ) const

essentially 'intersect but just comparing range'

Definition at line 288 of file Bijection.inl.

◆ ContainsDomainElement()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

bool Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::ContainsDomainElement ( ArgByValueType< DomainType > key ) const

Synonym for (Lookup (v).has_value ()) or Preimage ().Contains (v)

Definition at line 301 of file Bijection.inl.

◆ ContainsRangeElement()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

bool Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::ContainsRangeElement ( ArgByValueType< RangeType > v ) const

Synonym for (InverseLookup (v).has_value ()) or Image ().Contains (v)

Definition at line 306 of file Bijection.inl.

◆ Add()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

void Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::Add	(	ArgByValueType< DomainType >	key,
		ArgByValueType< RangeType >	newElt
	)

Add the association between key and newElt. If key was already associated with something else, the association is silently updated, and the size of the iterable does not change. 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: mutates container

Definition at line 317 of file Bijection.inl.

◆ AddAll()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

template<IIterableOfTo< KeyValuePair< DOMAIN_TYPE, RANGE_TYPE > > CONTAINER_OF_KEYVALUE>

nonvirtual void Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::AddAll ( const CONTAINER_OF_KEYVALUE & items )

@aliases .net AddRange ()

Note: mutates container

◆ Remove()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

void Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::Remove	(	const Iterator< value_type > &	i,
		Iterator< value_type > *	nextI = `nullptr`
	)

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 365 of file Bijection.inl.

◆ RemoveDomainElement()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

void Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::RemoveDomainElement ( ArgByValueType< DomainType > d )

This removes any mapping from 'd' to anything. It is not an error if 'd' isn not already in the domain.

Note: mutates container

Definition at line 355 of file Bijection.inl.

◆ RemoveRangeElement()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

void Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::RemoveRangeElement ( ArgByValueType< RangeType > r )

This removes any mapping from anything to 'r'. It is not an error if 'r' isn not already in the range.

Note: mutates container

Definition at line 360 of file Bijection.inl.

◆ RemoveAll()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

void Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_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.

Note: mutates container

Definition at line 372 of file Bijection.inl.

◆ As()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

template<typename CONTAINER_PAIR_RANGE_DOMAIN >

nonvirtual CONTAINER_PAIR_RANGE_DOMAIN Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::As ( ) const

This function should work for any container which accepts (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<pair<DomainType,RangeType>>, map<DomainType,RangeType>, vector<pair<DomainType,RangeType>>, etc...

This works for: o Mapping<DOMAIN_TYPE, RANGE_TYPE> o map<DOMAIN_TYPE, RANGE_TYPE> o vector<pair<DOMAIN_TYPE, RANGE_TYPE>> o Sequence<pair<DOMAIN_TYPE, RANGE_TYPE>>

◆ operator==()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

bool Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::operator== ( const Bijection< DOMAIN_TYPE, RANGE_TYPE > & rhs ) const

Note - this computation MAYBE very expensive, and not optimized (maybe do better in a future release - see TODO).

Note: Not to be confused with EqualityComparerType and GetEqualsComparer () which compares ELEMENTS of Bijection<> for equality.

Definition at line 466 of file Bijection.inl.

◆ clear()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

void Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::clear ( )

Aliases: RemoveAll ().

Note: mutates container

Definition at line 420 of file Bijection.inl.

◆ erase()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

auto Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::erase ( const Iterator< value_type > & i )

STL-ish alias for Remove ().

Note: mutates container

Definition at line 425 of file Bijection.inl.

◆ operator+=()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

template<IIterableOfTo< KeyValuePair< DOMAIN_TYPE, RANGE_TYPE > > ITERABLE_OF_ADDABLE>

nonvirtual Bijection & Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::operator+= ( const ITERABLE_OF_ADDABLE & items )

Note: mutates container

◆ operator-=()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

template<IIterableOfTo< KeyValuePair< DOMAIN_TYPE, RANGE_TYPE > > ITERABLE_OF_ADDABLE>

nonvirtual Bijection & Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_TYPE >::operator-= ( const ITERABLE_OF_ADDABLE & items )

Note: mutates container

◆ _GetWritableRepAndPatchAssociatedIterator()

template<typename DOMAIN_TYPE , typename RANGE_TYPE >

auto Stroika::Foundation::Containers::Bijection< DOMAIN_TYPE, RANGE_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 446 of file Bijection.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

◆ DomainEqualsCompareFunctionType

◆ RangeEqualsCompareFunctionType

Constructor & Destructor Documentation

◆ Bijection()

Member Function Documentation

◆ Preimage()

◆ Image()

◆ Lookup()

◆ LookupValue()

◆ InverseLookup()

◆ InverseLookupValue()

◆ MapToRange()

◆ MapToDomain()

◆ WhereDomainIntersects()

◆ WhereRangeIntersects()

◆ ContainsDomainElement()

◆ ContainsRangeElement()

◆ Add()

◆ AddAll()

◆ Remove()

◆ RemoveDomainElement()

◆ RemoveRangeElement()

◆ RemoveAll()

◆ As()

◆ operator==()

◆ clear()

◆ erase()

◆ operator+=()

◆ operator-=()

◆ _GetWritableRepAndPatchAssociatedIterator()