HashtableIterator< KeyType, ValueType, HashFunctorType > Class Template Reference

This class is an iterator object, used for iterating over the set of keys or values in a Hashtable. More...

#include <Hashtable.h>

Inheritance diagram for HashtableIterator< KeyType, ValueType, HashFunctorType >:

Inheritance graph
[legend]
List of all members.

Public Member Functions

 HashtableIterator ()
 Default constructor.
 HashtableIterator (const HashtableIterator< KeyType, ValueType, HashFunctorType > &rhs)
 Copy Constructor.
 HashtableIterator (const Hashtable< KeyType, ValueType, HashFunctorType > &table, uint32 flags=0)
 Convenience Constructor -- makes an iterator equivalent to the value returned by table.GetIterator().
 HashtableIterator (const Hashtable< KeyType, ValueType, HashFunctorType > &table, const KeyType &startAt, uint32 flags)
 Convenience Constructor -- makes an iterator equivalent to the value returned by table.GetIteratorAt().
 ~HashtableIterator ()
 Destructor.
HashtableIterator< KeyType,
ValueType, HashFunctorType > & 		operator= (const HashtableIterator< KeyType, ValueType, HashFunctorType > &rhs)
 Assignment operator.
void operator++ (int)
 Advances this iterator by one entry in the table.
void operator-- (int)
 Retracts this iterator by one entry in the table.
bool HasMoreKeys () const
 Returns true iff there are more keys left in the key traversal.
const KeyType & GetKey () const
 Returns a reference to the key this iterator is currently pointing at.
ValueType & GetValue () const
 Returns a reference to the value this iterator is currently pointing at.
status_t GetNextKey (KeyType &setNextKey)
 Iterates to get the next key in the key traversal.
status_t GetNextKey (const KeyType *&setNextKeyPtr)
 Iterates to get the next key in the key traversal.
const KeyType * GetNextKey ()
 Iterates to get a pointer to the next key in the key traversal.
status_t PeekNextKey (KeyType &setKey) const
 Peek at the next key without modifying the state of the traversal.
status_t PeekNextKey (const KeyType *&setKey) const
 Peek at the next key without modifying the state of the traversal.
const KeyType * PeekNextKey () const
 Peek at the next key without modifying the state of the traversal.
bool HasMoreValues () const
 Returns true iff there are more values left in the value traversal.
status_t GetNextValue (ValueType &setNextValue)
 Iterates to get the next value in the values traversal.
status_t GetNextValue (ValueType *&setValuePtr)
 Iterates to get the next value in the values traversal.
status_t GetNextValue (const ValueType *&setValuePtr)
 Iterates to get the next value in the values traversal.
ValueType * GetNextValue ()
 Iterates to get the next value in the values traversal.
status_t PeekNextValue (ValueType &setValue) const
 Peek at the next value without modifying the state of the traversal.
status_t PeekNextValue (const ValueType *&setValue) const
 Peek at the next value without modifying the state of the traversal.
status_t PeekNextValue (ValueType *&setValue) const
 Peek at the next value without modifying the state of the traversal.
ValueType * PeekNextValue () const
 Peek at the next value without modifying the state of the traversal.
status_t GetNextKeyAndValue (KeyType &setKey, ValueType &setValue)
 Convenience method -- equivalent to calling both GetNextKey() and GetNextValue().
status_t GetNextKeyAndValue (KeyType &setKey, ValueType *&setValuePtr)
 Convenience method -- equivalent to calling both GetNextKey() and GetNextValue().
status_t GetNextKeyAndValue (KeyType &setKey, const ValueType *&setValuePtr)
 Convenience method -- equivalent to calling both GetNextKey() and GetNextValue().
status_t GetNextKeyAndValue (const KeyType *&setKeyPtr, ValueType &setValue)
 Convenience method -- equivalent to calling both GetNextKey() and GetNextValue().
