Hash Iterators

Hash iterators are used to step through a hash, one or more elements at a time. Iterators that are newly constructed or reset are positioned before the first element in the hash. The hash may be traversed one element at a time using the pre-increment or call operator. An increment operation causing the iterator to be positioned after the end of the hash returns zero. Further increments will cause the undef_iter exception to be thrown, if it is enabled. The WCIterExcept class provides the common exception handling control interface for all of the iterators.

Since the iterator classes are all template classes, most of the functionality is derived from common base classes. In the listing of class member functions, those public member functions that appear to be in the iterator class but are actually defined in the common base class are identified as if they were explicitly specified in the iterator class.

This chapter describes the following classes:

WCPtrHashDictIter<Key,Value> Class

Declared:

wchiter.h

The WCPtrHashDictIter<Key,Value> class is the templated class used to create iterator objects for WCPtrHashDict<Key,Value> hash objects. In the description of each member function,

The WCIterExcept class is a base class of the WCPtrHashDictIter<Key,Value> class, and provides the exceptions() member function. This member function controls the exceptions that can be thrown by the WCPtrHashDictIter<Key,Value> object. No exceptions are enabled unless they're set by the exceptions() member function.

Public Member Functions

The following member functions are declared in the public interface: 

WCPtrHashDictIter();
WCPtrHashDictIter( const WCPtrHashDict<Key,Value> & );
~WCPtrHashDictIter();

const WCPtrHashDict<Key,Value> * container() const;
Key * key();
void reset();
void reset( WCPtrHashDict<Key,Value> & );
Value * value();

Public Member Operators

The following member operators are declared in the public interface: 

int operator ()();
int operator ++();

WCPtrHashDictIter<Key,Value>::WCPtrHashDictIter()

create a WCPtrHashDictIter<Key,Value> object

Synopsis:

#include <wchiter.h>
public:
WCPtrHashDictIter();
WCPtrHashDictIter( WCPtrHashDict<Key,Value> & );

Semantics:

There are two forms of the public WCPtrHashDictIter<Key,Value> constructor:

  • The first form is the default constructor for the class, and initializes the iterator with no hash to operate on. The reset() member function must be called to provide the iterator with a hash to iterate over.
  • The second form initializes the iterator to operate on the WCPtrHashDict hash object passed as a parameter. The iterator is positioned before the first hash element. To position the iterator to a valid element within the hash, increment it using one of the operator ++() or operator ()() operators.

Results:

The public WCPtrHashDictIter<Key,Value> constructor creates a WCPtrHashDictIter hash iterator object.

See also:

WCPtrHashDictIter<Key,Value>::~WCPtrHashDictIter(), WCPtrHashDictIter<Key,Value>::operator ()(), WCPtrHashDictIter<Key,Value>::operator ++(), WCPtrHashDictIter<Key,Value>::reset()

WCPtrHashDictIter<Key,Value>::~WCPtrHashDictIter()

destroy a WCPtrHashDictIter<Key,Value> object

Synopsis:

#include <wchiter.h>
public:
~WCPtrHashDictIter();

Semantics:

The public WCPtrHashDictIter<Key,Value> destructor is the destructor for the class. The call to it is inserted implicitly by the compiler at the point where the WCPtrHashDictIter hash iterator object goes out of scope.

Results:

The WCPtrHashDictIter hash iterator object is destroyed.

See also:

WCPtrHashDictIter<Key,Value>::WCPtrHashDictIter()

WCPtrHashDictIter<Key,Value>::container()

return a pointer to the hash container object

Synopsis:

#include <wchiter.h>
public:
WCPtrHashDict<Key,Value> * container() const;

Semantics:

The container() public member function returns a pointer to the hash container object. If the iterator hasn't been initialized with a hash object, and the undef_iter exception is enabled, the exception is thrown.

Results:

A pointer to the hash object associated with the iterator is returned, or NULL(0) if the iterator hasn't been initialized with a hash.

See also:

WCIterExcept::undef_iter, WCPtrHashDictIter<Key,Value>::WCPtrHashDictIter(), WCPtrHashDictIter<Key,Value>::reset()

WCPtrHashDictIter<Key,Value>::key()

return a pointer to the Key at the current iterator position

Synopsis:

#include <wchiter.h>
public:
Key * key();

Semantics:

The key() public member function returns a pointer to the Key value of the hash item at the current iterator position.

