Flow 2.0.0
Flow project: Public API.
Public Types | Public Member Functions | Related Functions | List of all members
flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t > Class Template Reference

An object of this class is a map that combines the lookup speed of an unordered_set<> and ordering and iterator stability capabilities of a list<>. More...

#include <linked_hash_set.hpp>

Public Types

using Key = Key_t
 Convenience alias for template arg.
 
using Hash = Hash_t
 Convenience alias for template arg.
 
using Pred = Pred_t
 Convenience alias for template arg.
 
using Value = Key
 Short-hand for values, which in this case are simply the keys.
 
using size_type = std::size_t
 Expresses sizes/lengths of relevant things.
 
using difference_type = std::ptrdiff_t
 Type for difference of size_types.
 
using Const_iterator = typename Value_list::const_iterator
 Type for iterator pointing into an immutable structure of this type.
 
using Iterator = Const_iterator
 Type for iterator pointing into a mutable structure of this type but actually that is not possible; so alias to Const_iterator. More...
 
using Const_reverse_iterator = typename Value_list::const_reverse_iterator
 Type for reverse iterator pointing into an immutable structure of this type.
 
using Reverse_iterator = Const_reverse_iterator
 Type for reverse iterator pointing into a mutable structure of this type but actually that is not possible; so alias to Const_reverse_iterator. More...
 
using key_type = Key
 For container compliance (hence the irregular capitalization): Key type.
 
using value_type = Value
 For container compliance (hence the irregular capitalization): Value type.
 
using hasher = Hash
 For container compliance (hence the irregular capitalization): Hash type.
 
using key_equal = Pred
 For container compliance (hence the irregular capitalization): Pred type.
 
using pointer = Value *
 For container compliance (hence the irregular capitalization): pointer to Key type.
 
using const_pointer = const Value *
 For container compliance (hence the irregular capitalization): pointer to const Key type.
 
using reference = Value &
 For container compliance (hence the irregular capitalization): reference to Key type.
 
using const_reference = const Value &
 For container compliance (hence the irregular capitalization): reference to const Key type.
 
using iterator = Iterator
 For container compliance (hence the irregular capitalization): Iterator type.
 
using const_iterator = Const_iterator
 For container compliance (hence the irregular capitalization): Const_iterator type.
 

Public Member Functions

 Linked_hash_set (size_type n_buckets=size_type(-1), const Hash &hasher_obj=Hash{}, const Pred &pred=Pred{})
 Constructs empty structure with some basic parameters. More...
 
 Linked_hash_set (std::initializer_list< Value > values, size_type n_buckets=size_type(-1), const Hash &hasher_obj=Hash{}, const Pred &pred=Pred{})
 Constructs structure with some basic parameters, and values initialized from initializer list. More...
 
 Linked_hash_set (const Linked_hash_set &src)
 Constructs object that is a copy of the given source. More...
 
 Linked_hash_set (Linked_hash_set &&src)
 Constructs object by making it equal to the given source, while the given source becomes as-if default-cted. More...
 
Linked_hash_setoperator= (const Linked_hash_set &src)
 Overwrites this object with a copy of the given source. More...
 
Linked_hash_setoperator= (Linked_hash_set &&src)
 Overwrites this object making it identical to the given source, while the given source becomes as-if default-cted. More...
 
void swap (Linked_hash_set &other)
 Swaps the contents of this structure and other. More...
 
std::pair< Iterator, bool > insert (const Key &key)
 Attempts to insert (copying it) the given keyinto the map; if key already in *this makes no change. More...
 
std::pair< Iterator, bool > insert (Key &&key)
 Identical to the other overload, except that (if key not already present in *this) the key is moved, not copied, into *this. More...
 
Const_iterator find (const Key &key) const
 Attempts to find value at the given key in the map. More...
 
size_type count (const Key &key) const
 Returns the number of times a key equal to the given one is present (as-if via find()) in the map: either 1 or 0. More...
 