status_t GetNextKeyAndValue (const KeyType *&setKeyPtr, ValueType *&setValuePtr)
 Convenience method -- equivalent to calling both GetNextKey() and GetNextValue().
status_t GetNextKeyAndValue (const KeyType *&setKeyPtr, const ValueType *&setValuePtr)
 Convenience method -- equivalent to calling both GetNextKey() and GetNextValue().
uint32 GetFlags () const
 Returns this iterator's HTIT_FLAG_* bit-chord value.
void SetBackwards (bool backwards)
 Sets or unsets the HTIT_FLAG_BACWARDS flag on this iterator.
bool IsBackwards () const
 Returns true iff this iterator is set to iterate in reverse order -- i.e.

Friends

class Hashtable< KeyType, ValueType, HashFunctorType >
 The Hashtable class needs access to our internals to do the iteration operation.

Detailed Description

template<class KeyType, class ValueType, class HashFunctorType = HashFunctor<KeyType>>
class HashtableIterator< KeyType, ValueType, HashFunctorType >

This class is an iterator object, used for iterating over the set of keys or values in a Hashtable.

Note that the Hashtable maintains the ordering of keys and values, unlike many hash table implementations.

Given a Hashtable object, you can obtain one or more of these iterator objects by calling the Hashtable's GetIterator() method.

This iterator actually contains separate state for two iterations: one for iterating over the values in the Hashtable, and one for iterating over the keys. These two iterations can be done independently of each other.

One useful form for doing an iteration is this:

for (HashtableIterator<String, int> iter(table); iter.HasMoreKeys(); iter++) { const String & nextKey = iter.GetKey(); int nextValue = iter.GetValue(); [...] }

Another common form is this:

String nextKey; int nextValue; HashtableIterator<String, int> iter(table); while(iter.GetNextKeyAndValue(nextKey, nextValue) == B_NO_ERROR) { [...] }

It is safe to modify or delete a hashtable during a traversal; the active iterators will be automatically notified so that they do the right thing.

Definition at line 80 of file Hashtable.h.

Constructor & Destructor Documentation

template<class KeyType, class ValueType, class HashFunctorType>
HashtableIterator< KeyType, ValueType, HashFunctorType >::HashtableIterator (  ) 

Default constructor.

It's here only so that you can include HashtableIterators as member variables, in arrays, etc. HashtableIterators created with this constructor are "empty", so they won't be useful until you set them equal to a HashtableIterator that was returned by Hashtable::GetIterator().

Definition at line 1984 of file Hashtable.h.

template<class KeyType, class ValueType, class HashFunctorType>
HashtableIterator< KeyType, ValueType, HashFunctorType >::HashtableIterator ( const Hashtable< KeyType, ValueType, HashFunctorType > &  table,
uint32  flags = 0 
)

Convenience Constructor -- makes an iterator equivalent to the value returned by table.GetIterator().

Parameters:
table the Hashtable to iterate over.
flags A bit-chord of HTIT_FLAG_* constants (see above). Defaults to zero for default behaviour.

Definition at line 1996 of file Hashtable.h.

References Hashtable< KeyType, ValueType, HashFunctorType >::InitializeIterator().

template<class KeyType, class ValueType, class HashFunctorType>
HashtableIterator< KeyType, ValueType, HashFunctorType >::HashtableIterator ( const Hashtable< KeyType, ValueType, HashFunctorType > &  table,
const KeyType &  startAt,
uint32  flags 
)

Convenience Constructor -- makes an iterator equivalent to the value returned by table.GetIteratorAt().

Parameters:
table the Hashtable to iterate over.
startAt the first key that should be returned by the iteration. If (startAt) is not in the table, the iterator will not return any results.
flags A bit-chord of HTIT_FLAG_* constants (see above). Set to zero to get the default behaviour.

Definition at line 2002 of file Hashtable.h.

References Hashtable< KeyType, ValueType, HashFunctorType >::InitializeIteratorAt().

Member Function Documentation