If the iterator isn't associated with a hash, or the iterator position is either before the first element or past the last element in the hash, the current iterator position is undefined. In this case the undef_item exception is thrown, if enabled.

Results:

A pointer to Key at the current iterator element is returned. If the current element is undefined, an undefined pointer is returned.

See also:

WCIterExcept::undef_item, WCPtrHashDictIter<Key,Value>::operator ()(), WCPtrHashDictIter<Key,Value>::operator ++(), WCPtrHashDictIter<Key,Value>::reset()

WCPtrHashDictIter<Key,Value>::operator ()()

the call operator for the class

Synopsis:

#include <wchiter.h>
public:
int operator ()();

Semantics:

The operator ()() public member function is the call operator for the class. The hash element that follows the current item is set to be the new current item. If the previous current item is the last element in the hash, the iterator is positioned after the end of the hash.

The operator ()() public member function has the same semantics as the pre-increment operator, operator ++().

If the iterator is positioned before the first hash element, the current item is set to the first element. If the hash is empty, the iterator is positioned after the end of the hash.

If the iterator isn't associated with a hash, or the iterator position before the increment is past the last element in the hash, the undef_iter exception is thrown, if enabled.

Results:

The operator ()() public member function returns a non-zero value if the iterator is positioned on a hash item. It returns 0 when the iterator is incremented past the end of the hash.

See also:

WCIterExcept::undef_iter, WCPtrHashDictIter<Key,Value>::operator ++(), WCPtrHashDictIter<Key,Value>::reset()

WCPtrHashDictIter<Key,Value>::operator ++()

the pre-increment operator for the class

Synopsis:

#include <wchiter.h>
public:
int operator ++();

Semantics:

The operator ++() public member function is the pre-increment operator for the class. The hash element that follows the current item is set to be the new current item. If the previous current item is the last element in the hash, the iterator is positioned after the end of the hash.

The operator ++() public member function has the same semantics as the call operator, operator ()().

The current item is set to the first hash element if the iterator is positioned before the first element in the hash. If the hash is empty, the iterator is positioned after the end of the hash.

If the iterator isn't associated with a hash, or the iterator position before the increment is past the last element in the hash, the undef_iter exception is thrown, if enabled.

Results:

The operator ++() public member function returns a non-zero value if the iterator is positioned on a hash item. It returns 0 when the iterator is incremented past the end of the hash.

See also:

WCIterExcept::undef_iter, WCPtrHashDictIter<Key,Value>::operator ()(), WCPtrHashDictIter<Key,Value>::reset()

WCPtrHashDictIter<Key,Value>::reset()

reset the iterator to the initial state

Synopsis:

#include <wchiter.h>
public:
void reset();
void reset( WCPtrHashDict<Key,Value> & );

Semantics:

The first form of the reset() public member function resets the iterator to the initial state, positioning the iterator before the first element in the associated hash.

The second form of this function resets the iterator to operate on the specified hash. The iterator is positioned before the first element in the hash.

Results:

The iterator is positioned before the first hash element.

See also:

WCPtrHashDictIter<Key,Value>::WCPtrHashDictIter(), WCPtrHashDictIter<Key,Value>::container()

WCPtrHashDictIter<Key,Value>::value()

return a pointer to the Value at the current iterator position

Synopsis:

#include <wchiter.h>
public:
Value * value();

Semantics:

The value() public member function returns a pointer to the Value at the current iterator position.

If the iterator isn't associated with a hash, or the iterator position is either before the first element or past the last element in the hash, the current iterator position is undefined. In this case the undef_item is thrown, if enabled.

Results:

A pointer to the Value at the current iterator element is returned. If the current element is undefined, an undefined pointer is returned.

See also:

WCIterExcept::undef_item, WCPtrHashDictIter<Key,Value>::operator ()(), WCPtrHashDictIter<Key,Value>::operator ++(), WCPtrHashDictIter<Key,Value>::reset()

WCValHashDictIter<Key,Value> Class

Declared:

wchiter.h

The WCValHashDictIter<Key,Value> class is the templated class used to create iterator objects for WCValHashDict<Key,Value> hash objects. In the description of each member function,

  • the text Key is used to indicate the template parameter defining the type of the indices used to store data in the dictionary
  • the text Value is used to indicate the template parameter defining the type of the data stored in the dictionary.

The WCIterExcept class is a base class of the WCValHashDictIter<Key,Value> class, and provides the exceptions() member function. This member function controls the exceptions that can be thrown by the WCValHashDictIter object. No exceptions are enabled unless they're set by the exceptions() member function.

