vector.txt

来自「开放源码的编译器open watcom 1.6.0版的源代码」· 文本 代码 · 共 429 行 · 第 1/2 页

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;
    }
  

  WCValVector requires from <Type>:
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    - default constuctor
    - copy constructor
    - 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 ); }
    - NOTE: well defined assignment operator is not required by WCValVector,
       but is required for assignment to a vector element (vect[ i ] = a)
	
    
  WCPtrVector requires from <Type>:
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    nothing
    
  public constructors/destructors:
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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

    - WCPtrVector<Type>( size_t s ):
       construct a vector length s (if cannot allocate memory for vector,
       vector is constructed size 0).  Conceptially, all elements are 
       initialized to be NULL (0).

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

    - ...Vector( const ...Vector &orig );
       the copy constructor.  Constructs 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 and 
       the out_of_memory exception thrown, if enabled in orig.
       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 not 
       called on 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.
  
  WCValOrderedVector requires 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 ); }
    - operator == with constant parameters
    
  WCPtrOrderedVector requires from <Type>:
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    - operator == with constant parameters (comparisons are by value 
        pointed to)
    
  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