Detailed Description

Safe Iterators for hashtables.

HashTableIteratorSafe provides a safe way to parse HashTables. They are safe because they are kept informed by the hashtable they belong to of the elements deleted by the user. Hence, even if the user removes an element pointed to by a HashTableIteratorSafe, using the latter to access this element will never crash the application. Instead it will properly throw an UndefinedIteratorValue exception.

Developers may consider using HashTable<x,y>::iterator_safe instead of HashTableIteratorSafe<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>::iterator_safe iter = table.beginSafe ();

iter != table.endSafe (); ++iter) {

// display the values

cerr << "at " << iter.key() << " value = " << iter.val () << endl;

HashTable<int,string>::value_type& elt = *iter;

std::pair<const int, string>& xelt = *iter;

}

// check whether two iterators point toward the same element

HashTable<int,string>::iterator_safe iter1 = table1.beginSafe ();

HashTable<int,string>::iterator_safe iter2 = table1.endSafe ();

if (iter1 != iter) {

cerr << "iter1 and iter2 point toward different elements";

}

// make iter1 point toward nothing

iter1.clear ();

setset

Template Parameters

Key The gum::HashTable key.

Val The gum::HashTable Value. / template < typename Key, typename Val > class HashTableIteratorSafe: public HashTableConstIteratorSafe< Key, Val > { public: /// Types for STL compliance. /// @{ using iterator_category = std::forward_iterator_tag; using key_type = Key; using mapped_type = Val; using value_type = std::pair< const Key, Val >; using reference = value_type&; using const_reference = const value_type&; using pointer = value_type*; using const_pointer = const value_type*; using difference_type = std::ptrdiff_t; /// @}

// ============================================================================ /// @name Constructors / Destructors // ============================================================================ /// @{

/**

@brief Basic constructor: creates an iterator pointing to nothing. */ explicit HashTableIteratorSafe();

// DOXYGEN_SHOULD_SKIP_THIS

/**

@brief Constructor for an iterator pointing to the first element of a
hashtable. */ HashTableIteratorSafe(const HashTable< Key, Val >& tab);

/**

@brief 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
Parameters

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 */ HashTableIteratorSafe(const HashTable< Key, Val >& tab, Size ind_elt);

/**
@brief Copy constructor.
Parameters

from the gum::HashTableIteratorSafe to copy.
Returns
This gum::HashTableIteratorSafe. */ HashTableIteratorSafe(const HashTableIteratorSafe< Key, Val >& from);
/**
@brief Copy constructor.
Parameters

from the gum::HashTableIterator to copy.
Returns
This gum::HashTableIteratorSafe. */ explicit HashTableIteratorSafe(const HashTableIterator< Key, Val >& from);
/**
@brief Move constructor.
Parameters

from The gum::HashTableIteratorSafe to move.
Returns
Returns this gum::HashTableIteratorSafe. */ HashTableIteratorSafe(HashTableIteratorSafe< Key, Val >&& from) noexcept;
/**
@brief Class destructor. */ ~HashTableIteratorSafe() noexcept;

/// @} // ============================================================================ /// @name Accessors / Modifiers // ============================================================================ /// @{

/// Usefull Alias /// @{ using HashTableConstIteratorSafe< Key, Val >::key; using HashTableConstIteratorSafe< Key, Val >::val; using HashTableConstIteratorSafe< Key, Val >::clear; /// @}

/**

@brief Returns the mapped value pointed to by the iterator.
Returns
Returns the mapped value pointed to by the iterator.
Exceptions

UndefinedIteratorValue Raised when the iterator does not point
to a valid hash table element. */ mapped_type& val();

/// @} // ============================================================================ /// @name Operators // ============================================================================ /// @{

/**

@brief Copy operator.
Parameters

from The gum::HashTableIteratorSafe to copy.
Returns
Returns this gum::HashTableIterator. */ HashTableIteratorSafe< Key, Val >& operator=(const HashTableIteratorSafe< Key, Val >& from);
/**
@brief Copy operator.
Parameters

from The gum::HashTableIterator to copy.
Returns
Returns this gum::HashTableIterator. */ HashTableIteratorSafe< Key, Val >& operator=(const HashTableIterator< Key, Val >& from);
/**
@brief Move operator.
Parameters

from The gum::HashTableIteratorSafe to move.
Returns
Returns this gum::HashTableIterator. */ HashTableIteratorSafe< Key, Val >& operator=(HashTableIteratorSafe< Key, Val >&& from) noexcept;
/**
@brief Makes the iterator point to the next element in the hash table.
* for (iter = hash.beginSafe (); iter != hash.endSafe (); ++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. Deleting elements during the loop is guaranteed to never produce a segmentation fault.

Returns
This gum::HashTableIteratorSafe.

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

agrum/base/core/hashTable.h