Public Member Functions

The following member functions are declared in the public interface: 

WCValHashDictIter();
WCValHashDictIter( const WCValHashDict<Key,Value> & );
~WCValHashDictIter();
const WCValHashDict<Key,Value> *container() const;
Key key();
void reset();
void reset( WCValHashDict<Key,Value> & );
Value value();

Public Member Operators

The following member operators are declared in the public interface: 

int operator ()();
int operator ++();

WCValHashDictIter<Key,Value>::WCValHashDictIter()

create a WCValHashDictIter<Key,Value> object

Synopsis:

#include <wchiter.h>
public:
WCValHashDictIter();
WCValHashDictIter( WCValHashDict<Key,Value> & );

Semantics:

The public WCValHashDictIter<Key,Value> constructor is available in two forms:

  • The first is the default constructor for the class, and initializes the iterator with no hash to operate on. The reset() member function must be called to provide the iterator with a hash to iterate over.
  • The second form of the constructor initializes the iterator to operate on the WCValHashDict hash object passed as an argument. The iterator is positioned before the first hash element. To position the iterator to a valid element within the hash, increment it using one of the operator ++() or operator ()() operators.

Results:

The public WCValHashDictIter<Key,Value> constructor creates a WCValHashDictIter hash iterator object.

See also:

WCValHashDictIter<Key,Value>::~WCValHashDictIter(), WCValHashDictIter<Key,Value>::operator ()(), WCValHashDictIter<Key,Value>::operator ++(), WCValHashDictIter<Key,Value>::reset()

WCValHashDictIter<Key,Value>::~WCValHashDictIter()

destroy a WCValHashDictIter<Key,Value> object

Synopsis:

#include <wchiter.h>
public:
~WCValHashDictIter();

Semantics:

The public WCValHashDictIter<Key,Value> destructor is the destructor for the class. The call to this destructor is inserted implicitly by the compiler at the point where the WCValHashDictIter hash iterator object goes out of scope.

Results:

The WCValHashDictIter hash iterator object is destroyed.

See also:

WCValHashDictIter<Key,Value>::WCValHashDictIter()

WCValHashDictIter<Key,Value>::container()

return a pointer to the hash container object

Synopsis:

#include <wchiter.h>
public:
WCValHashDict<Key,Value> * container() const;

Semantics:

The container() public member function returns a pointer to the hash container object. If the iterator hasn't been initialized with a hash object, and the undef_iter exception is enabled, the exception is thrown.

Results:

A pointer to the hash object associated with the iterator is returned, or NULL(0) if the iterator hasn't been initialized with a hash.

See also:

WCIterExcept::undef_iter, WCValHashDictIter<Key,Value>::WCValHashDictIter(), WCValHashDictIter<Key,Value>::reset()

WCValHashDictIter<Key,Value>::key()

return the value of the Key value of the current hash item

Synopsis:

#include <wchiter.h>
public:
Key key();

Semantics:

The key() public member function returns the value of Key at the current iterator position.

If the iterator isn't associated with a hash, or the iterator position is either before the first element or past the last element in the hash, the current iterator position is undefined. In this case the undef_item exception is thrown, if enabled.

Results:

The value of Key at the current iterator element is returned. If the current element is undefined, a default initialized object is returned.

See also:

WCIterExcept::undef_item, WCValHashDictIter<Key,Value>::operator ()(), WCValHashDictIter<Key,Value>::operator ++(), WCValHashDictIter<Key,Value>::reset()

WCValHashDictIter<Key,Value>::operator ()()

the call operator for the class

Synopsis:

#include <wchiter.h>
public:
int operator ()();

Semantics:

The operator ()() public member function is the call operator for the class. The hash element that follows the current item is set to be the new current item. If the previous current item is the last element in the hash, the iterator is positioned after the end of the hash.

The operator ()() public member function has the same semantics as the pre-increment operator, operator ++().

If the iterator is positioned before the first hash element, the current item is set to the first element. If the hash is empty, the iterator is positioned after the end of the hash.

If the iterator isn't associated with a hash, or the iterator position before the increment is past the last element in the hash, the undef_iter exception is thrown, if enabled.

Results:

The operator ()() public member function returns a non-zero value if the iterator is positioned on a hash item. It returns 0 when the iterator is incremented past the end of the hash.

See also:

WCIterExcept::undef_iter, WCValHashDictIter<Key,Value>::operator ++(), WCValHashDictIter<Key,Value>::reset()