template<class KeyType, class ValueType, class HashFunctorType = HashFunctor<KeyType>>
void HashtableIterator< KeyType, ValueType, HashFunctorType >::operator++ ( int   )  [inline]

Advances this iterator by one entry in the table.

Equivalent to calling both GetNextKey() and GetNextValue().

Reimplemented in MessageFieldNameIterator.

Definition at line 115 of file Hashtable.h.

template<class KeyType, class ValueType, class HashFunctorType = HashFunctor<KeyType>>
void HashtableIterator< KeyType, ValueType, HashFunctorType >::operator-- ( int   )  [inline]

Retracts this iterator by one entry in the table.

The opposite of the ++ operator.

Reimplemented in MessageFieldNameIterator.

Definition at line 118 of file Hashtable.h.

template<class KeyType, class ValueType, class HashFunctorType = HashFunctor<KeyType>>
const KeyType& HashtableIterator< KeyType, ValueType, HashFunctorType >::GetKey (  )  const [inline]

Returns a reference to the key this iterator is currently pointing at.

This method does not change the state of the iterator.

Note:
Be careful with this method, if this iterator isn't currently pointing at any key, it will return a NULL reference and your program will crash when you try to use it. Typically you would want to call this function only after checking to see that HasMoreKeys() returns true.

The returned reference is only guaranteed to remain valid for as long as the Hashtable remains unchanged.

Definition at line 131 of file Hashtable.h.

template<class KeyType, class ValueType, class HashFunctorType = HashFunctor<KeyType>>
ValueType& HashtableIterator< KeyType, ValueType, HashFunctorType >::GetValue (  )  const [inline]

Returns a reference to the value this iterator is currently pointing at.

Note:
Be careful with this method, if this iterator isn't currently pointing at any value, it will return a NULL reference and your program will crash when you try to use it. Typically you would want to call this function only after checking to see that HasMoreValues() returns true.

The returned reference is only guaranteed to remain valid for as long as the Hashtable remains unchanged.

Definition at line 141 of file Hashtable.h.

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey ( KeyType &  setNextKey  ) 

Iterates to get the next key in the key traversal.

Parameters:
setNextKey On success, the next key is copied into this object.
Returns:
B_NO_ERROR on success, B_ERROR if there are no more keys left.

Definition at line 2033 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey ( const KeyType *&  setNextKeyPtr  ) 

Iterates to get the next key in the key traversal.

Parameters:
setNextKeyPtr On success, this pointer is set to point to the next key in the traversal.
Returns:
B_NO_ERROR on success, B_ERROR if there are no more keys left.

Definition at line 2046 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey().

template<class KeyType, class ValueType, class HashFunctorType>
const KeyType * HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey (  ) 

Iterates to get a pointer to the next key in the key traversal.

Note that the returned pointer is only guaranteed valid as long as the Hashtable remains unchanged.

Returns:
A pointer to the next key in the key traversal, or NULL if there are no more keys left.

Definition at line 2143 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextKey().

Referenced by HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey(), HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKeyAndValue(), HashtableIterator< SocketRef, bool, HashFunctor< SocketRef > >::operator++(), and HashtableIterator< SocketRef, bool, HashFunctor< SocketRef > >::operator--().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextKey ( KeyType &  setKey  )  const

Peek at the next key without modifying the state of the traversal.

Parameters:
setKey On success, the next key is copied into this object.
Returns:
B_NO_ERROR on success, or B_ERROR if there are no more keys left.

Definition at line 2080 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextKey().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextKey ( const KeyType *&  setKey  )  const

Peek at the next key without modifying the state of the traversal.

Parameters:
setKey On success, the next key is copied into this object.
Returns:
B_NO_ERROR on success, or B_ERROR if there are no more keys left.

Definition at line 2093 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextKey().

template<class KeyType, class ValueType, class HashFunctorType>
const KeyType * HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextKey (  )  const