void touch (const Const_iterator &it)
 Given a valid iterator into the structure, makes the pointed-to element "newest" by moving it from wherever it is to be first in the iteration order. More...
 
bool touch (const Key &key)
 Given a key into the structure, makes the corresponding element "newest" by moving it from wherever it is to be first in the iteration order; or does nothing if no such key. More...
 
Const_iterator erase (const Const_iterator &it)
 Erases the element pointed to by the given valid iterator. More...
 
Const_iterator erase (const Const_iterator &it_newest, const Const_iterator &it_past_oldest)
 Erases all elements in the range [it_newest, it_past_oldest). More...
 
size_type erase (const Key &key)
 Erases the element with the given key, if it exists. More...
 
void clear ()
 Makes it so that size() == 0.
 
Iterator begin () const
 Synonym of newest(). More...
 
Iterator newest () const
 Returns first, a/k/a "newest," element's iterator (to immutable element, due to nature of this type). More...
 
Iterator end () const
 Synonym of past_oldest(). More...
 
Iterator past_oldest () const
 Returns one past last, a/k/a "oldest," element's iterator (to immutable element, due to nature of this type). More...
 
Const_iterator cbegin () const
 Synonym of const_newest(). More...
 
Const_iterator const_newest () const
 Returns first, a/k/a "newest," element's iterator (to immutable element). More...
 
Const_iterator cend () const
 Synonym of const_past_oldest(). More...
 
Const_iterator const_past_oldest () const
 Returns one past last, a/k/a "oldest," element's iterator (to immutable element). More...
 
Reverse_iterator rbegin () const
 Synonym of oldest(). More...
 
Reverse_iterator oldest () const
 Returns first, a/k/a "oldest," element's reverse iterator (to immutable element, due to nature of this type). More...
 
Reverse_iterator rend () const
 Synonym of past_newest(). More...
 
Reverse_iterator past_newest () const
 Returns one past last, a/k/a "newest," element's reverse iterator (to immutable element, due to nature of this type). More...
 
Const_reverse_iterator crbegin () const
 Synonym of const_oldest(). More...
 
Const_reverse_iterator const_oldest () const
 Returns first, a/k/a "oldest," element's reverse iterator (to immutable element). More...
 
Const_reverse_iterator crend () const
 Synonym of const_past_newest(). More...
 
Const_reverse_iterator const_past_newest () const
 Returns one past last, a/k/a "newest," element's reverse iterator (to immutable element). More...
 
bool empty () const
 Returns true if and only if container is empty. More...
 
size_type size () const
 Returns number of elements stored. More...
 
size_type max_size () const
 Returns max number of elements that can be stored. More...
 

Related Functions

(Note that these are not member functions.)

template<typename Key_t , typename Hash_t , typename Pred_t >
void swap (Linked_hash_set< Key_t, Hash_t, Pred_t > &val1, Linked_hash_set< Key_t, Hash_t, Pred_t > &val2)
 Equivalent to val1.swap(val2). More...
 

Detailed Description

template<typename Key_t, typename Hash_t, typename Pred_t>
class flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >

An object of this class is a map that combines the lookup speed of an unordered_set<> and ordering and iterator stability capabilities of a list<>.

This is just like Linked_hash_map, except it only stores keys – no mapped values. All comments, except for self-explanatory differences, from Linked_hash_map apply here. Thus I will only speak of differences below to avoid duplication of this header. Incidentally the most visible API difference (aside from having no Mappeds to speak of, only Keys) is that Linked_hash_set lacks (*this)[] operator; so one always uses insert() to insert.

Move semantics for keys are supported (let x be a *this):

The iterators are, really, list<Key> const-iterators; and as such are not invalidated except due to direct erasure of a given pointee.

Template Parameters
Key_tKey type. Same as for Linked_hash_map.
Hash_tHasher type. Same as for Linked_hash_map.
Pred_tEquality functor type. Same as for Linked_hash_map.

Member Typedef Documentation