WCValHashDictIter<Key,Value>::operator ++()

the pre-increment operator for the class

Synopsis:

#include <wchiter.h>
public:
int operator ++();

Semantics:

The operator ++() public member function is the pre-increment operator for the class. The hash element that follows the current item is set to be the new current item. If the previous current item is the last element in the hash, the iterator is positioned after the end of the hash.

The operator ++() public member function has the same semantics as the call operator, operator ()().

The current item is set to the first hash element if the iterator is positioned before the first element in the hash. If the hash is empty, the iterator is positioned after the end of the hash.

If the iterator isn't associated with a hash, or the iterator position before the increment is past the last element in the hash, the undef_iter exception is thrown, if enabled.

Results:

The operator ++() public member function returns a non-zero value if the iterator is positioned on a hash item. It returns 0 when the iterator is incremented past the end of the hash.

See also:

WCIterExcept::undef_iter, WCValHashDictIter<Key,Value>::operator ()(), WCValHashDictIter<Key,Value>::reset()

WCValHashDictIter<Key,Value>::reset()

position the iterator before the first hash element

Synopsis:

#include <wchiter.h>
public:
void reset();
void reset( WCValHashDict<Key,Value> & );

Semantics:

The first form of the reset() public member function resets the iterator to the initial state, positioning the iterator before the first element in the associated hash.

The second form of this function resets the iterator to operate on the specified hash. The iterator is positioned before the first element in the hash.

Results:

The iterator is positioned before the first hash element.

See also:

WCValHashDictIter<Key,Value>::WCValHashDictIter(), WCValHashDictIter<Key,Value>::container()

WCValHashDictIter<Key,Value>::value()

return the value of the Value at the current iterator position

Synopsis:

#include <wchiter.h>
public:
Value value();

Semantics:

The value() public member function returns the value of Value at the current iterator position.

If the iterator isn't associated with a hash, or the iterator position is either before the first element or past the last element in the hash, the current iterator position is undefined. In this case the undef_item exception is thrown, if enabled.

Results:

The value of the Value at the current iterator element is returned. If the current element is undefined, a default initialized object is returned.

See also:

WCIterExcept::undef_item, WCValHashDictIter<Key,Value>::operator ()(), WCValHashDictIter<Key,Value>::operator ++(), WCValHashDictIter<Key,Value>::reset()

WCPtrHashTableIter<Type>, WCPtrHashSetIter<Type> Classes

Declared:

wchiter.h

The WCPtrHashTableIter<Type> and WCPtrHashSetIter classes are the templated classes used to create iterator objects for WCPtrHashTable<Type> and WCPtrHashSet<Type> hash objects. In the description of each member function, the text Type is used to indicate the hash element type specified as the template parameter.

The WCIterExcept class is a base class of the WCPtrHashTableIter<Type> and WCPtrHashSetIter classes, and provides the exceptions() member function. This member function controls the exceptions that can be thrown by the WCPtrHashTableIter and WCPtrHashSetIter objects. No exceptions are enabled unless they're set by the exceptions() member function.

Public Member Functions

The following member functions are declared in the public interface: 

WCPtrHashSetIter();
WCPtrHashSetIter( const WCPtrHashSet<Type> & );
~WCPtrHashSetIter();

WCPtrHashTableIter();
WCPtrHashTableIter( const WCPtrHashTable<Type> & );
~WCPtrHashTableIter();

const WCPtrHashSet<Type> * container() const;
const WCPtrHashTable<Type> * container() const;
Type * current() const;
void reset();
void WCPtrHashSetIter<Type>::reset( 
        WCPtrHashSet<Type> & );
void WCPtrHashTableIter<Type>::reset( 
        WCPtrHashTable<Type> & );

Public Member Operators

The following member operators are declared in the public interface: 

int operator ()();
int operator ++();

WCPtrHashSetIter<Type>::WCPtrHashSetIter()

create a WCPtrHashSetIter<Type> object

Synopsis:

#include <wchiter.h>
public:
WCPtrHashSetIter();
WCPtrHashSetIter( WCPtrHashSet<Type> & );

Semantics:

The public WCPtrHashSetIter<Type> constructor is available in two forms:

  • The first is the default constructor for the class, and initializes the iterator with no hash to operate on. The reset() member function must be called to provide the iterator with a hash to iterate over.
  • The second form initializes the iterator to operate on the WCPtrHashSet<Type> hash object passed as the parameter. The iterator is positioned before the first hash element. To position the iterator to a valid element within the hash, increment it using one of the operator ++() or operator ()() operators.

