gum::HashTableConstIterator< Key, Val > Class Template Reference

Unsafe Const Iterators for hashtablesHashTableConstIterator provides a fast but unsafe way to parse HashTables. More...

#include <agrum/tools/core/hashTable.h>

Inheritance diagram for gum::HashTableConstIterator< Key, Val >:

Collaboration diagram for gum::HashTableConstIterator< Key, Val >:

Public Member Functions
template<typename Alloc >
INLINE	HashTableConstIterator (const HashTable< Key, Val, Alloc > &tab) noexcept
Constructors / Destructors
	HashTableConstIterator () noexcept
	Basic constructor: creates an iterator pointing to nothing. More...
template<typename Alloc >
	HashTableConstIterator (const HashTable< Key, Val, Alloc > &tab) noexcept
	Constructor for an iterator pointing to the first element of a hashtable. More...
template<typename Alloc >
	HashTableConstIterator (const HashTable< Key, Val, Alloc > &tab, Size ind_elt)
	Constructor for an iterator pointing to the nth element of a hashtable. More...
	HashTableConstIterator (const HashTableConstIterator< Key, Val > &from) noexcept
	Copy constructor. More...
	HashTableConstIterator (HashTableConstIterator< Key, Val > &&from) noexcept
	Move constructor. More...
	~HashTableConstIterator () noexcept
	Class destructor. More...
Accessors / Modifiers
const key_type &	key () const
	Returns the key corresponding to the element pointed to by the iterator. More...
const mapped_type &	val () const
	Returns the mapped value pointed to by the iterator. More...
void	clear () noexcept
	Makes the iterator point toward nothing (in particular, it is not related anymore to its current hash table). More...
Operators
HashTableConstIterator< Key, Val > &	operator= (const HashTableConstIterator< Key, Val > &from) noexcept
	Copy operator. More...
HashTableConstIterator< Key, Val > &	operator= (HashTableConstIterator< Key, Val > &&from) noexcept
	Move operator. More...
HashTableConstIterator< Key, Val > &	operator++ () noexcept
	Makes the iterator point to the next element in the hash table. More...
HashTableConstIterator< Key, Val > &	operator+= (Size i) noexcept
	Makes the iterator point to i elements further in the hashtable. More...
HashTableConstIterator< Key, Val >	operator+ (Size i) const noexcept
	Returns a new iterator pointing to i elements further in the hashtable. More...
bool	operator!= (const HashTableConstIterator< Key, Val > &from) const noexcept
	Checks whether two iterators are pointing toward different elements. More...
bool	operator== (const HashTableConstIterator< Key, Val > &from) const noexcept
	Checks whether two iterators are pointing toward equal elements. More...
const value_type &	operator* () const
	Returns the value pointed to by the iterator. More...

Public Types
using	iterator_category = std::forward_iterator_tag
	Types for STL compliance. More...
using	key_type = Key
	Types for STL compliance. More...
using	mapped_type = Val
	Types for STL compliance. More...
using	value_type = std::pair< const Key, Val >
	Types for STL compliance. More...
using	reference = value_type &
	Types for STL compliance. More...
using	const_reference = const value_type &
	Types for STL compliance. More...
using	pointer = value_type *
	Types for STL compliance. More...
using	const_pointer = const value_type *
	Types for STL compliance. More...
using	difference_type = std::ptrdiff_t
	Types for STL compliance. More...

Protected Attributes
const HashTable< Key, Val > *	_table_ {nullptr}
	The hash table the iterator is pointing to. More...
Size	_index_ {Size(0)}
	The index of the chained list pointed by the iterator in the array of nodes of the hash table. More...
HashTable< Key, Val >::Bucket *	_bucket_ {nullptr}
	The bucket in the chained list pointed to by the iterator. More...

Protected Member Functions
HashTable< Key, Val >::Bucket *	_getBucket_ () const noexcept
	Returns the current iterator's bucket. More...
Size	_getIndex_ () const noexcept
	Returns the index in the hashtable's node vector pointed to by the iterator. More...

Friends
template<typename K , typename V , typename A >
class	HashTable
	Class HashTable must be a friend because it stores iterator end and this one can be properly initialized only when the hashtable has been fully allocated. More...
class	HashTableConstIteratorSafe< Key, Val >
	For the safe copy constructor and operator. More...

