Note that for any kind of Ptr vector (WCPtrVector, WCPtrOrderedVector,
WCPtrSortedVector), destructors are not called on the elements (on a resize, 
remove, or clear).


Header File:
============
#include <wcvector.h>


WCExcept:
=========

  This is the base class to all non-iterative container classes.  Exception
  handling is performed using this class.  By default, no exceptions will be
  thrown, and vector functions and operators will leave the vector in a valid
  state on an error.  Exceptions can be enabled to be thrown using the
  exceptions member function

  available exceptions:
  ~~~~~~~~~~~~~~~~~~~~~

    The following exceptions can be throw by vectors:
      - WCExcept::empty_container
        if an invalid operation on an empty vector
	is attempted, this error can be thrown.
      - WCExcept::index_range
        if an index value is not valid, this error can be thrown.
      - WCExcept::out_of_memory
        thrown when an attempt to insert an element, resize a vector or
	perform an assignment fails due to lack of memory.
      - WCExcept::not_empty
        if a vector was not zero length is being
  	destroyed by the destructor, this error can be thrown.
      - WCExcept::resize_required
        if an attempt was made to insert into a full vector,
  	or index a position lenght or greater in WCValVector
  	or WCPtrVector, this exception can be throw.
  	If this exception is disabled, the necessary resize
  	will be performed.

    the exceptions member function:  see WCListExcept::exceptions in the
    Container Class Library reference.