Results:

The public WCPtrHashSetIter<Type> constructor creates an initialized WCPtrHashSetIter hash iterator object.

See also:

WCPtrHashSetIter<Type>::~WCPtrHashSetIter(), WCPtrHashSetIter<Type>::operator ()(), WCPtrHashSetIter<Type>::operator ++(), WCPtrHashSetIter<Type>::reset(), WCPtrHashTableIter<Type>::WCPtrHashTableIter()

WCPtrHashSetIter<Type>::~WCPtrHashSetIter()

destroy a WCPtrHashSetIter<Type> object

Synopsis:

#include <wchiter.h>
public:
~WCPtrHashSetIter();

Semantics:

This function is the public WCPtrHashSetIter<Type> destructor for the class. The call to this destructor is inserted implicitly by the compiler at the point where the WCPtrHashSetIter hash iterator object goes out of scope.

Results:

The WCPtrHashSetIter hash iterator object is destroyed.

See also:

WCPtrHashSetIter<Type>::WCPtrHashSetIter(), WCPtrHashTableIter<Type>::WCPtrHashTableIter()

WCPtrHashTableIter::WCPtrHashTableIter()

create a WCPtrHashTableIter<Type> object

Synopsis:

#include <wchiter.h>
public:
WCPtrHashTableIter();
WCPtrHashTableIter( WCPtrHashTable<Type> & );

Semantics:

The WCPtrHashTableIter<Type> constructor is available in two forms:

  • The first is the default constructor for the class, and initializes the iterator with no hash to operate on. The reset() member function must be called to provide the iterator with a hash to iterate over.
  • The second form initializes the iterator to operate on the WCPtrHashTable<Type> hash passed as a parameter. The iterator is positioned before the first hash element. To position the iterator to a valid element within the hash, increment it using one of the operator ++() or operator ()() operators.

Results:

The public WCPtrHashTableIter<Type> constructor creates an initialized WCPtrHashTableIter hash iterator object.

See also:

WCPtrHashSetIter<Type>::WCPtrHashSetIter(), WCPtrHashTableIter<Type>::~WCPtrHashTableIter(), WCPtrHashTableIter<Type>::operator ()(), WCPtrHashTableIter<Type>::operator ++(), WCPtrHashTableIter<Type>::reset()

WCPtrHashTableIter::~WCPtrHashTableIter()

destroy a WCPtrHashTableIter object

Synopsis:

#include <wchiter.h>
public:
~WCPtrHashTableIter();

Semantics:

This function is the public WCPtrHashTableIter<Type> destructor for the class. The call to this destructor is inserted implicitly by the compiler at the point where the WCPtrHashSetIter hash iterator object goes out of scope.

Results:

The WCPtrHashTableIter hash iterator object is destroyed.

See also:

WCPtrHashSetIter<Type>::WCPtrHashSetIter(), WCPtrHashTableIter<Type>::WCPtrHashTableIter()

WCPtrHashTableIter<Type>::container(), WCPtrHashSetIter::container()

return a pointer to the hash container object

Synopsis:

#include <wchiter.h>
public:
WCPtrHashTable<Type> * 
    WCPtrHashTableIter<Type>::container() const;
WCPtrHashSet<Type> * 
    WCPtrHashSetIter<Type>::container() const;

Semantics:

The container() public member function returns a pointer to the hash container object. If the iterator hasn't been initialized with a hash object, and the undef_iter exception is enabled, the exception is thrown.

Results:

A pointer to the hash object associated with the iterator is returned, or NULL(0) if the iterator hasn't been initialized with a hash.

See also:

WCIterExcept::undef_iter, WCPtrHashSetIter<Type>::WCPtrHashSetIter(), WCPtrHashSetIter<Type>::reset(), WCPtrHashTableIter<Type>::WCPtrHashTableIter(), WCPtrHashTableIter<Type>::reset()

WCPtrHashTableIter<Type>::current(), WCPtrHashSetIter<Type>::current()

return a pointer to the current hash element

Synopsis:

#include <wchiter.h>
public:
Type * current();

Semantics:

The current() public member function returns a pointer to the hash item at the current iterator position.

If the iterator isn't associated with a hash, or the iterator position is either before the first element or past the last element in the hash, the current iterator position is undefined. In this case the undef_item exception is thrown, if enabled.