Detailed Description

template<typename Key, typename Val>
class gum::HashTableConstIterator< Key, Val >

Unsafe Const Iterators for hashtables

HashTableConstIterator provides a fast but unsafe way to parse HashTables.

They should only be used when parsing hashtables in which no element is removed from the hashtable. Removing an element where the iterator points to will mess the iterator as it will most certainly point to an unallocated memory. So, this kind of iterator should only be used when parsing "(key) constant" hash tables, e.g., when we wish to display the content of a hash table or when we wish to update the mapped values of some elements of the hash table without ever modifying their keys.

Developers may consider using HashTable<x,y>::const_iterator instead of HashTableConstIterator<x,y>.

Usage example:

// creation of a hash table with 10 elements
HashTable<int,string> table;
for (int i = 0; i< 10; ++i)
  table.insert (i,"xxx" + string (i,'x'));

// parse the hash table
for (HashTable<int,string>::const_iterator iter = table.cbegin ();
       iter != table.cend (); ++iter) {
  // display the values
  cerr << "at " << iter.key() << " value = " << iter.val () << endl;
  const HashTable<int,string>::value_type& elt = *iter;
  const std::pair<const int, string>& xelt = *iter;
}

// check whether two iterators point toward the same element
HashTable<int,string>::const_iterator iter1 = table1.cbegin();
HashTable<int,string>::const_iterator iter2 = table1.cend();
if (iter1 != iter) {
  cerr << "iter1 and iter2 point toward different elements";
}

// make iter1 point toward nothing
iter1.clear ();

Template Parameters

Key	The gum::HashTable key.
Val	The gum::HashTable Value.

Definition at line 2439 of file hashTable.h.

Member Typedef Documentation

const_pointer

template<typename Key, typename Val>

using gum::HashTableConstIterator< Key, Val >::const_pointer = const value_type*

Types for STL compliance.

Definition at line 2450 of file hashTable.h.

const_reference

template<typename Key, typename Val>

using gum::HashTableConstIterator< Key, Val >::const_reference = const value_type&

Types for STL compliance.

Definition at line 2448 of file hashTable.h.

difference_type

template<typename Key, typename Val>

using gum::HashTableConstIterator< Key, Val >::difference_type = std::ptrdiff_t

Types for STL compliance.

Definition at line 2451 of file hashTable.h.

iterator_category

template<typename Key, typename Val>

using gum::HashTableConstIterator< Key, Val >::iterator_category = std::forward_iterator_tag

Types for STL compliance.

Definition at line 2443 of file hashTable.h.

key_type

template<typename Key, typename Val>

using gum::HashTableConstIterator< Key, Val >::key_type = Key

Types for STL compliance.

Definition at line 2444 of file hashTable.h.

mapped_type

template<typename Key, typename Val>

using gum::HashTableConstIterator< Key, Val >::mapped_type = Val

Types for STL compliance.

Definition at line 2445 of file hashTable.h.

pointer

template<typename Key, typename Val>

using gum::HashTableConstIterator< Key, Val >::pointer = value_type*

Types for STL compliance.

Definition at line 2449 of file hashTable.h.

reference

template<typename Key, typename Val>

using gum::HashTableConstIterator< Key, Val >::reference = value_type&

Types for STL compliance.

Definition at line 2447 of file hashTable.h.

value_type

template<typename Key, typename Val>

using gum::HashTableConstIterator< Key, Val >::value_type = std::pair< const Key, Val >

Types for STL compliance.

Definition at line 2446 of file hashTable.h.

Constructor & Destructor Documentation

HashTableConstIterator() [1/6]

template<typename Key , typename Val >

INLINE gum::HashTableConstIterator< Key, Val >::HashTableConstIterator ( )

noexcept

Basic constructor: creates an iterator pointing to nothing.

Definition at line 1820 of file hashTable_tpl.h.

                                                                             {
    GUM_CONSTRUCTOR(HashTableConstIterator);
  }

HashTableConstIterator() [2/6]

template<typename Key, typename Val>

template<typename Alloc >

gum::HashTableConstIterator< Key, Val >::HashTableConstIterator ( const HashTable< Key, Val, Alloc > &  tab )

noexcept