WCValVector<Type>, WCPtrVector<Type>:
=====================================

  These vectors are basic vectors.  They have a length (which can change),
  but do not keep track of the number of elements stored.  This vector can
  be used in a fashion similar to a C array (but the vector does range checking
  and can be resized).  Elements may be initialized in any order, by assigning
  to an index of a vector:

    WCValVector<int> vect( 10 );
    for( int i = 9; i >= 0; i-- ) {
	vect[ i ] = i;
    }
  

  req'd from <Type>:
  ~~~~~~~~~~~~~~~~~~

    - default constuctor
    - copy constructor
    - assignment operator
    - if the operator new function is overridded for Type, then the following
      operator new override for Type must also be specified:
    	void * operator new( size_t, void * ptr ){ return( ptr ); }
    
  public constructors/destructors:
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    - ...Vector<Type>():
       construct zero length vector

    - ...Vector<Type>( size_t s ):
       construct a vector length s (if cannot allocate memory for vector,
       vector is constructed size 0).  Conceptially, all element initialized
       by default constructor (but really only done when req'd).  Depending on
       Type's default constructor, may be initialized with garbage.

    - Val: ...Vector<Type>( size_t s, const Type & init )
    - Ptr: ...Vector<Type>( size_t s, const Type * init )
       like ...Vector<Type> with all elements initialized to init using Type's
       copy constructor

    - ...Vector( const ...Vector &orig );
       the copy constructor.  Returns a vector of orig's length and copies
       all of orig's elements.  If there was not enough memory to allocate a
       new vector, then the vector will be initialized with 0 elements.
       Includes copying the exception state.

    - ~...Vector<Type>:
       destroys this.  For the value case, the destructor is called for each
       element of the vector.  In the pointer case, the destructer is called
       on the pointer, but not the element pointed to.  In either case, if
       the vector is not length zero, the not_empty exception will be thrown
       if enabled (making a vector length zero can be done with the clear or
       clearAndDestroy member functions).
       
  public operators
  ~~~~~~~~~~~~~~~~

    - Type& operator[] ( int i )
    - const Type &operator[] ( int i ) const
      The vector index operation.  i < 0 will raise an
      index_range exception if enabled.  If i > (vector length - 1) will throw
      a resize_required exception if enabled.  If index_range is not enabled and
      i < 0 indexes element 0.  If resize_required is not enabled and
      i >= vector length on a non-const operator then:
        attempt to resize vector
	  - if that fails, out_of_memory thrown if enabled
	    or if out_of_memory not enabled, vector remains unchanged, and
	    indexes ( vector length - 1 )th element
	  - if successfull, returns correct index
      on the const operator, if the vector is empty, then an empty_container
      exception is thrown if enabled, or an index_range exception is thrown if
      enabled and the empty_container exception is disabled.  If neither
      exception is enabled the element at index 0 is created, and intialized
      with the default constructor. 
      If the vector contains at least one element, the index_range is thrown
      if i < 0 or i > (vector length - 1 ), and closest valid element is
      indexed.

    - ...Vector & operator = ( const ...Vector & orig )
      The assignment operator.  'this' is assigned to be a copy of orig.
      Includes assignment of exception state.
      If there was not enough memory to perform the assignment, then 'this'
      will be a vector with 0 elements.

    - int operator==( const ...Vector &RHS ) const:
      the equivalence operator.  non-zero is returned if both vectors have
      the same address (i.e. both are the same vector).  Zero is returned
      if two vectors are not the same vector.

  public member fns
  ~~~~~~~~~~~~~~~~~

    - void clear()
      ** VAL ONLY **: call destructors for all elements in the vector.
      ** PTR AND VAL **: reinitialize the vector to be 0 length.
    
    ** PTR ONLY **
    - void clearAndDestroy()
      call delete for all pointers in the vector, and reinitialize the vector
      to be 0 length.
    
    - size_t length():
      returns the current length of vector

    - int resize( size_t new_length ):
      resize the vector to new_length, returning failure zero / success
      non-zero.
      if the out_of_memory exception is enabled, it is thrown if resize fails.
      if new_length > old length, all elements are copied, additional elements
        in vector remain uninitialized.
      if new_length < old length only new_length elements are copied, the rest
      are destroyed (the destructor is called on (Type *) in Ptr case).


WCValOrderedVector<Type>, WCPtrOrderedVector<Type>:
==================================================

  These vectors provide additional functionality, like find, insert and remove.
  The vector elements stay in the ordering in which they were inserted (ie, if
  element A has an index < element B, then after any sequence of operations
  which do not delete or reassign element A or element B is deleted, element A
  will have an index < element B.
  New elements cannot be inserted using the index operator.  The index operator
  can only index element already in the vector.
  
  req'd from <Type>:
  ~~~~~~~~~~~~~~~~~~

    - default constuctor
    - copy constructor
    - assignment operator
    - operator == (comparisons are by value, even for Ptr)
    - if the operator new function is overridded for Type, then the following
      operator new override for Type must also be specified:
    	void * operator new( size_t, void * ptr ){ return( ptr ); }
    
  public constructors/destructors:
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    - ...Vector<Type>( size_t s = WCDEFAULT_VECTOR_LENGTH
    		     , unsigned grow = WCDEFAULT_VECTOR_RESIZE_GROW );
       construct a vector length s (if cannot allocate memory for vector,
       vector is constructed size 0).  All elements are uninitialized.
       If the resize_required exception is not enabled, then the list will
       be automatically resized to have 'grow' more elements, before an
       element is inserted if the list was full.  If 'grow' is 0, and the
       resize_required exception is not enabled, then an attempt to insert
       into a list with s entries will fail, returning 0.
       

    - ...Vector( const ...Vector &orig );
       the copy constructor.  Returns a vector with copies
       all of orig's elements.  If there was not enough memory to allocate a
       new vector, then the vector will be initialized with 0 elements.
       Includes copying the exception state, and the default growth value.

    - ~...Vector();
       destroys this.  For the value case, the destructor is called for each
       entry in the vector.  In the pointer case, the
       destructer is called each pointer, but not the element pointed to.
       In either case, if
       the vector is not length zero, the not_empty exception will be thrown
       if enabled (making a vector length zero can be done with the clear or
       clearAndDestroy member functions).
       
  public operators
  ~~~~~~~~~~~~~~~~

    - Type& operator[] ( int i )
    - const Type &operator[] ( int i ) const
      The vector index operation.  i < 0 or i >= vector entries will raise an
      index_range exception if enabled.  If index_range is not enabled and
      i < 0 indexes element 0; i >= vector entries max( 0, vector entries - 1 )
      the vector is not resized.
      if the vector is empty, an empty_container exception is thrown, if
      enabled, or an index_range exception is thrown is enabled and
      empty_container disabled.  If neither exception is enabled, then
      element 0 is initialized
      with default contructor (so that the list will contain 1 element)
      and returned.  This ensures assignment to, or use of, the index operator
      will not cause a run-time error.

    - ...Vector & operator = ( const ...Vector & orig )
      The assignment operator.  'this' is assigned to be a copy of orig.
      Includes assignment of exception state.
      If there was not enough memory to perform the assignment, then 'this'
      will be a vector with 0 elements and size 0.

    - int operator==( const ...Vector &RHS ):
      the equivalence operator.  non-zero is returned if both vectors have
      the same address (i.e. both are the same vector).  Zero is returned
      if two vectors are not the same vector.

  public member fns
  ~~~~~~~~~~~~~~~~~
  unless otherwise specified, parameters listed with type "Type &" are the
  params for the ValOrderedVector, and corresponding PtrOrderedVector function
  parameters have type "Type *"

    - int WCValOrderedVector::append( const Type& new_elem )
    - int WCPtrOrderedVector::append( Type * new_elem )
      append new_elem to the end of the vector using
      insertAt( num_entries, new_elem ).  (same as insert)
    
    - void clear()
      ** VAL ONLY **: call destructors for all elements in the list.
      ** PTR AND VAL **: reinitialize the vector to be 0 length.

    ** PTR ONLY **
    - void clearAndDestroy()
      call delete for all pointers in the vector, and reinitialize the vector
      to be 0 length.
    
    - int contains( const Type &elem ) const;
      returns non-zero if elem is found in the this vector (using lin search),
      zero if not.

    - unsigned entries():
      returns the number of elements stored in the vector

    **VAL ONLY**
    - int find( const Type &elem, Type &ret_val ) const
      attempts to find elem.  If elem is found (using Type's ==), then non-zero
      is returned, and ret_val will contain the first element equal to elem
      If the vector contained no value equal to elem, zero is returned, and
      ret_val is untouched.  (uses lin search)

    **PTR ONLY**
    - Type *find( Type const * elem ) const
      returns a pointer to first element in the vector equal to the value
      pointed to by elem, or NULL if no value equal to elem is in the vector.

    - Type first() const
      returns the first element in the vector.  See operator[]() if the 
      vector is empty.

    - int index( const Type & elem ) const
      returns the index of the first value equal to elem, or -1 if no value
      equal to elem is in the vector (uses lin search).

    - int WCValOrderedVector::insert( const Type& new_elem )
    - int WCPtrOrderedVector::insert( Type * new_elem )
      append new_elem to the end of the vector using
      insertAt( num_entries, new_elem ).  (same as append)
    
    - int WCValOrderedVector::insertAt( int index, const Type& new_elem )
    - int WCPtrOrderedVector::insertAt( int index, Type * new_elem )
      insert new_elem at index, returning success or failure.
      If index == (num_entries) then new_elem will be appended to the end of the
      vector.
      If index < 0 or index > (the number of entries in the vector)
      and the index_range exception is enabled, an index_range exception is
      thrown. If exception range is disabled then:
	If index < 0 then new_elem is inserted at index 0
	If index > (num_entries) then new_elem is appended to the end of the
	  vector.
      If the vector previously
      contained vector length entries, and the resize_required exception is
      enabled, then the resize_required exception is thrown.  If the
      resize_required exception is not enabled, the vector will be grown
      by the grow parameter to the constructor (defaults to
      WCDEFAULT_VECTOR_RESIZE_GROW) when needed. If the vector must be grown
      to insert new_elem, and the resize_required exception is NOT enabled, but
      the out_of_memory exception is enabled, the out_of_memory exception will
      be thrown if resize fails.  Otherwise if the resize failed, or the grow
      parameter was 0, the vector remains unchanged and zero is returned.
      If insert at index i, then the element at index i is copied to index i+1,
      etc.  A successful insertion returns non-zero.

    - int isEmpty() const
      returns non-zero if there are no elements in the list, zero otherwise

    - Type last() const
      returns the last element in the vector.  See operator[]() if the
      vector is empty.

    - int occurrencesOf( const Type & elem ) const
      return the number of elements in the vector equal to elem using a linear
      search.

    - int WCValOrderedVector::prepend( const Type& new_elem )
    - int WCPtrOrderedVector::prepend( Type * new_elem )
      insert new_elem into index 0 of the vector, causing all other entries in
      the vector to be copied to one index higher.  
      see insertAt( 0, new_elem ).
    
    - int WCValOrderedVector::remove( const Type & elem )
    - Type *WCPtrOrderedVector::remove( const Type & elem )
      removes the first element in the vector equal to elem (using lin search).
      If, for example, the element at index i was removed, then the element
      at index i+1 is copied to index i, etc. (using assignment operator)
      If an element equal to elem is found, WCValOrderedVector returns non-zero,
      and WCPtrOrderedVector returns the pointer removed from the vector.
      If no equivalent element is found, the vector stays unchanged, and zero
      is returned.

    - unsigned removeAll( const Type & elem )
      removes all elements in the vector equal to elem (using lin search).
      This is done so that only elements which must be moved are moved, and
      no element is moved more than once.  (vector order remains unchanged)
      The number of elements removed is returned.

    - int WCValOrderedVector::removeAt( int index )
    - Type *WCPtrOrderedVector::removeAt( int index )
      remove the element at index.  If the vector is empty, then an
      empty_containter exception is thrown, if enabled.  If empty_container is
      disabled, then zero is returned.  If index < 0 or index > (the
      number of entries in the vector - 1) and the index_range
      exception is enabled, an exception range exception is thrown.  If
      index < 0 and the index_range exception is disabled, element 0 is
      removed and returned.  If index > (num_entries - 1) and index_range is
      disabled, element (num_entries - 1) is removed and returned.
      If element at index i is removed, then the element at index i+1 is copied
      to index i, etc. (using assignment operator)

    - int WCValOrderedVector::removeFirst()
    - Type *WCPtrOrderedVector::removeFirst()
      remove the first element in the vector.  See removeAt( 0 ).

    - int WCValOrderedVector::removeLast()
    - Type *WCPtrOrderedVector::removeLast()
      remove the last element in the vector.  If the vector is empty
      see removeAt( num_entries - 1 ).

    - int resize( size_t new_length ):
      resize the vector to new_length, returning failure zero / success
      non-zero.
      if the out_of_memory exception is enabled, it is thrown if resize fails.
      if new_length > old length, all elements are copied, additional elements
        in vector remain uninitialized.
      if new_length < num entries only new_length elements are copied, the rest
      are destroyed (the destructor is called on (Type *) in Ptr case).
      

WCValSortedVector<Type>, WCPtrSortedVector<Type>:
==================================================

  These vectors are similar to WCValOrderedVector and WCPtrOrderedVector
  with the difference being the vector is kept in ascending sorted order, and
  all searching is done using a binary search.  The only way to insert a new
  element into the list is with the insert member function.

  CAUTION!!!:  Although the index operator (operator[]) does return an lvalue
  (i.e. assignment to the return of an index operator, vect[ 5 ] = a, is legal)
  THE ELEMENT MUST NOT BE ASSIGNED TO IN SUCH A WAY THAT IT'S EQUIVALENCE
  RELATIONS (the returns of Type's operator== and operator <) WOULD CHANGE
  IN ANY WAY.  FAILURE TO COMPLY MAY CAUSE SEARCHES TO NOT WORK PROPERLY,
  SINCE BINARY SEARCE ASSUMES A SORTED VECTOR.
  
  req'd from <Type>:
  ~~~~~~~~~~~~~~~~~~

    - default constuctor
    - copy constructor
    - assignment operator
    - operator == (comparisons are by value, even for Ptr)
    - operator <  (comparisons are by value, even for Ptr)
  
  differences from WCValOrderedVector and WCPtrOrderedVector
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    - where ever a linear search was done, a binary search is done.

    - no append, insertAt or prepend member functions.

    int WCValSortedVector::insert( const Type &new_elem )
    int WCPtrSortedVector::insert( Type * new_elem )
      is changed to find i such that all element with index < i are
      <= new_elem, and all elements with index >= i are > new_elem, then an
      insertAt( i, new_elem )