Results:

A pointer to the current iterator element is returned. If the current element is undefined, NULL(0) is returned.

See also:

WCIterExcept::undef_item, WCPtrHashSetIter<Type>::operator ()(), WCPtrHashSetIter<Type>::operator ++(), WCPtrHashSetIter<Type>::reset(), WCPtrHashTableIter<Type>::operator ()(), WCPtrHashTableIter<Type>::operator ++(), WCPtrHashTableIter<Type>::reset()

WCPtrHashTableIter<Type>::operator ()(), WCPtrHashSetIter<Type>::operator ()()

the call operator for the class

Synopsis:

#include <wchiter.h>
public:
int operator ()();

Semantics:

The operator ()() public member function is the call operator for the class. The hash element that follows the current item is set to be the new current item. If the previous current item is the last element in the hash, the iterator is positioned after the end of the hash.

The operator ()() public member function has the same semantics as the pre-increment operator, operator ++().

If the iterator is positioned before the first hash element, the current item is set to the first element. If the hash is empty, the iterator is positioned after the end of the hash.

If the iterator isn't associated with a hash, or the iterator position before the increment was past the last element in the hash, the undef_iter exception is thrown, if enabled.

Results:

The operator ()() public member function returns a non-zero value if the iterator is positioned on a hash item. It returns 0 when the iterator is incremented past the end of the hash.

See also:

WCIterExcept::undef_iter, WCPtrHashSetIter<Type>::operator ++(), WCPtrHashSetIter<Type>::reset(), WCPtrHashTableIter<Type>::operator ++(), WCPtrHashTableIter<Type>::reset()

WCPtrHashTableIter<Type>::operator ++(), WCPtrHashSetIter<Type>::operator ++()

the pre-increment operator for the class

Synopsis:

#include <wchiter.h>
public:
int operator ++();

Semantics:

The operator ++() public member function is the pre-increment operator for the class. The hash element that follows the current item is set to be the new current item. If the previous current item is the last element in the hash, the iterator is positioned after the end of the hash.

The operator ++() public member function has the same semantics as the call operator, operator ()().

The current item is set to the first hash element if the iterator was positioned before the first element in the hash. If the hash is empty, the iterator is positioned after the end of the hash.

If the iterator isn't associated with a hash or the iterator position before the increment is past the last element in the hash, the undef_iter exception is thrown, if enabled.

Results:

The operator ++() public member function returns a non-zero value if the iterator is positioned on a hash item. It returns 0 when the iterator is incremented past the end of the hash.

See also:

WCIterExcept::undef_iter, WCPtrHashSetIter<Type>::current(), WCPtrHashSetIter<Type>::operator ()(), WCPtrHashSetIter<Type>::reset(), WCPtrHashTableIter<Type>::current(), WCPtrHashTableIter<Type>::operator ()(), WCPtrHashTableIter<Type>::reset()

WCPtrHashTableIter<Type>::reset(), WCPtrHashSetIter<Type>::reset()

position the iterator before the first hash

Synopsis:

#include <wchiter.h>
public:
void reset();
void WCPtrHashTableIter<Type>::reset( 
        WCPtrHashTable<Type> & );
void WCPtrHashSetIter<Type>::reset( 
        WCPtrHashSet<Type> & );

Semantics:

The first form of the reset() public member function resets the iterator to the initial state, positioning the iterator before the first element in the associated hash.

The second and third forms reset the iterator to operate on the specified hash. The iterator is positioned before the first element in the hash.

Results:

The iterator is positioned before the first hash element.

See also:

WCPtrHashSetIter<Type>::WCPtrHashSetIter(), WCPtrHashSetIter<Type>::container() WCPtrHashTableIter<Type>::WCPtrHashTableIter(), WCPtrHashTableIter<Type>::container()

WCValHashTableIter<Type>, WCValHashSetIter<Type> Classes

Declared:

wchiter.h

The WCValHashTableIter<Type> and WCValHashSetIter<Type> classes are the templated classes used to create iterator objects for WCValHashTable and WCValHashSet hash objects. In the description of each member function, the text Type is used to indicate the hash element type specified as the template parameter.

The WCIterExcept class is a base class of the WCValHashTableIter<Type> and WCValHashSetIter<Type> classes, and provides the exceptions() member function. This member function controls the exceptions that can be thrown by the WCValHashTableIter and WCValHashSetIter objects. No exceptions are enabled unless they are set by the exceptions() member function.