Peek at the next key without modifying the state of the traversal.

Note that the returned pointer is only guaranteed valid as long as the Hashtable remains unchanged.

Returns:
a pointer to the next key in the key traversal, or NULL if there are no keys left.

Definition at line 2166 of file Hashtable.h.

Referenced by HashtableIterator< SocketRef, bool, HashFunctor< SocketRef > >::GetKey(), HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey(), and HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextKey().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue ( ValueType &  setNextValue  ) 

Iterates to get the next value in the values traversal.

Parameters:
setNextValue On success, the next value in the traversal is copied into this object.
Returns:
B_NO_ERROR on success, B_ERROR if there are no more values left in the value traversal.

Definition at line 2053 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue ( ValueType *&  setValuePtr  ) 

Iterates to get the next value in the values traversal.

Parameters:
setValuePtr On success, this pointer will be set to the next value in the traversal.
Returns:
B_NO_ERROR on success, B_ERROR if there are no more values left in the value traversal.

Definition at line 2066 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue ( const ValueType *&  setValuePtr  ) 

Iterates to get the next value in the values traversal.

Parameters:
setValuePtr On success, this pointer will be set to the next value in the traversal.
Returns:
B_NO_ERROR on success, B_ERROR if there are no more values left in the value traversal.

Definition at line 2073 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue().

template<class KeyType, class ValueType, class HashFunctorType>
ValueType * HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue (  ) 

Iterates to get the next value in the values traversal.

Note that the returned pointer is only guaranteed valid as long as the Hashtable remains unchanged.

Returns:
a pointer to the next value in the value traversal, or NULL if there are no values left.

Definition at line 2127 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextValue().

Referenced by HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKeyAndValue(), HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue(), HashtableIterator< SocketRef, bool, HashFunctor< SocketRef > >::operator++(), and HashtableIterator< SocketRef, bool, HashFunctor< SocketRef > >::operator--().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextValue ( ValueType &  setValue  )  const

Peek at the next value without modifying the state of the traversal.

Parameters:
setValue On success, the next value is copied into this object.
Returns:
B_NO_ERROR on success, or B_ERROR if there are no more values left.

Definition at line 2100 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextValue().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextValue ( const ValueType *&  setValue  )  const

Peek at the next value without modifying the state of the traversal.

Parameters:
setValue On success, this pointer is set to point to the next value in the traversal.
Returns:
B_NO_ERROR on success, or B_ERROR if there are no more values left.

Definition at line 2113 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextValue().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextValue ( ValueType *&  setValue  )  const

Peek at the next value without modifying the state of the traversal.

Parameters:
setValue On success, this pointer is set to point to the next value in the traversal.
Returns:
B_NO_ERROR on success, or B_ERROR if there are no more values left.

Definition at line 2120 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextValue().

template<class KeyType, class ValueType, class HashFunctorType>
ValueType * HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextValue (  )  const

Peek at the next value without modifying the state of the traversal.

Note that the returned pointer is only guaranteed valid as long as the Hashtable remains unchanged.

Returns:
a pointer to the next value in the value traversal, or NULL if there are no values left.

Definition at line 2159 of file Hashtable.h.

Referenced by HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue(), HashtableIterator< SocketRef, bool, HashFunctor< SocketRef > >::GetValue(), and HashtableIterator< KeyType, ValueType, HashFunctorType >::PeekNextValue().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKeyAndValue ( KeyType &  setKey,
ValueType &  setValue 
)

Convenience method -- equivalent to calling both GetNextKey() and GetNextValue().

Parameters:
setKey on success, this parameter will contain the next key in the iteration.
setValue on success, this parameter will contain the next value in the iteration.
Returns:
B_NO_ERROR if values were written into (setKey) and (setValue), or B_ERROR if the iteration is complete.

Definition at line 2173 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey(), and HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKeyAndValue ( KeyType &  setKey,
ValueType *&  setValuePtr 
)

