vector.txt

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

       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.
  
  differences from WCValOrderedVector and WCPtrOrderedVector
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    - additional requirements from <Type>:
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	- operator <  with const parameters (comparisons are by value, 
	    even for Ptr)
 
    - 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 )