WCExcept::wc_state

a set of bits that represents the current state of the container object

Synopsis:

#include <wcexcept.h>
public:
enum wcstate {
  all_fine       = 0x0000,  // no errors
  check_none     = all_fine,// throw no exceptions
  not_empty      = 0x0001,  // container not empty
  index_range    = 0x0002,  // index is out of 
                            // range
  empty_container= 0x0004,  // empty container 
                            // error
  out_of_memory  = 0x0008,  // allocation failed
  resize_required= 0x0010,  // request needs resize
  not_unique     = 0x0020,  // adding duplicate
  zero_buckets   = 0x0040,  // resizing hash to 
                            // zero
  // value to use to check for all errors
  check_all   = (not_empty|index_range
                 |empty_container|out_of_memory
                 |resize_required|not_unique
                 |zero_buckets)
};
typedef int wc_state;

Semantics:

The type WCExcept::wcstate is a set of bits representing the current state of the container object. The WCExcept::wc_state member type definition represents the same set of bits, but uses an int to represent the values, thereby avoiding problems made possible by the compiler's ability to use smaller types for enumerations.

You should use WCExcept::wc_state, not WCExcept::wcstate.

The bit values defined by the WCExcept::wc_state member type definition can be read and set by the exceptions() member function, which is also used to control exception handling. The bit values are as follows:

WCExcept::not_empty

This bit setting traps the destruction of a container when the container has one or more entries. If this error isn't trapped, memory might not be properly released back to the system.

WCExcept::index_range

This state setting traps an attempt to access a container item by an index value that is either not positive or is larger than the index of the last item in the container.

WCExcept::empty_container

This bit setting traps an attempt to perform an invalid operation on a container with no entries.

WCExcept::out_of_memory

This bit setting traps any container class allocation failures. If this exception isn't enabled, the operation in which the allocation failed returns a FALSE (zero) value. Container class copy constructors and assignment operators can also throw this exception; if it isn't enabled, incomplete copies may result.

WCExcept::resize_required

This bit setting traps any vector operations that can't be performed unless the vector is made larger. If this exception isn't enabled, the vector class attempts an appropriate resize when necessary for an operation.

WCExcept::not_unique

This bit setting traps an attempt to add a duplicate value to a set container, or a duplicate key to a dictionary container. The duplicate value isn't added to the container object, regardless of the exception trap state.

WCExcept::zero_buckets

This bit setting traps an attempt to resize a hash container to have zero buckets. No resize is performed, whether or not the exception is enabled.

See also:

exceptions()

WCIterExcept Class

Declared:

wcexcept.h

The WCIterExcept class provides the exception handling for the container iterators. If you've compiled your code with exception handling enabled, the C++ exception processing can be used to catch errors.

---

Your source file must be compiled with the exception handling compile switch for C++ exception processing to occur; see the section ``C++ Exception Handling'' in the C/C++ Compiler Options chapter of the Watcom Compiler & Tools User's Guide.

---

The iterators attempt to set the class into a reasonable state if there is an error and exception handling isn't enabled, or if the trap for the specific error hasn't been enabled by your program.

By default, no exception traps are enabled, and no exceptions are thrown. Exception traps are enabled by setting the exception state with the exceptions() member function.

The wcexcept.h header file is included by the header files for each of the iterator classes. There's normally no need to include the wcexcept.h header file explicitly, but no errors result if you do. This class is inherited as part of the base construction for each of the iterators. You don't need to derive from it directly.

Public Enumerations

The following enumeration typedefs are declared in the public interface:

typedef int wciter_state;

Public Member Functions

The following public member functions are declared:

WCIterExcept();
virtual ~WCIterExcept();
wciter_state exceptions() const;
wciter_state exceptions( wciter_state );

WCIterExcept::WCIterExcept()

create a WCIterExcept object

Synopsis:

#include <wcexcept.h>
public:
WCIterExcept();

Semantics:

The public WCIterExcept constructor creates a WCIterExcept object.

This constructor is used implicitly by the compiler when it generates a constructor for a derived class.

Results:

This constructor produces an initialized WCIterExcept object with no exception traps enabled.

See also:

WCIterExcept::~WCIterExcept()

WCIterExcept::~WCIterExcept()

destroy a WCIterExcept object

Synopsis:

#include <wcexcept.h>
public:
virtual ~WCIterExcept();

Semantics:

The public WCIterExcept destructor doesn't do anything explicit. The call to it is inserted implicitly by the compiler at the point where the object derived from WCIterExcept goes out of scope.

Results:

The object derived from WCIterExcept is destroyed.

See also:

WCIterExcept::WCIterExcept()

WCIterExcept::exceptions()

query and/or set bits that enable exceptions for the iterator classes

Synopsis:

#include <wcexcept.h>
public:
wciter_state exceptions() const;
wciter_state exceptions( wciter_state set_flags );

Semantics:

The exceptions() public member function queries and/or sets the bits that control which exceptions are enabled for the iterator class. Each bit corresponds to an exception, and is set if the exception is enabled.

The first form of the function returns the current settings of the exception bits; the second form sets the exception bits to those specified by set_flags.

Results:

The first form returns the current set of exception bits; the second form returns the new set.

See also:

wciter_state

WCIterExcept::wciter_state

a set of bits that represent the current state of the iterator

Synopsis:

#include <wcexcept.h>
public:
enum wciterstate {
  all_fine    = 0x0000,  // no errors
  check_none  = all_fine,// disable all exceptions
  undef_iter  = 0x0001,  // position is undefined
  undef_item  = 0x0002,  // iterator item is 
                         // undefined
  iter_range  = 0x0004,  // advance value is bad
  // value to use to check for all errors
  check_all   = (undef_iter|undef_item|iter_range)
};
typedef int wciter_state;

Semantics:

The type WCIterExcept::wciterstate is a set of bits representing the current state of the iterator. The WCIterExcept::wciter_state member type definition represents the same set of bits, but uses an int to represent the values, thereby avoiding problems made possible by the compiler's ability to use smaller types for enumerations.

---

You should use WCIterExcept::wciter_state, not WCIterExcept::wciterstate.

---

The bit values defined by the WCIterExcept::wciter_state member type definition can be read and set by the member function exceptions(), which is used to control exception handling. The bit values are as follows:

WCIterExcept::undef_iter

This bit setting traps the use of the iterator when the position within the container object is undefined. The following operations are undefined:

• operating on an iterator with no associated container object
• incrementing an iterator that's after the last element
• decrementing an iterator positioned before the first element

WCIterExcept::undef_item

This bit setting traps an attempt to obtain the current element of the iterator when the iterator has no associated container object, or is positioned either before or after the container elements. The undef_item exception can be thrown only by the key() and value() dictionary iterator member functions, and the current() member function for non-dictionary iterators.

WCIterExcept::iter_range

This bit setting traps an attempt to use a iteration count value that would place the iterator more than one element past the end or before the beginning of the container elements. The iter_range exception can be thrown only by the operator +=() and operator -=() operators.

See also:

exceptions()