Public Member Functions

The following member functions are declared in the public interface: 

WCValHashSetIter();
WCValHashSetIter( const WCValHashSet<Type> & );
~WCValHashSetIter();

WCValHashTableIter();
WCValHashTableIter( const WCValHashTable<Type> & );
~WCValHashTableIter();

const WCValHashSet<Type> * container() const;
const WCValHashTable<Type> * container() const;
Type current() const;
void reset();
void WCValHashSetIter<Type>::reset( 
        WCValHashSet<Type> & );
void WCValHashTableIter<Type>::reset( 
        WCValHashTable<Type> & );

Public Member Operators

The following member operators are declared in the public interface: 

int operator ()();
int operator ++();

WCValHashSetIter<Type>::WCValHashSetIter()

create a WCValHashSetIter<Type> object

Synopsis:

#include <wchiter.h>
public:
WCValHashSetIter();
WCValHashSetIter( WCValHashSet<Type> & );

Semantics:

The public WCValHashSetIter<Type> constructor available in two forms:

  • The first is the default constructor for the class, and initializes the iterator with no hash to operate on. The reset() member function must be called to provide the iterator with a hash to iterate over.
  • The second form initializes the iterator to operate on the WCValHashSet<Type> hash passed as a parameter. The iterator is positioned before the first hash element. To position the iterator to a valid element within the hash, increment it using one of the operator ++() or operator ()() operators.

Results:

The public WCValHashSetIter<Type> constructor creates an initialized WCValHashSetIter hash iterator object.

See also:

WCValHashSetIter<Type>::~WCValHashSetIter(), WCValHashSetIter<Type>::operator ()(), WCValHashSetIter<Type>::operator ++(), WCValHashSetIter<Type>::reset(), WCValHashTableIter<Type>::WCValHashTableIter()

WCValHashSetIter<Type>::~WCValHashSetIter()

destroy a WCValHashSetIter<Type> object

Synopsis:

#include <wchiter.h>
public:
~WCValHashSetIter();

Semantics:

This function is the public WCValHashSetIter<Type> destructor for the class. The call to it is inserted implicitly by the compiler at the point where the WCValHashSetIter hash iterator object goes out of scope.

Results:

The WCValHashSetIter hash iterator object is destroyed.

See also:

WCValHashSetIter<Type>::WCValHashSetIter(), WCValHashTableIter<Type>::WCValHashTableIter()

WCValHashTableIter::WCValHashTableIter()

create a WCValHashTableIter<Type> object

Synopsis:

#include <wchiter.h>
public:
WCValHashTableIter();
WCValHashTableIter( WCValHashTable<Type> & );

Semantics:

The WCValHashTableIter<Type> constructor is available in two forms:

  • The first is the default constructor for the class, and initializes the iterator with no hash to operate on. The reset() member function must be called to provide the iterator with a hash to iterate over.
  • The second form initializes the iterator to operate on the WCValHashTable hash object passed as a parameter. The iterator is positioned before the first hash element. To position the iterator to a valid element within the hash, increment it using one of the operator ++() or operator ()() operators.

Results:

The public WCValHashTableIter constructor creates an initialized WCValHashTableIter object.

See also:

WCValHashSetIter<Type>::WCValHashSetIter(), WCValHashTableIter<Type>::~WCValHashTableIter(), WCValHashTableIter<Type>::operator ()(), WCValHashTableIter<Type>::operator ++(), WCValHashTableIter<Type>::reset()

WCValHashTableIter::~WCValHashTableIter()

destroy a WCValHashTableIter object

Synopsis:

#include <wchiter.h>
public:
~WCValHashTableIter();

Semantics:

This function is the public WCValHashTableIter <Type> destructor for the class. The call to it is inserted implicitly by the compiler at the point where the WCValHashTableIter hash iterator object goes out of scope.

Results:

The WCValHashTableIter hash iterator object is destroyed.

See also:

WCValHashSetIter<Type>::WCValHashSetIter(), WCValHashTableIter<Type>::WCValHashTableIter()

WCValHashTableIter<Type>::container(), WCValHashSetIter<Type>::container()

return a pointer to the hash container object

Synopsis:

#include <wchiter.h>
public:
WCValHashTable<Type> * container() const;
WCValHashSet<Type> * container() const;

Semantics:

The container() public member function returns a pointer to the hash container object. If the iterator hasn't been initialized with a hash object, and the undef_iter exception is enabled, the exception is thrown.