◆ Iterator

template<typename Key_t , typename Hash_t , typename Pred_t >
using flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::Iterator = Const_iterator

Type for iterator pointing into a mutable structure of this type but actually that is not possible; so alias to Const_iterator.

Note these are standard semantics (see std::set, etc.).

◆ Reverse_iterator

template<typename Key_t , typename Hash_t , typename Pred_t >
using flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::Reverse_iterator = Const_reverse_iterator

Type for reverse iterator pointing into a mutable structure of this type but actually that is not possible; so alias to Const_reverse_iterator.

Note these are standard semantics (see std::set, etc.).

Constructor & Destructor Documentation

◆ Linked_hash_set() [1/4]

template<typename Key_t , typename Hash_t , typename Pred_t >
flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::Linked_hash_set ( size_type  n_buckets = size_type(-1),
const Hash hasher_obj = Hash{},
const Pred pred = Pred{} 
)

Constructs empty structure with some basic parameters.

Parameters
n_bucketsNumber of buckets for the unordered (hash) table. Special value -1 (default) will cause us to use whatever unordered_set<> would use by default.
hasher_objInstance of the hash function type (hasher_obj(k) -> size_t should be hash of Key k).
predInstance of the equality function type (pred(k1, k2) should return true if and only if the Keys are equal by value).

◆ Linked_hash_set() [2/4]

template<typename Key_t , typename Hash_t , typename Pred_t >
flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::Linked_hash_set ( std::initializer_list< Value values,
size_type  n_buckets = size_type(-1),
const Hash hasher_obj = Hash{},
const Pred pred = Pred{} 
)
explicit

Constructs structure with some basic parameters, and values initialized from initializer list.

The values are inserted as if insert(v) was called for each element v in values in reverse order. Since the canonical ordering places the newest (last inserted/touch()ed) element at the front of the ordering, that means that forward iteration through the set (right after this constructor runs) will yield values in the same order as in initializer list values.

Parameters
valuesValues with which to fill the structure after initializing it. Typically you'd provide a series of keys like this: { key1, key2, ... }. They will appear in iterated sequence in the same order as they appear in this list.
n_bucketsSee other constructor.
hasher_objSee other constructor.
predSee other constructor.

◆ Linked_hash_set() [3/4]

template<typename Key_t , typename Hash_t , typename Pred_t >
flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::Linked_hash_set ( const Linked_hash_set< Key_t, Hash_t, Pred_t > &  src)

Constructs object that is a copy of the given source.

Equivalent to default-ction followed by operator=(src).

Parameters
srcSource object.

◆ Linked_hash_set() [4/4]

template<typename Key_t , typename Hash_t , typename Pred_t >
flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::Linked_hash_set ( Linked_hash_set< Key_t, Hash_t, Pred_t > &&  src)

Constructs object by making it equal to the given source, while the given source becomes as-if default-cted.

Equivalent to default-ction followed by operator=(std::move(src)).

This is a constant-time operation.

Parameters
srcSource object which is emptied.

Member Function Documentation

◆ begin()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::begin

Synonym of newest().

Returns
See newest().

◆ cbegin()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Const_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::cbegin

Synonym of const_newest().

Exists as standard container method (hence the odd formatting).

Returns
See const_newest().

◆ cend()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Const_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::cend

Synonym of const_past_oldest().

Exists as standard container method (hence the odd formatting).

Returns
See const_past_oldest().

◆ const_newest()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Const_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::const_newest

Returns first, a/k/a "newest," element's iterator (to immutable element).

Returns
Ditto.

◆ const_oldest()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Const_reverse_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::const_oldest

Returns first, a/k/a "oldest," element's reverse iterator (to immutable element).

Returns
Ditto.

◆ const_past_newest()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Const_reverse_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::const_past_newest

Returns one past last, a/k/a "newest," element's reverse iterator (to immutable element).

Returns
Ditto.

◆ const_past_oldest()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Const_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::const_past_oldest