Convenience method -- equivalent to calling both GetNextKey() and GetNextValue().

Parameters:
setKey on success, this parameter will contain the next key in the iteration.
setValuePtr on success, this pointer will point to the next value in the iteration.
Returns:
B_NO_ERROR if values were written into (setKey) and (setValue), or B_ERROR if the iteration is complete.

Definition at line 2180 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey(), and HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKeyAndValue ( KeyType &  setKey,
const ValueType *&  setValuePtr 
)

Convenience method -- equivalent to calling both GetNextKey() and GetNextValue().

Parameters:
setKey on success, this parameter will contain the next key in the iteration.
setValuePtr on success, this pointer will point to the next value in the iteration.
Returns:
B_NO_ERROR if values were written into (setKey) and (setValue), or B_ERROR if the iteration is complete.

Definition at line 2187 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey(), and HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKeyAndValue ( const KeyType *&  setKeyPtr,
ValueType &  setValue 
)

Convenience method -- equivalent to calling both GetNextKey() and GetNextValue().

Parameters:
setKeyPtr on success, this pointer will point to the next key in the iteration.
setValue on success, this parameter will contain the next value in the iteration.
Returns:
B_NO_ERROR if values were written into (setKey) and (setValue), or B_ERROR if the iteration is complete.

Definition at line 2194 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey(), and HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKeyAndValue ( const KeyType *&  setKeyPtr,
ValueType *&  setValuePtr 
)

Convenience method -- equivalent to calling both GetNextKey() and GetNextValue().

Parameters:
setKeyPtr on success, this pointer will point to the next key in the iteration.
setValuePtr on success, this pointer will point to the next value in the iteration.
Returns:
B_NO_ERROR if values were written into (setKey) and (setValue), or B_ERROR if the iteration is complete.

Definition at line 2201 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey(), and HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue().

template<class KeyType, class ValueType, class HashFunctorType>
status_t HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKeyAndValue ( const KeyType *&  setKeyPtr,
const ValueType *&  setValuePtr 
)

Convenience method -- equivalent to calling both GetNextKey() and GetNextValue().

Parameters:
setKeyPtr on success, this pointer will point to the next key in the iteration.
setValuePtr on success, this pointer will point to the next value in the iteration.
Returns:
B_NO_ERROR if values were written into (setKey) and (setValue), or B_ERROR if the iteration is complete.

Definition at line 2208 of file Hashtable.h.

References HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextKey(), and HashtableIterator< KeyType, ValueType, HashFunctorType >::GetNextValue().

template<class KeyType, class ValueType, class HashFunctorType = HashFunctor<KeyType>>
void HashtableIterator< KeyType, ValueType, HashFunctorType >::SetBackwards ( bool  backwards  )  [inline]

Sets or unsets the HTIT_FLAG_BACWARDS flag on this iterator.

Parameters:
backwards If true, this iterator will be set to iterate backwards from wherever it is currently; if false, this iterator will be set to iterate forwards from wherever it is currently.

Definition at line 293 of file Hashtable.h.

Referenced by MessageFieldNameIterator::operator--(), and HashtableIterator< SocketRef, bool, HashFunctor< SocketRef > >::operator--().

template<class KeyType, class ValueType, class HashFunctorType = HashFunctor<KeyType>>
bool HashtableIterator< KeyType, ValueType, HashFunctorType >::IsBackwards (  )  const [inline]

Returns true iff this iterator is set to iterate in reverse order -- i.e.

if HTIT_FLAG_BACKWARDS was passed in to the constructor, or if SetBackwards(true) was called.

Definition at line 298 of file Hashtable.h.

Referenced by MessageFieldNameIterator::operator--(), and HashtableIterator< SocketRef, bool, HashFunctor< SocketRef > >::operator--().

The documentation for this class was generated from the following file:
Generated on Thu Jun 5 17:48:08 2008 for MUSCLE by  doxygen 1.5.1