Results:

A pointer to the hash object associated with the iterator is returned, or NULL(0) if the iterator hasn't been initialized with a hash.

See also:

WCIterExcept::undef_iter, WCValHashSetIter<Type>::WCValHashSetIter(), WCValHashSetIter<Type>::reset() WCValHashTableIter<Type>::WCValHashTableIter(), WCValHashTableIter<Type>::reset()

WCValHashTableIter<Type>::current(), WCValHashSetIter<Type>::current()

return a pointer to the hash item at the current iterator position

Synopsis:

#include <wchiter.h>
public:
Type current();

Semantics:

The current() public member function returns the value of the hash element at the current iterator position.

If the iterator isn't associated with a hash, or the iterator position is either before the first element or past the last element in the hash, the current iterator position is undefined. In this case the undef_item exception is thrown, if enabled.

Results:

The value at the current iterator element is returned. If the current element is undefined, a default initialized object is returned.

See also:

WCIterExcept::undef_item, WCValHashSetIter<Type>::operator ()(), WCValHashSetIter<Type>::operator ++(), WCValHashSetIter<Type>::reset() WCValHashTableIter<Type>::operator ()(), WCValHashTableIter<Type>::operator ++(), WCValHashTableIter<Type>::reset()

WCValHashTableIter<Type>::operator ()(), WCValHashSetIter<Type>::operator ()()

the call operator for the class

Synopsis:

#include <wchiter.h>
public:
int operator ()();

Semantics:

The operator ()() public member function is the call operator for the class. The hash element that follows the current item is set to be the new current item. If the previous current item was the last element in the hash, the iterator is positioned after the end of the hash.

The operator ()() public member function has the same semantics as the pre-increment operator, operator ++().

If the iterator was positioned before the first hash element, the current item is set to the first element. If the hash is empty, the iterator is positioned after the end of the hash.

If the iterator isn't associated with a hash, or the iterator position before the increment was past the last element in the hash, the undef_iter exception is thrown, if enabled.

Results:

The operator ()() public member function returns a non-zero value if the iterator is positioned on a hash item. It returns 0 when the iterator is incremented past the end of the hash.

See also:

WCIterExcept::undef_iter, WCValHashSetIter<Type>::operator ++(), WCValHashSetIter<Type>::reset() WCValHashTableIter<Type>::operator ++(), WCValHashTableIter<Type>::reset()

WCValHashTableIter<Type>::operator ++(), WCValHashSetIter<Type>::operator ++()

the pre-increment operator for the class

Synopsis:

#include <wchiter.h>
public:
int operator ++();

Semantics:

The operator ++() public member function is the pre-increment operator for the class. The hash element that follows the current item is set to be the new current item. If the previous current item was the last element in the hash, the iterator is positioned after the end of the hash.

The operator ++() public member function has the same semantics as the call operator, operator ()().

The current item is set to the first hash element if the iterator was positioned before the first element in the hash. If the hash is empty, the iterator is positioned after the end of the hash.

If the iterator isn't associated with a hash, or the iterator position before the increment is past the last element in the hash, the undef_iter exception is thrown, if enabled.

Results:

The operator ++() public member function returns a non-zero value if the iterator is positioned on a hash item. It returns 0 when the iterator is incremented past the end of the hash.

See also:

WCIterExcept::undef_iter, WCValHashSetIter<Type>::current(), WCValHashSetIter<Type>::operator ()(), WCValHashSetIter<Type>::reset() WCValHashTableIter<Type>::current(), WCValHashTableIter<Type>::operator ()(), WCValHashTableIter<Type>::reset()

WCValHashTableIter<Type>::reset(), WCValHashSetIter<Type>::reset()

position the iterator before the first hash element

Synopsis:

#include <wchiter.h>
public:
void reset();
void WCValHashTableIter<Type>::reset( 
        WCValHashTable<Type> & );
void WCValHashSetIter<Type>::reset( 
        WCValHashSet<Type> & );

Semantics:

The first form of the reset() public member function resets the iterator to the initial state, positioning the iterator before the first element in the associated hash.

The second and third forms reset the iterator to operate on the specified hash. The iterator is positioned before the first element in the hash.

Results:

The iterator is positioned before the first hash element.

See also:

WCValHashSetIter<Type>::WCValHashSetIter(), WCValHashSetIter<Type>::container() WCValHashTableIter<Type>::WCValHashTableIter(), WCValHashTableIter<Type>::container()