Returns one past last, a/k/a "oldest," element's iterator (to immutable element).

Returns
Ditto.

◆ count()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::size_type flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::count ( const Key key) const

Returns the number of times a key equal to the given one is present (as-if via find()) in the map: either 1 or 0.

Parameters
keyKey whose equal to find.
Returns
0 or 1.

◆ crbegin()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Const_reverse_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::crbegin

Synonym of const_oldest().

Returns
See const_oldest().

◆ crend()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Const_reverse_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::crend

Synonym of const_past_newest().

Exists as standard container method.

Returns
See const_past_newest().

◆ empty()

template<typename Key_t , typename Hash_t , typename Pred_t >
bool flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::empty

Returns true if and only if container is empty.

Same performance as of unordered_set<>.

Returns
Ditto.

◆ end()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::end

Synonym of past_oldest().

Exists as standard container method.

Returns
See past_oldest().

◆ erase() [1/3]

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::erase ( const Const_iterator it)

Erases the element pointed to by the given valid iterator.

Behavior undefined if it is not valid. it becomes invalid.

Parameters
itIterator of element to erase.
Returns
Iterator one position past (i.e., "older") than it, before *it was removed.

◆ erase() [2/3]

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::erase ( const Const_iterator it_newest,
const Const_iterator it_past_oldest 
)

Erases all elements in the range [it_newest, it_past_oldest).

Behavior undefined if a given iterator is invalid, or if the range is invalid. Corner case: an empty range is allowed; then this no-ops. Unless no-op, it_newest becomes invalid.

Parameters
it_newestIterator of first ("newest") element to erase.
it_past_oldestIterator of one past last ("oldest") element to erase.
Returns
it_past_oldest copy.

◆ erase() [3/3]

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::size_type flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::erase ( const Key key)

Erases the element with the given key, if it exists.

find(key) equivalent is performed first. Return value indicates whether it existed.

Parameters
keyKey such that its equal's (if found) element will be erased.
Returns
Number of elements erased (0 or 1).

◆ find()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Const_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::find ( const Key key) const

Attempts to find value at the given key in the map.

Key presence is determined identically to how it would be done in an unordered_set<Key_t, Hash_t, Pred_t>, with the particular Hash and Pred instances given to ctor (typically their default-cted instances, typically occupying no memory).

The returned iterator (if valid) cannot be used to mutate the key inside the map.

Parameters
keyKey whose equal to find.
Returns
If found, iterator to the key/mapped-value pair with the equivalent key; else this->end().

◆ insert() [1/2]

template<typename Key_t , typename Hash_t , typename Pred_t >
std::pair< typename Linked_hash_set< Key_t, Hash_t, Pred_t >::Iterator, bool > flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::insert ( const Key key)

Attempts to insert (copying it) the given keyinto the map; if key already in *this makes no change.

See also the overload which can avoid a copy and destructively move the key instead.

Return value indicates various info of interest about what occurred or did not occur. If inserted, the new element is considered "newest," as if by touch(). If not inserted, the existing element location is not affected (use touch() upon consulting the return value, if this is desirable).

Parameters
keyThe key to attempt to insert. A copy of this value is placed in *this.
Returns
A pair whose second element is true if and only if the insertion occurred; and whose first element is an iterator pointing to either the newly inserted element or already present one with a key equal to key.

◆ insert() [2/2]

template<typename Key_t , typename Hash_t , typename Pred_t >
std::pair< typename Linked_hash_set< Key_t, Hash_t, Pred_t >::Iterator, bool > flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::insert ( Key &&  key)

Identical to the other overload, except that (if key not already present in *this) the key is moved, not copied, into *this.

Parameters
keyThe key to attempt to insert (it is moved-from, if insertion occurs).
Returns
See other overload.

◆ max_size()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::size_type flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::max_size

Returns max number of elements that can be stored.

Same performance as of unordered_set<> + list<>.