Constructor for an iterator pointing to the first element of a hashtable.

Parameters

tab	The gum::HashTable to iterate over.

Template Parameters

Alloc

The gum::HashTable allocator.

HashTableConstIterator() [3/6]

template<typename Key, typename Val>

template<typename Alloc >

gum::HashTableConstIterator< Key, Val >::HashTableConstIterator	(	const HashTable< Key, Val, Alloc > &	tab,
		Size	ind_elt
	)

Constructor for an iterator pointing to the nth element of a hashtable.

The method runs in time linear to ind_elt.

Parameters

tab	The hash table to which the so-called element belongs.
ind_elt	The position of the element in the hash table (0 means the first element).

Exceptions

UndefinedIteratorValue

Raised if the element cannot be found.

Definition at line 1853 of file hashTable_tpl.h.

                                                  :
      _table_{reinterpret_cast< const HashTable< Key, Val >* >(&tab)} {
    Size i;

    // check if we are looking for a begin() and we know for sure its index
    if ((ind_elt == Size(0)) && (_table_->_begin_index_ != std::numeric_limits< Size >::max())) {
      _index_  = _table_->_begin_index_;
      _bucket_ = _table_->_nodes_[_index_]._end_list_;
    } else {
      // check if it is faster to find the ind_eltth element from the start or
      // from the end of the hashtable
      if (ind_elt < (_table_->_nb_elements_ >> 1)) {
        // find the element we shall point to from the start of the hashtable
        for (i = _table_->_size_ - 1;; --i) {   // no test on i since
          // ind_elt < table_-> _nb_elements_
          if (_table_->_nodes_[i]._nb_elements_) {
            if (ind_elt >= _table_->_nodes_[i]._nb_elements_)
              ind_elt -= _table_->_nodes_[i]._nb_elements_;
            else {
              for (_bucket_ = _table_->_nodes_[i]._end_list_; ind_elt;
                   --ind_elt, _bucket_ = _bucket_->prev) {}

              _index_ = i;
              break;
            }
          }
        }
      } else {
        // ind_elt = the index of the element we should point to
        // check if the index passed as parameter is valid
        if (ind_elt >= _table_->_nb_elements_) {
          GUM_ERROR(UndefinedIteratorValue, "Not enough elements in the hashtable")
        }

        // find the element we shall point to from the end of the hashtable
        for (i = 0, ind_elt = _table_->_nb_elements_ - ind_elt - 1;; ++i) {
          if (_table_->_nodes_[i]._nb_elements_) {
            if (ind_elt >= _table_->_nodes_[i]._nb_elements_)
              ind_elt -= _table_->_nodes_[i]._nb_elements_;
            else {
              for (_bucket_ = _table_->_nodes_[i]._deb_list_; ind_elt;
                   --ind_elt, _bucket_ = _bucket_->next) {}

              _index_ = i;
              break;
            }
          }
        }
      }
    }

    // for debugging purposes
    GUM_CONSTRUCTOR(HashTableConstIterator);
  }

HashTableConstIterator() [4/6]

template<typename Key, typename Val>

INLINE gum::HashTableConstIterator< Key, Val >::HashTableConstIterator ( const HashTableConstIterator< Key, Val > &  from )

noexcept

Copy constructor.

Parameters

from	The gum::HashTableConstIterator to copy.

Definition at line 1911 of file hashTable_tpl.h.

                                                              :
      _table_{from._table_},
      _index_{from._index_}, _bucket_{from._bucket_} {
    GUM_CONS_CPY(HashTableConstIterator);
  }

HashTableConstIterator() [5/6]

template<typename Key, typename Val>

INLINE gum::HashTableConstIterator< Key, Val >::HashTableConstIterator ( HashTableConstIterator< Key, Val > &&  from )

noexcept

Move constructor.

Parameters

from	The gum::HashTableConstIterator to move.

Definition at line 1919 of file hashTable_tpl.h.

                                                         :
      _table_{from._table_},
      _index_{from._index_}, _bucket_{from._bucket_} {
    GUM_CONS_MOV(HashTableConstIterator);
  }

~HashTableConstIterator()

template<typename Key , typename Val >

INLINE gum::HashTableConstIterator< Key, Val >::~HashTableConstIterator ( )

noexcept

Class destructor.

Definition at line 1927 of file hashTable_tpl.h.

                                                                              {
    // for debugging purposes
    GUM_DESTRUCTOR(HashTableConstIterator);
  }

HashTableConstIterator() [6/6]

template<typename Key, typename Val>

template<typename Alloc >

INLINE gum::HashTableConstIterator< Key, Val >::HashTableConstIterator ( const HashTable< Key, Val, Alloc > &  tab )

noexcept

Definition at line 1826 of file hashTable_tpl.h.

                                                       :
      _table_{reinterpret_cast< const HashTable< Key, Val >* >(&tab)} {
    // for debugging purposes
    GUM_CONSTRUCTOR(HashTableConstIterator);

    if (_table_->_nb_elements_) {
      if (_table_->_begin_index_ != std::numeric_limits< Size >::max()) {
        _index_  = _table_->_begin_index_;
        _bucket_ = _table_->_nodes_[_index_]._end_list_;
      } else {
        // find the element we shall point to from the start of the hashtable
        for (Size i = _table_->_size_ - Size(1);; --i) {   // no test on i since
          //  _nb_elements_ != 0
          if (_table_->_nodes_[i]._nb_elements_) {
            _index_                = i;
            _bucket_               = _table_->_nodes_[_index_]._end_list_;
            _table_->_begin_index_ = _index_;
            break;
          }
        }
      }
    }
  }

Member Function Documentation

_getBucket_()

template<typename Key , typename Val >

INLINE HashTable< Key, Val >::Bucket * gum::HashTableConstIterator< Key, Val >::_getBucket_ ( ) const

protectednoexcept

Returns the current iterator's bucket.

Returns

Returns the current iterator's bucket.

Definition at line 2094 of file hashTable_tpl.h.

                                                                    {
    return _bucket_;
  }

_getIndex_()

template<typename Key , typename Val >

INLINE Size gum::HashTableConstIterator< Key, Val >::_getIndex_ ( ) const

protectednoexcept

Returns the index in the hashtable's node vector pointed to by the iterator.

Returns

Returns the index in the hashtable's node vector pointed to by the iterator.

Definition at line 2099 of file hashTable_tpl.h.

                                                                            {
    return _index_;
  }

clear()

template<typename Key , typename Val >

INLINE void gum::HashTableConstIterator< Key, Val >::clear ( )

noexcept

Makes the iterator point toward nothing (in particular, it is not related anymore to its current hash table).

Definition at line 1979 of file hashTable_tpl.h.

                                                                 {
    _table_  = nullptr;
    _bucket_ = nullptr;
    _index_  = 0;
  }

key()

template<typename Key , typename Val >

INLINE const HashTableConstIterator< Key, Val >::key_type & gum::HashTableConstIterator< Key, Val >::key

(

)

const

Returns the key corresponding to the element pointed to by the iterator.

Warning

Using this method on an iterator that points to an element that has been deleted will most certainly result in a segfault. If unsure, use a safe iterator instead of an unsafe one.

Returns

Returns the key corresponding to the element pointed to by the iterator.

Definition at line 1960 of file hashTable_tpl.h.

                                                   {
    if (_bucket_)
      return _bucket_->pair.first;
    else {
      GUM_ERROR(UndefinedIteratorValue, "Accessing a nullptr object")
    }
  }

operator!=()

template<typename Key, typename Val>

INLINE bool gum::HashTableConstIterator< Key, Val >::operator!= ( const HashTableConstIterator< Key, Val > &  from ) const

noexcept

Checks whether two iterators are pointing toward different elements.

Parameters

from	The gum::HashTableConstIterator to test for inequality.

Returns

Returns true if this and from are not equal.

Definition at line 2071 of file hashTable_tpl.h.

                                                                    {
    return (_bucket_ != from._bucket_);
  }

operator*()

template<typename Key , typename Val >

INLINE const HashTableConstIterator< Key, Val >::value_type & gum::HashTableConstIterator< Key, Val >::operator*

(

)

const

Returns the value pointed to by the iterator.

Warning

using this method on an iterator that points to an element that has been deleted will most certainly result in a segfault. If unsure, use a safe iterator instead of an unsafe one.

Returns

Returns the value pointed to by the iterator.