Returns
Ditto.

◆ newest()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::newest

Returns first, a/k/a "newest," element's iterator (to immutable element, due to nature of this type).

Returns
Ditto.

◆ oldest()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Reverse_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::oldest

Returns first, a/k/a "oldest," element's reverse iterator (to immutable element, due to nature of this type).

Returns
Ditto.

◆ operator=() [1/2]

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t > & flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::operator= ( const Linked_hash_set< Key_t, Hash_t, Pred_t > &  src)

Overwrites this object with a copy of the given source.

We become equal to src but independent of it to a common-sense extent. In addition, the hasher instance and equality predicate are copied from src. Finally, a reasonable attempt is made to also make the internal structure of the hash map to be similar to that of `src.

Parameters
srcSource object. No-op if this == &src.
Returns
*this.

◆ operator=() [2/2]

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t > & flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::operator= ( Linked_hash_set< Key_t, Hash_t, Pred_t > &&  src)

Overwrites this object making it identical to the given source, while the given source becomes as-if default-cted.

This is a constant-time operation, plus whatever is the cost of this->clear() (linear in pre-op .size()).

Parameters
srcSource object which is emptied; except no-op if this == &src.
Returns
*this.

◆ past_newest()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Reverse_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::past_newest

Returns one past last, a/k/a "newest," element's reverse iterator (to immutable element, due to nature of this type).

Returns
Ditto.

◆ past_oldest()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::past_oldest

Returns one past last, a/k/a "oldest," element's iterator (to immutable element, due to nature of this type).

Returns
Ditto.

◆ rbegin()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Reverse_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::rbegin

Synonym of oldest().

Returns
See oldest().

◆ rend()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::Reverse_iterator flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::rend

Synonym of past_newest().

Exists as standard container method.

Returns
See past_newest().

◆ size()

template<typename Key_t , typename Hash_t , typename Pred_t >
Linked_hash_set< Key_t, Hash_t, Pred_t >::size_type flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::size

Returns number of elements stored.

Same performance as of unordered_set<>.

Returns
Ditto.

◆ swap()

template<typename Key_t , typename Hash_t , typename Pred_t >
void flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::swap ( Linked_hash_set< Key_t, Hash_t, Pred_t > &  other)

Swaps the contents of this structure and other.

This is a constant-time operation, as internal representations are swapped instead of any copy-assignment.

See also
The swap() free function. It is generally best (equivalent but covers more generic cases) to use the ADL-enabled swap(a, b) pattern instead of this member function. That is: using std::swap; ...; swap(a, b);. (Details are outside our scope here; but in short ADL will cause the right thing to happen.)
Parameters
otherThe other structure.

◆ touch() [1/2]

template<typename Key_t , typename Hash_t , typename Pred_t >
void flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::touch ( const Const_iterator it)

Given a valid iterator into the structure, makes the pointed-to element "newest" by moving it from wherever it is to be first in the iteration order.

Behavior undefined if iterator invalid.

The iterator continues to be valid.

Parameters
itIterator to an element of the structure.

◆ touch() [2/2]

template<typename Key_t , typename Hash_t , typename Pred_t >
bool flow::util::Linked_hash_set< Key_t, Hash_t, Pred_t >::touch ( const Key key)

Given a key into the structure, makes the corresponding element "newest" by moving it from wherever it is to be first in the iteration order; or does nothing if no such key.

find(key) equivalent is performed first. Return value indicates whether it was found.

Parameters
keyKey whose equal to find.
Returns
true if the key was found (even if it was already "newest"); false if not found.

Friends And Related Function Documentation

◆ swap()

template<typename Key_t , typename Hash_t , typename Pred_t >
void swap ( Linked_hash_set< Key_t, Hash_t, Pred_t > &  val1,
Linked_hash_set< Key_t, Hash_t, Pred_t > &  val2 
)
related

Equivalent to val1.swap(val2).

Parameters
val1Object.
val2Object.

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