Definition at line 2084 of file hashTable_tpl.h.

                                                         {
    if (_bucket_)
      return _bucket_->elt();
    else {
      GUM_ERROR(UndefinedIteratorValue, "Accessing a nullptr object")
    }
  }

operator+()

template<typename Key , typename Val >

INLINE HashTableConstIterator< Key, Val > gum::HashTableConstIterator< Key, Val >::operator+ ( Size  i ) const

noexcept

Returns a new iterator pointing to i elements further in the hashtable.

Parameters

i	The number of increments.

Returns

Returns a new iterator pointing to i elements further in the hashtable.

Definition at line 2066 of file hashTable_tpl.h.

                                                                         {
    return HashTableConstIterator< Key, Val >{*this} += nb;
  }

operator++()

template<typename Key , typename Val >

HashTableConstIterator< Key, Val > & gum::HashTableConstIterator< Key, Val >::operator++ ( )

noexcept

Makes the iterator point to the next element in the hash table.

for (iter = cbegin (); iter != cend(); ++iter ) { }

The above loop is guaranteed to parse the whole hash table as long as no element is added to or deleted from the hash table while being in the loop.

Warning

performing a ++ on an iterator that points to an element that has been deleted will most certainly result in a segfault.

Returns

Returns this gum::HashTableConstIterator.

Definition at line 1986 of file hashTable_tpl.h.

                                                                                              {
    // if  _bucket_ == nullptr then we are at the end of the hashtable
    if (_bucket_ == nullptr) return *this;

    // if we are not pointing on the first element of the chained list, just
    // point to the next bucket in this list
    if (_bucket_->prev) {
      _bucket_ = _bucket_->prev;
      // here, no need to update  _index_ which has not changed.
    } else {
      // ok, here we are on the end of a chained list,
      // so 2 cases can obtain:
      // 1/ index = 0 : then we have reached the end of the hashtable
      // 2/ index != 0 => we must search for a new slot containing elements

      // case 1:
      if (_index_ == Size(0)) {
        _bucket_ = nullptr;
        // we are thus at the end() of the hashTable
      }

      // case 2:
      else {
        // arrived here, we need to parse the hash table until we find a new
        // bucket because we are pointing on a chained list with no more element
        // to the right of the current element
        for (Size i = _index_ - Size(1); i; --i) {
          if (_table_->_nodes_[i]._nb_elements_) {
            _index_  = i;
            _bucket_ = _table_->_nodes_[i]._end_list_;
            return *this;
          }
        }

        if (_table_->_nodes_[0]._nb_elements_)
          _bucket_ = _table_->_nodes_[0]._end_list_;
        else
          _bucket_ = nullptr;

        _index_ = Size(0);
      }
    }

    return *this;
  }

operator+=()

template<typename Key , typename Val >

HashTableConstIterator< Key, Val > & gum::HashTableConstIterator< Key, Val >::operator+= ( Size  i )

noexcept

Makes the iterator point to i elements further in the hashtable.

Parameters

i	The number of increments.

Returns

Returns this gum::HashTableConstIterator.

Definition at line 2034 of file hashTable_tpl.h.

                                                                    {
    if ((nb == 0) || (_table_ == nullptr) || (_bucket_ == nullptr)) return *this;

    // ok, here we can use  _bucket_ as a starting point: parse all the elements
    // of the current chained list
    for (; nb && _bucket_ != nullptr; --nb, _bucket_ = _bucket_->prev) {}

    if (_bucket_ != nullptr) return *this;

    // here, we shall skip all the chained list that have not sufficiently
    // many elements
    --_index_;

    for (; _index_ < _table_->_size_ && nb >= _table_->_nodes_[_index_]._nb_elements_;
         nb -= _table_->_nodes_[_index_]._nb_elements_, --_index_) {}

    // here: either  _index_ >=  _table_-> _size_, which means that we did not find
    // the element we looked for, i.e., we are at the end of the hashtable, or
    // nb <  _table_-> _nodes_[ _index_]. _nb_elements_, and we should parse the
    // chained list to get the element (which, we know for sure, exists)
    if (_index_ >= _table_->_size_) {
      _index_ = 0;
      return *this;
    }

    for (_bucket_ = _table_->_nodes_[_index_]._end_list_; nb; --nb, _bucket_ = _bucket_->prev) {}

    return *this;
  }

operator=() [1/2]

template<typename Key, typename Val>

INLINE HashTableConstIterator< Key, Val > & gum::HashTableConstIterator< Key, Val >::operator= ( const HashTableConstIterator< Key, Val > &  from )

noexcept

Copy operator.

Parameters

from	The gum::HashTableConstIterator to copy.

Returns

Returns this gum::HashTableConstIterator.

Definition at line 1933 of file hashTable_tpl.h.

                                                              {
    // here, no need to avoid self assignment: this would slow down normal
    // assignments and, in any case, this would not result in an iterator in
    // an incoherent state
    _table_  = from._table_;
    _index_  = from._index_;
    _bucket_ = from._bucket_;

    return *this;
  }

operator=() [2/2]

template<typename Key, typename Val>

INLINE HashTableConstIterator< Key, Val > & gum::HashTableConstIterator< Key, Val >::operator= ( HashTableConstIterator< Key, Val > &&  from )

noexcept

Move operator.

Parameters

from	The gum::HashTableConstIterator to move.

Returns

Returns this gum::HashTableConstIterator.

Definition at line 1946 of file hashTable_tpl.h.

                                                         {
    // here, no need to avoid self assignment: this would slow down normal
    // assignments and, in any case, this would not result in an iterator in
    // an incoherent state
    _table_  = from._table_;
    _index_  = from._index_;
    _bucket_ = from._bucket_;

    return *this;
  }

operator==()

template<typename Key, typename Val>

INLINE bool gum::HashTableConstIterator< Key, Val >::operator== ( const HashTableConstIterator< Key, Val > &  from ) const

noexcept

Checks whether two iterators are pointing toward equal elements.

Parameters

from	The gum::HashTableConstIterator to test for equality.

Returns

Returns true if this and from are equal.

Definition at line 2077 of file hashTable_tpl.h.

                                                                    {
    return (_bucket_ == from._bucket_);
  }

val()

template<typename Key , typename Val >

INLINE const HashTableConstIterator< Key, Val >::mapped_type & gum::HashTableConstIterator< Key, Val >::val

(

)

const

Returns the mapped value pointed to by the iterator.

Warning

Using this method on an iterator that points to an element that has been deleted will most certainly result in a segfault. If unsure, use a safe iterator instead of an unsafe one.

Returns

Returns the mapped value pointed to by the iterator.

Definition at line 1970 of file hashTable_tpl.h.

                                                   {
    if (_bucket_)
      return _bucket_->val();
    else {
      GUM_ERROR(UndefinedIteratorValue, "Accessing a nullptr object")
    }
  }

Friends And Related Function Documentation

HashTable

template<typename Key, typename Val>

template<typename K , typename V , typename A >

friend class HashTable

friend

Class HashTable must be a friend because it stores iterator end and this one can be properly initialized only when the hashtable has been fully allocated.

Thus, proper initialization can only take place within the constructor's code of the hashtable.

Template Parameters

K	The gum::HashTable keys type.
V	The gum::HashTable values type.
A	The gum::HashTable allocator.

Definition at line 2639 of file hashTable.h.

HashTableConstIteratorSafe< Key, Val >

template<typename Key, typename Val>

friend class HashTableConstIteratorSafe< Key, Val >

friend

For the safe copy constructor and operator.

Definition at line 2642 of file hashTable.h.

Member Data Documentation

_bucket_

template<typename Key, typename Val>

HashTable< Key, Val >::Bucket* gum::HashTableConstIterator< Key, Val >::_bucket_ {nullptr}

protected

The bucket in the chained list pointed to by the iterator.

Definition at line 2654 of file hashTable.h.

_index_

template<typename Key, typename Val>

Size gum::HashTableConstIterator< Key, Val >::_index_ {Size(0)}

protected

The index of the chained list pointed by the iterator in the array of nodes of the hash table.

Definition at line 2651 of file hashTable.h.

_table_

template<typename Key, typename Val>

const HashTable< Key, Val >* gum::HashTableConstIterator< Key, Val >::_table_ {nullptr}

protected

The hash table the iterator is pointing to.

Definition at line 2645 of file hashTable.h.

---

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

• agrum/tools/core/hashTable.h
• agrum/tools/core/hashTable_tpl.h