WCValOrderedVector<Type> and WCValSortedVector<Type> Classes

Declared:

wcvector.h

The WCValOrderedVector<Type> and WCValSortedVector<Type> classes are templated classes used to store objects in a vector. Ordered and Sorted vectors are powerful arrays that can be resized, and provide an abstract interface to insert, find and remove elements:

• An ordered vector maintains the order in which elements are added, and allows more than one occurrence of an equivalent element.
• A sorted vector allows only one occurrence of an equivalent element, and inserts elements in a sorted order. A sorted vector is less efficient when inserting elements, but can provide a faster retrieval time.

Elements can't be inserted into these vectors by assigning to a vector index. Vectors automatically grow when necessary to insert an element if the resize_required exception isn't enabled.

In the description of each member function, the text Type is used to indicate the template parameter defining the type of the elements stored in the vector.

Values are copied into the vector, which could be undesirable if the stored objects are complicated and copying is expensive. Value vectors shouldn't be used to store objects of a base class if any derived types of different sizes would be stored in the vector, or if the destructor for a derived class must be called.

The WCValOrderedVector class stores elements in the order in which they're inserted using the insert(), append(), prepend() and insertAt() member functions. Linear searches are performed to locate entries, and the less-than operator isn't required.

The WCValSortedVector class stores elements in ascending order. Type must provide a less-than operator. Insertions are more expensive than inserting or appending into an ordered vector, since entries must be moved to make room for the new element. A binary search is used to locate elements in a sorted vector, making searches quicker than in the ordered vector.

Take care, when using the WCValSortedVector class, not to change the ordering of the vector elements. The result returned by the index operator mustn't be assigned to or modified in such a way that it's no longer equivalent to the value inserted into the vector. Lookups assume elements are in sorted order.

The WCValVector class is also available. It provides a resizable and boundary safe vector similar to standard arrays.

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

Requirements of Type

Both the WCValOrderedVector<Type> and WCValSortedVector<Type> classes require Type to have:

• a default constructor

      Type::Type()
      
  

• a well defined copy constructor

      Type::Type( const Type & )
      
  

• a well defined assignment operator

      Type & operator =( const Type & )
      
  

• the following override of operator new(), if Type overrides the global operator new()

      void * operator new( size_t, void *ptr ) 
      { return( ptr ); }
      
  

• a well defined equivalence operator with constant parameters

      int operator ==( const Type & ) const
      
  

Additionally the WCValSortedVector class requires Type to have:

• a well defined less-than operator with constant parameters

      int operator <( const Type & ) const
      
  

Public Member Functions

The following member functions are declared in the public interface:

WCValOrderedVector( size_t = WCDEFAULT_VECTOR_LENGTH,
                    unsigned = WCDEFAULT_VECTOR_RESIZE_GROW );
WCValOrderedVector( const WCValOrderedVector & );
virtual ~WCValOrderedVector();

WCValSortedVector( size_t = WCDEFAULT_VECTOR_LENGTH,
                   unsigned = WCDEFAULT_VECTOR_RESIZE_GROW );
WCValSortedVector( const WCValSortedVector & );
virtual ~WCValSortedVector();

void clear();
int contains( const Type & ) const;
unsigned entries() const;
int find( const Type &, Type & ) const;
Type first() const;
int index( const Type & ) const;
int insert( const Type & );
int isEmpty() const;
Type last() const;
int occurrencesOf( const Type & ) const;
int remove( const Type & );
unsigned removeAll( const Type & );
int removeAt( int );
int removeFirst();
int removeLast();
int resize( size_t );

The following public member functions are available for the WCValOrderedVector class only:

int append( const Type & );
int insertAt( int, const Type & );
int prepend( const Type & );

Public Member Operators

The following member operators are declared in the public interface:

Type & operator [ ]( int );
const Type & operator [ ]( int ) const;
WCValOrderedVector & WCValOrderedVector::operator =( 
    const WCValOrderedVector & );
WCValSortedVector & WCValSortedVector::operator =(
    const WCValSortedVector & );
int WCValOrderedVector::operator ==(
    const WCValOrderedVector & ) const;
int WCValSortedVector::operator ==(
    const WCValSortedVector & ) const;

WCValOrderedVector<Type>::WCValOrderedVector()

create a WCValOrderedVector<Type> object

Synopsis:

#include <wcvector.h>
public:
WCValOrderedVector( 
    size_t = WCDEFAULT_VECTOR_LENGTH,
	unsigned = WCDEFAULT_VECTOR_RESIZE_GROW );
WCValOrderedVector( const WCValOrderedVector & );

Semantics:

There are two forms of the WCValOrderedVector<Type> constructor:

• The first creates an empty WCValOrderedVector object that's able to store the number of elements specified in the first optional parameter, which defaults to the constant WCDEFAULT_VECTOR_LENGTH (currently defined as 10).

  If the resize_required exception isn't enabled, then the second optional parameter is used to specify the value to increase the vector size when an element is inserted into a full vector. If zero(0) is specified as the second parameter, any attempt to insert into a full vector fails. This parameter defaults to the constant WCDEFAULT_VECTOR_RESIZE_GROW (currently defined as 5).

  If the vector object can't be fully initialized, the vector is created with length zero.

• The second form is the copy constructor for the WCValOrderedVector class. The new vector is created with the same length and resize value as the passed vector. All of the vector elements and exception trap states are copied.

  If the new vector can't be fully created, it will have length zero. The out_of_memory exception is thrown if it's enabled in the vector being copied.

Results:

The WCValOrderedVector<Type> constructor creates an initialized WCValOrderedVector object.

See also:

WCExcept::out_of_memory, WCExcept::resize_required, WCValOrderedVector<Type>::operator =()

WCValOrderedVector<Type>::~WCValOrderedVector()

destroy a WCValOrderedVector<Type> object

Synopsis:

#include <wcvector.h>
public:
virtual ~WCValOrderedVector();

Semantics:

The WCValOrderedVector<Type> destructor is the destructor for the WCValOrderedVector class. If the vector isn't length zero and the not_empty exception is enabled, it's thrown. Otherwise, the vector entries are cleared using the clear() member function.

The call to this destructor is inserted implicitly by the compiler at the point where the WCValOrderedVector object goes out of scope.

Results:

The WCValOrderedVector object is destroyed.

See also:

WCExcept::not_empty, WCValOrderedVector<Type>::clear()

WCValSortedVector<Type>::WCValSortedVector()

create a WCValSortedVector<Type> object

Synopsis:

#include <wcvector.h>
public:
WCValSortedVector( 
    size_t = WCDEFAULT_VECTOR_LENGTH,
	unsigned = WCDEFAULT_VECTOR_RESIZE_GROW );
WCValSortedVector( const WCValSortedVector & );

Semantics:

There are two forms of the WCValSortedVector<Type> constructor:

• The first creates an empty WCValSortedVector object that's able to store the number of elements specified in the first optional parameter, which defaults to the constant WCDEFAULT_VECTOR_LENGTH (currently defined as 10).

  If the resize_required exception isn't enabled, then the second optional parameter is used to specify the value to increase the vector size when an element is inserted into a full vector. If zero(0) is specified as the second parameter, any attempt to insert into a full vector fails. This parameter defaults to the constant WCDEFAULT_VECTOR_RESIZE_GROW (currently defined as 5).

  If the vector object can't be fully initialized, the vector is created with length zero.

• The second form is the copy constructor for the WCValSortedVector class. The new vector is created with the same length and resize value as the passed vector. All of the vector elements and exception trap states are copied.

  If the new vector can't be fully created, it will have length zero. The out_of_memory exception is thrown if it's enabled in the vector being copied.

Results:

The WCValSortedVector<Type> constructor creates an empty initialized WCValSortedVector object.

See also:

WCExcept::out_of_memory, WCExcept::resize_required WCValOrderedVector<Type>::operator =()

WCValSortedVector<Type>::~WCValSortedVector()

destroy a WCValSortedVector<Type> object

Synopsis:

#include <wcvector.h>
public:
virtual ~WCValSortedVector();

Semantics:

The WCValSortedVector<Type> destructor is the destructor for the WCValSortedVector class. If the vector isn't length zero and the not_empty exception is enabled, it's thrown. Otherwise, the vector entries are cleared using the clear() member function.

The call to this destructor is inserted implicitly by the compiler at the point where the WCValSortedVector object goes out of scope.

Results:

The WCValSortedVector object is destroyed.

See also:

WCExcept::not_empty, WCValOrderedVector<Type>::clear()

WCValOrderedVector<Type>::append()

append an element to the vector

Synopsis:

#include <wcvector.h>
public:
int append( const Type & );

Semantics:

The append() public member function adds the passed element to the end of the vector. The data stored in the vector is a copy of the data passed as a parameter. This member function has the same semantics as the WCValOrderedVector::insert() member function.

---

This function isn't provided by the WCValSortedVector class, since all elements must be inserted in sorted order by the insert() member function.

---

Several different results can occur if the vector isn't large enough for the new element:

• If the resize_required exception is enabled, it's thrown.
• If the exception isn't enabled, the append fails if the amount the vector is to be grown (the second parameter to the constructor) is zero(0).
• Otherwise, the vector is automatically grown by the number of elements specified to the constructor, using the resize() member function. If resize() fails, the element isn't appended to the vector and the out_of_memory exception is thrown, if it's enabled.

Results:

The append() public member function appends an element to the WCValOrderedVector object. A TRUE (non-zero) value is returned if the append is successful; if it fails, FALSE (zero) is returned.

See also:

WCExcept::out_of_memory, WCExcept::resize_required, WCValOrderedVector<Type>::insert(), WCValOrderedVector<Type>::insertAt(), WCValOrderedVector<Type>::prepend()

WCValOrderedVector<Type>::clear(), WCValSortedVector<Type>::clear()

clear the vector

Synopsis:

#include <wcvector.h>
public:
void clear();

Semantics:

The clear() public member function is used to clear the vector so that it contains no entries, and is of size zero. Elements stored in the vector are destroyed using Type's destructor. The vector object isn't destroyed and re-created by this function, so the object destructor isn't invoked.

Results:

The clear() public member function clears the vector to have length zero and no entries.

See also:

WCValOrderedVector<Type>::~WCValOrderedVector(), WCValSortedVector<Type>::~WCValSortedVector(), WCValOrderedVector<Type>::operator =(), WCValSortedVector<Type>::operator =()

WCValOrderedVector<Type>::contains(), WCValSortedVector<Type>::contains()

determine whether or not a given value is in the vector

Synopsis:

#include <wcvector.h>
public:
int contains( const Type & ) const;

Semantics:

The contains() public member function is used to determine if a value is contained by a vector. A linear search is used by the WCValOrderedVector class to find the value; the WCValSortedVector class uses a binary search.

Results:

The contains() public member function returns a TRUE (non-zero) value if the element is found in the vector. It returns a FALSE (zero) value if the vector doesn't contain the element.

See also:

WCValOrderedVector<Type>::index(), WCValSortedVector<Type>::index(), WCValOrderedVector<Type>::find(), WCValSortedVector<Type>::find()

WCValOrderedVector<Type>::entries(), WCValSortedVector<Type>::entries()

count the elements in the vector

Synopsis:

#include <wcvector.h>
public:
unsigned entries() const;

Semantics:

The entries() public member function is used to find the number of elements that are stored in the vector.

Results:

The entries() public member function returns the number of elements in the vector.

See also:

WCValOrderedVector<Type>::isEmpty(), WCValSortedVector<Type>::isEmpty()

WCValOrderedVector<Type>::find(), WCValSortedVector<Type>::find()

find an element in the vector

Synopsis:

#include <wcvector.h>
public:
int find( const Type &, Type & ) const;

Semantics:

The find() public member function is used to find an element equivalent to the first argument. The WCValOrderedVector class uses a linear search to find the element, and the WCValSortedVector class uses a binary search.

Results:

If an equivalent element is found, a TRUE (non-zero) value is returned, and the second parameter is assigned the first equivalent value. A FALSE (zero) value is returned and the second parameter is unchanged if the element is not in the vector.

See also:

WCValOrderedVector<Type>::contains(), WCValSortedVector<Type>::contains(), WCValOrderedVector<Type>::first(), WCValSortedVector<Type>::first(), WCValOrderedVector<Type>::index(), WCValSortedVector<Type>::index(), WCValOrderedVector<Type>::last(), WCValSortedVector<Type>::last(), WCValOrderedVector<Type>::occurrencesOf(), WCValSortedVector<Type>::occurrencesOf(), WCValOrderedVector<Type>::remove(), WCValSortedVector<Type>::remove()

WCValOrderedVector<Type>::first(), WCValSortedVector<Type>::first()

return the first element in the vector

Synopsis:

#include <wcvector.h>
public:
Type first() const;

Semantics:

The first() public member function returns the first element in the vector. The element isn't removed from the vector.

If the vector is empty, one of two exceptions can be thrown:

• The empty_container exception is thrown if it's enabled.
• Otherwise, if the index_range exception is enabled, it's thrown.

If neither exception is enabled, a first element of the vector is added with a default value.

Results:

The first() public member function returns the value of the first element in the vector.

See also:

WCExcept::index_range, WCExcept::empty_container, WCValOrderedVector<Type>::last(), WCValSortedVector<Type>::last(), WCValOrderedVector<Type>::removeFirst(), WCValSortedVector<Type>::removeFirst()

WCValOrderedVector<Type>::index(), WCValSortedVector<Type>::index()

find the index of an element

Synopsis:

#include <wcvector.h>
public:
int index( const Type & ) const;

Semantics:

The index() public member function is used find the index of the first element equivalent to the passed element. A linear search is used by the WCValOrderedVector class to find the element; the WCValSortedVector class uses a binary search.

Results:

The index() public member function returns the index of the first element equivalent to the parameter. If the passed value isn't contained in the vector, negative one (-1) is returned.

See also:

WCValOrderedVector<Type>::contains(), WCValSortedVector<Type>::contains(), WCValOrderedVector<Type>::find(), WCValSortedVector<Type>::find(), WCValOrderedVector<Type>::insertAt(), WCValOrderedVector<Type>::operator [ ](), WCValSortedVector<Type>::operator [ ](), WCValOrderedVector<Type>::removeAt(), WCValSortedVector<Type>::removeAt()

WCValOrderedVector<Type>::insert(), WCValSortedVector<Type>::insert()

insert an element into the vector

Synopsis:

#include <wcvector.h>
public:
int insert( const Type & );

Semantics:

The insert() public member function inserts the value into the vector. The data stored in the vector is a copy of the data passed as a parameter.

The WCValOrderedVector::insert() function inserts the value as the last element of the vector, and has the same semantics as the WCValOrderedVector::append() member function.

A binary search is performed to determine where the value should be inserted for the WCValSortedVector::insert() function. Any elements greater than the inserted value are copied up one index (using Type's assignment operator), so that the new element is after all elements with value less than or equal to it.

Several different results can occur if the vector isn't large enough for the new element:

• If the resize_required exception is enabled, it's thrown.
• If the exception isn't enabled, the insertion fails if the amount the vector is to be grown (the second parameter to the constructor) is zero(0).
• Otherwise, the vector is automatically grown by the number of elements specified to the constructor, using the resize() member function. If resize() fails, the element isn't added to the vector, and the out_of_memory exception is thrown, if enabled.

Results:

The insert() public member function inserts an element in to the vector. A TRUE (non-zero) value is returned if the insertion is successful; If it fails, a FALSE (zero) value is returned.

See also:

WCExcept::out_of_memory, WCExcept::resize_required, WCValOrderedVector<Type>::append(), WCValOrderedVector<Type>::insertAt(), WCValOrderedVector<Type>::prepend()

WCValOrderedVector<Type>::insertAt()

insert an element in a specific location in the vector

Synopsis:

#include <wcvector.h>
public:
int insertAt( int, const Type & );

Semantics:

The insertAt() public member function inserts the second argument into the vector before the element at index given by the first argument. If the passed index is equal to the number of entries in the vector, the new value is appended to the vector as the last element. The data stored in the vector is a copy of the data passed as a parameter. All vector elements with indexes greater than or equal to the first parameter are copied (using Type's assignment operator) up one index.

---

This function isn't provided by the WCValSortedVector class, since all elements must be inserted in sorted order by the insert() member function.

---

If the passed index is negative or greater than the number of entries in the vector and the index_range exception is enabled, it's thrown. If the exception isn't enabled, the new element is inserted as the first element when the index is negative, or as the last element when the index is too large.

Several different results can occur if the vector isn't large enough for the new element:

• If the resize_required exception is enabled, it's thrown.
• If the exception isn't enabled, the insertion fails if the amount the vector is to be grown (the second parameter to the constructor) is zero(0).
• Otherwise, the vector is automatically grown by the number of elements specified to the constructor, using the resize() member function. If resize() fails, the element isn't inserted into the vector and the out_of_memory exception is thrown, if enabled.

Results:

The insertAt() public member function inserts an element into the WCValOrderedVector object before the element at the given index. A TRUE (non-zero) value is returned if the insertion is successful. If the insertion fails, a FALSE (zero) value is returned.

See also:

WCExcept::index_range, WCExcept::out_of_memory, WCExcept::resize_required, WCValOrderedVector<Type>::append(), WCValOrderedVector<Type>::insert(), WCValOrderedVector<Type>::prepend(), WCValOrderedVector<Type>::operator [ ](), WCValOrderedVector<Type>::removeAt()

WCValOrderedVector<Type>::isEmpty(), WCValSortedVector<Type>::isEmpty()

determine whether or not the vector is empty

Synopsis:

#include <wcvector.h>
public:
int isEmpty() const;

Semantics:

The isEmpty() public member function is used to determine if a vector object has any entries in it.

Results:

A TRUE value (non-zero) is returned if the vector object doesn't have any vector elements in it. A FALSE (zero) result is returned if the vector contains at least one element.

See also:

WCValOrderedVector<Type>::entries(), WCValSortedVector<Type>::entries()

WCValOrderedVector<Type>::last(), WCValSortedVector<Type>::last()

return the last element of the vector

Synopsis:

#include <wcvector.h>
public:
Type last() const;

Semantics:

The last() public member function returns the last element in the vector. The element isn't removed from the vector.

If the vector is empty, one of two exceptions can be thrown:

• The empty_container exception is thrown if it's enabled.
• Otherwise, if the index_range exception is enabled, it's thrown.

If neither exception is enabled, a first element of the vector is added with a default value.

Results:

The last() public member function returns the value of the last element in the vector.

See also:

WCExcept::index_range, WCExcept::empty_container, WCValOrderedVector<Type>::first(), WCValSortedVector<Type>::first(), WCValOrderedVector<Type>::removeLast(), WCValSortedVector<Type>::removeLast()

WCValOrderedVector<Type>::occurrencesOf(), WCValSortedVector<Type>::occurrencesOf()

count the occurrences of an element

Synopsis:

#include <wcvector.h>
public:
int occurrencesOf( const Type & ) const;

Semantics:

The occurrencesOf() public member function returns the number of elements contained in the vector that are equivalent to the passed value.

A linear search is used by the WCValOrderedVector class to find the value; the WCValSortedVector class uses a binary search.

Results:

The occurrencesOf() public member function returns the number of elements equivalent to the passed value.

See also:

WCValOrderedVector<Type>::contains(), WCValSortedVector<Type>::contains(), WCValOrderedVector<Type>::find(), WCValSortedVector<Type>::find(), WCValOrderedVector<Type>::index(), WCValSortedVector<Type>::index(), WCValOrderedVector<Type>::operator [ ](), WCValSortedVector<Type>::operator [ ](), WCValOrderedVector<Type>::removeAll(), WCValSortedVector<Type>::removeAll()

WCValOrderedVector<Type>::operator [ ](), WCValSortedVector<Type>::operator [ ]()

index into the vector

Synopsis:

#include <wcvector.h>
public:
Type & operator [ ]( int );
const Type & operator [ ]( int ) const;

Semantics:

operator [ ]() is the vector index operator. A reference to the object stored in the vector at the given index is returned. If a constant vector is indexed, a reference to a constant element is returned.

The append(), insert(), insertAt() and prepend() member functions are used to insert a new element into a vector, and the remove(), removeAll(), removeAt(), removeFirst() and removeLast() member functions remove elements. The index operator can't be used to change the number of entries in the vector. Searches may be performed using the find() and index() member functions.

If the vector is empty, one of two exceptions can be thrown:

• The empty_container exception is thrown if it's enabled.
• Otherwise, if the index_range exception is enabled, it's thrown.

If neither exception is enabled, a first element of the vector is added with a default value. This element is added so that a reference to a valid vector element can be returned.

If the index value is negative and the index_range exception is enabled, it's thrown. An attempt to index an element with index greater than or equal to the number of entries in the vector will also cause the index_range exception to be thrown if it's enabled. If the exception isn't enabled, attempting to index a negative element indexes the first element in the vector, and attempting to index an element after the last entry indexes the last element.

---

Take care, when using the WCValSortedVector class, not to change the ordering of the vector elements. The result returned by the index operator mustn't be assigned to or modified in such a way that it's no longer equivalent (by Type's equivalence operator) to the value inserted into the vector. Failure to comply may cause lookups to work incorrectly, since the binary search algorithm assumes elements are in sorted order.

---

Results:

The operator [ ]() public member function returns a reference to the element at the given index. If the index is invalid, a reference to the closest valid element is returned. The result of the non-constant index operator may be assigned to.

See also:

WCExcept::empty_container, WCExcept::index_range, WCValOrderedVector<Type>::append(), WCValOrderedVector<Type>::find(), WCValSortedVector<Type>::find(), WCValOrderedVector<Type>::first(), WCValSortedVector<Type>::first(), WCValOrderedVector<Type>::index(), WCValSortedVector<Type>::index(), WCValOrderedVector<Type>::insert(), WCValSortedVector<Type>::insert(), WCValOrderedVector<Type>::insertAt(), WCValOrderedVector<Type>::isEmpty(), WCValSortedVector<Type>::isEmpty(), WCValOrderedVector<Type>::last(), WCValSortedVector<Type>::last(), WCValOrderedVector<Type>::prepend(), WCValOrderedVector<Type>::remove(), WCValSortedVector<Type>::remove(), WCValOrderedVector<Type>::removeAt(), WCValSortedVector<Type>::removeAt(), WCValOrderedVector<Type>::removeAll(), WCValSortedVector<Type>::removeAll(), WCValOrderedVector<Type>::removeFirst(), WCValSortedVector<Type>::removeFirst(), WCValOrderedVector<Type>::removeLast(), WCValSortedVector<Type>::removeLast()

WCValOrderedVector<Type>::operator =(), WCValSortedVector<Type>::operator =()

assign one vector to another

Synopsis:

#include <wcvector.h>
public:
WCValOrderedVector & 
    WCValOrderedVector::operator =(
        const WCValOrderedVector & );
WCValSortedVector & 
    WCValSortedVector::operator =(
        const WCValSortedVector & );

Semantics:

The operator =() public member function is the assignment operator for the class. The left hand side vector is first cleared using the clear() member function, and then the right hand side vector is copied. The left hand side vector is made to have the same length and growth amount as the right hand side (the growth amount is the second argument passed to the right hand side vector constructor). All of the vector elements and exception trap states are copied.

If the left hand side vector can't be fully created, it will have length zero. The out_of_memory exception is thrown if it's enabled in the right hand side vector.

Results:

The operator =() public member function sets the left hand side vector to be a copy of the right hand side.

See also:

WCExcept::out_of_memory, WCValOrderedVector<Type>::clear(), WCValSortedVector<Type>::clear()

WCValOrderedVector<Type>::operator ==(), WCValSortedVector<Type>::operator ==()

determine whether or not two vectors are equivalent

Synopsis:

#include <wcvector.h>
public:
int WCValOrderedVector::operator ==( 
        const WCValOrderedVector & ) const;
int WCValSortedVector::operator ==( 
        const WCValSortedVector & ) const;

Semantics:

The operator ==() public member function is the equivalence operator for the class. Two vector objects are equivalent if they're the same object and share the same address.

Results:

A TRUE (non-zero) value is returned if the left hand side and right hand side vectors are the same object. A FALSE (zero) value is returned otherwise.

WCValOrderedVector<Type>::prepend()

insert an element at the beginning of the vector

Synopsis:

#include <wcvector.h>
public:
int prepend( const Type & );

Semantics:

The prepend() public member function inserts the passed element as the first element in the vector. The data stored in the vector is a copy of the data passed as a parameter. All vector elements contained in the vector are copied (using Type's assignment operator) up one index.

---

This function isn't provided by the WCValSortedVector class, since all elements must be inserted in sorted order by the insert() member function.

---

Several different results can occur if the vector isn't large enough for the new element:

• If the resize_required exception is enabled, it's thrown.
• If the exception isn't enabled, the prepend fails if the amount the vector is to be grown (the second parameter to the constructor) is zero(0).
• Otherwise, the vector is automatically grown by the number of elements specified to the constructor, using the resize() member function. If resize() fails, the element isn't inserted to the vector and the out_of_memory exception is thrown, if enabled.

Results:

The prepend() public member function prepends an element to the WCValOrderedVector object. A TRUE (non-zero) value is returned if the insertion is successful. If the insertion fails, a FALSE (zero) value is returned.

See also:

WCExcept::out_of_memory, WCExcept::resize_required, WCValOrderedVector<Type>::append(), WCValOrderedVector<Type>::insert(), WCValOrderedVector<Type>::insertAt()

WCValOrderedVector<Type>::remove(), WCValSortedVector<Type>::remove()

remove an element from the vector

Synopsis:

#include <wcvector.h>
public:
int remove( const Type & );

Semantics:

The remove() public member function removes the first element in the vector that's equivalent to the passed value. All vector elements stored after the removed elements are copied (using Type's assignment operator) down one index.

A linear search is used by the WCValOrderedVector class to find the element being removed; the WCValSortedVector class uses a binary search.

Results:

The remove() public member function removes the first element in the vector that's equivalent to the passed value. A TRUE (non-zero) value is returned if an equivalent element was contained in the vector and removed. If the vector didn't contain an equivalent value, a FALSE (zero) value is returned.

See also:

WCValOrderedVector<Type>::clear(), WCValSortedVector<Type>::clear(), WCValOrderedVector<Type>::find(), WCValSortedVector<Type>::find(), WCValOrderedVector<Type>::removeAll(), WCValSortedVector<Type>::removeAll(), WCValOrderedVector<Type>::removeAt(), WCValSortedVector<Type>::removeAt(), WCValOrderedVector<Type>::removeFirst(), WCValSortedVector<Type>::removeFirst(), WCValOrderedVector<Type>::removeLast(), WCValSortedVector<Type>::removeLast()

WCValOrderedVector<Type>::removeAll(), WCValSortedVector<Type>::removeAll()

remove all occurrences of an element from the vector

Synopsis:

#include <wcvector.h>
public:
unsigned removeAll( const Type & );

Semantics:

The removeAll() public member function removes all elements in the vector that are equivalent to the passed value. All vector elements stored after the removed elements are copied (using Type's assignment operator) down one or more indexes to take the place of the removed elements.

A linear search is used by the WCValOrderedVector class to find the elements being removed; the WCValSortedVector class uses a binary search.

Results:

The removeAll() public member function removes all elements in the vector that are equivalent to the passed value. The number of elements removed is returned.

See also:

WCValOrderedVector<Type>::clear(), WCValSortedVector<Type>::clear(), WCValOrderedVector<Type>::find(), WCValSortedVector<Type>::find(), WCValOrderedVector<Type>::occurrencesOf(), WCValSortedVector<Type>::occurrencesOf(), WCValOrderedVector<Type>::remove(), WCValSortedVector<Type>::remove(), WCValOrderedVector<Type>::removeAt(), WCValSortedVector<Type>::removeAt(), WCValOrderedVector<Type>::removeFirst(), WCValSortedVector<Type>::removeFirst(), WCValOrderedVector<Type>::removeLast(), WCValSortedVector<Type>::removeLast()

WCValOrderedVector<Type>::removeAt(), WCValSortedVector<Type>::removeAt()

remove the element with the given index from the vector

Synopsis:

#include <wcvector.h>
public:
int removeAt( int );

Semantics:

The removeAt() public member function removes the element at the given index. All vector elements stored after the removed elements are copied (using Type's assignment operator) down one index.

If the vector is empty and the empty_container exception is enabled, it's thrown.

If an attempt is made to remove an element with a negative index and the index_range exception is enabled, it's thrown. If the exception isn't enabled, the first element is removed from the vector. Attempting to remove an element with index greater or equal to the number of entries in the vector also causes the index_range exception to be thrown if enabled. The last element in the vector is removed if the exception isn't enabled.

Results:

The removeAt() public member function removes the element with the given index. If the index is invalid, the closest element to the given index is removed. A TRUE (non-zero) value is returned if an element was removed. If the vector was empty, a FALSE (zero) value is returned.

See also:

WCValOrderedVector<Type>::clear(), WCValSortedVector<Type>::clear(), WCValOrderedVector<Type>::insertAt(), WCValOrderedVector<Type>::operator [ ](), WCValSortedVector<Type>::operator [ ](), WCValOrderedVector<Type>::remove(), WCValSortedVector<Type>::remove(), WCValOrderedVector<Type>::removeAll(), WCValSortedVector<Type>::removeAll(), WCValOrderedVector<Type>::removeFirst(), WCValSortedVector<Type>::removeFirst(), WCValOrderedVector<Type>::removeLast(), WCValSortedVector<Type>::removeLast()

WCValOrderedVector<Type>::removeFirst(), WCValSortedVector<Type>::removeFirst()

remove the first element from the vector

Synopsis:

#include <wcvector.h>
public:
int removeFirst();

Semantics:

The removeFirst() public member function removes the first element from a vector. All other vector elements are copied (using Type's assignment operator) down one index.

If the vector is empty and the empty_container exception is enabled, it's thrown.

Results:

The removeFirst() public member function removes the first element from the vector. A TRUE (non-zero) value is returned if an element was removed. If the vector was empty, FALSE (zero) value is returned.

See also:

WCValOrderedVector<Type>::clear(), WCValSortedVector<Type>::clear(), WCValOrderedVector<Type>::first(), WCValSortedVector<Type>::first(), WCValOrderedVector<Type>::remove(), WCValSortedVector<Type>::remove(), WCValOrderedVector<Type>::removeAt(), WCValSortedVector<Type>::removeAt(), WCValOrderedVector<Type>::removeAll(), WCValSortedVector<Type>::removeAll(), WCValOrderedVector<Type>::removeLast(), WCValSortedVector<Type>::removeLast()

WCValOrderedVector<Type>::removeLast(), WCValSortedVector<Type>::removeLast()

remove the last element from the vector

Synopsis:

#include <wcvector.h>
public:
int removeLast();

Semantics:

The removeLast() public member function removes the last element from a vector. If the vector is empty and the empty_container exception is enabled, it's thrown.

Results:

The removeLast() public member function removes the last element from the vector. A TRUE (non-zero) value is returned if an element was removed. If the vector was empty, a FALSE (zero) value is returned.

See also:

WCValOrderedVector<Type>::clear(), WCValSortedVector<Type>::clear(), WCValOrderedVector<Type>::last(), WCValSortedVector<Type>::last(), WCValOrderedVector<Type>::remove(), WCValSortedVector<Type>::remove(), WCValOrderedVector<Type>::removeAt(), WCValSortedVector<Type>::removeAt(), WCValOrderedVector<Type>::removeAll(), WCValSortedVector<Type>::removeAll(), WCValOrderedVector<Type>::removeFirst(), WCValSortedVector<Type>::removeFirst()

WCValOrderedVector<Type>::resize(), WCValSortedVector<Type>::resize()

change the size of the vector

Synopsis:

#include <wcvector.h>
public:
int resize( size_t new_size );

Semantics:

The resize() public member function is used to change the vector size to be able to store new_size elements:

• If new_size is larger than the previous vector size, all elements are copied (using Type's copy constructor) into the newly sized vector, and new elements can be added using the append(), insert(), insertAt(), and prepend() member functions.
• If the vector is resized to a smaller size, the first new_size elements are copied (all vector elements if the vector contained new_size or fewer elements). The remaining elements are destroyed using Type's destructor.

If the resize can't be performed and the out_of_memory exception is enabled, it's thrown.

Results:

The vector is resized to new_size. A TRUE value (non-zero) is returned if the resize is successful. A FALSE (zero) result is returned if the resize fails.

See also:

WCExcept::out_of_memory

WCValVector<Type> Class

Declared:

wcvector.h

The WCValVector<Type> class is a templated class used to store objects in a vector. Vectors are similar to arrays, but vectors perform bound checking, and can be resized. Elements are inserted into the vector by assigning to a vector index.

The WCValOrderedVector and WCValSortedVector classes are also available. They provide a more abstract view of the vector and additional functionality, including finding and removing elements.

Values are copied into the vector, which could be undesirable if the stored objects are complicated and copying is expensive. Value vectors shouldn't be used to store objects of a base class if any derived types of different sizes would be stored in the vector, or if the destructor for a derived class must be called.

In the description of each member function, the text Type is used to indicate the template parameter defining the type of the elements stored in the vector.

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

Requirements of Type

The WCValVector<Type> class requires Type to have:

• a default constructor

      Type::Type()
      
  

• a well defined copy constructor

      Type::Type( const Type & )
      
  

• the following override of operator new(), only if Type overrides the global operator new()

      void * operator new( size_t, void *ptr ) 
      { return( ptr ); }
      
  

Public Member Functions

The following member functions are declared in the public interface:

WCValVector( size_t = 0 );
WCValVector( size_t, const Type & );
WCValVector( const WCValVector & );
virtual ~WCValVector();
void clear();
size_t length() const;
int resize( size_t );

Public Member Operators

The following member operators are declared in the public interface:

Type & operator [ ]( int );
const Type & operator [ ]( int ) const;
WCValVector & operator =( const WCValVector & );
int operator ==( const WCValVector & ) const;

WCValVector<Type>::WCValVector()

create a WCValVector<Type> object

Synopsis:

#include <wcvector.h>
public:
WCValVector( size_t = 0 );
WCValVector( size_t, const Type & );

Semantics:

There are three forms of the public WCValVector<Type> constructor:

• The first creates a WCValVector<Type> object that's able to store the number of elements specified in the optional parameter, which defaults to zero. All vector elements are initialized with Type's default constructor.

  If the vector object can't be fully initialized, the vector is created with length zero.

• The second form also creates a WCValVector<Type> object that's able to store the number of elements specified by the first parameter. All vector elements are initialized to the value of the second parameter using Type's copy constructor.

  If the vector object can't be fully initialized, the vector is created with length zero.

• The third form is the copy constructor for the WCValVector<Type> class. The new vector is created with the same length as the given vector. All of the vector elements and exception trap states are copied.

  If the new vector can't be fully created, it will have length zero. The out_of_memory exception is thrown if it's enabled in the vector being copied.

Results:

The public WCValVector<Type> constructor creates an initialized WCValVector<Type> object of the specified length.

See also:

WCExcept::out_of_memory, WCValVector<Type>::~WCValVector(), WCValVector<Type>::operator =()

WCValVector<Type>::~WCValVector()

destroy a WCValVector<Type> object

Synopsis:

#include <wcvector.h>
public:
virtual ~WCValVector();

Semantics:

The public WCValVector<Type> destructor is the destructor for the WCValVector<Type> class. If the vector isn't of length zero and the not_empty exception is enabled, it's thrown. Otherwise, the vector elements are cleared using the clear() member function.

The call to this destructor is inserted implicitly by the compiler at the point where the WCValVector<Type> object goes out of scope.

Results:

The WCValVector<Type> object is destroyed.

See also:

WCExcept::not_empty, WCValVector<Type>::clear()

WCValVector<Type>::clear()

clear the vector

Synopsis:

#include <wcvector.h>
public:
void clear();

Semantics:

The clear() public member function is used to clear the vector so that it's of length zero. Elements stored in the vector are destroyed using Type's destructor. The vector object isn't destroyed and re-created by this function, so the object destructor isn't invoked.

Results:

The clear() public member function clears the vector to have length zero and no vector elements.

See also:

WCValVector<Type>::~WCValVector(), WCValVector<Type>::operator =()

WCValVector<Type>::length()

calculate the length of the vector

Synopsis:

#include <wcvector.h>
public:
size_t length() const;

Semantics:

The length() public member function is used to find the number of elements that can be stored in the WCValVector<Type> object.

Results:

The length() public member function returns the length of the vector.

See also:

WCValVector<Type>::resize()

WCValVector<Type>::operator [ ]()

index into the vector

Synopsis:

#include <wcvector.h>
public:
Type & operator [ ]( int );
const Type & operator [ ]( int ) const;

Semantics:

operator [ ]() is the vector index operator. A reference to the object stored in the vector at the given index is returned. If a constant vector is indexed, a reference to a constant element is returned. The index operator of a non-constant vector is the only way to insert an element into the vector.

If an attempt to access an element with index greater than or equal to the length of a non-constant vector is made and the resize_required exception is enabled, it's thrown. If the exception isn't enabled, the vector is automatically resized using the resize() member function to have length the index value plus one. New vector elements are initialized using Type's default constructor.

If the resize failed, and the out_of_memory exception is enabled, it's thrown. If the exception isn't enabled and the resize failed, the last element is indexed (a new element if the vector was length zero). If a negative value is used to index the non-constant vector and the index_range exception is enabled, it's thrown. If the exception isn't enabled and the vector is empty, the resize_required exception may be thrown.

An attempt to index an empty constant vector may cause one of two exceptions to be thrown:

• If the empty_container exception is enabled, it's thrown.
• Otherwise, the index_range exception is thrown, if enabled.

If neither exception is enabled, a first vector element is added and indexed (so that a reference to a valid element can be returned).

Indexing with a negative value or a value greater than or equal to the length of a constant vector causes the index_range exception to be thrown, if enabled.

Results:

The operator [ ]() public member function returns a reference to the element at the given index. If the index is invalid, a reference to the closest valid element is returned. The result of the non-constant index operator may be assigned to.

See also:

WCExcept::empty_container, WCExcept::index_range, WCExcept::out_of_memory, WCExcept::resize_required, WCValVector<Type>::resize()

WCValVector<Type>::operator =()

assign one vector to another

Synopsis:

#include <wcvector.h>
public:
WCValVector & operator =( const WCValVector & );

Semantics:

The operator =() public member function is the assignment operator for the WCValVector<Type> class. The left hand side vector is first cleared using the clear() member function, and then the right hand side vector is copied. The left hand side vector is made to have the same length as the right hand side. All of the vector elements and exception trap states are copied.

If the left hand side vector can't be fully created, it will have a length of zero. The out_of_memory exception is thrown if it's enabled in the right hand side vector.

Results:

The operator =() public member function assigns the left hand side vector to be a copy of the right hand side.

See also:

WCExcept::out_of_memory, WCValVector<Type>::clear()

WCValVector<Type>::operator ==()

determine whether or not two vectors are equivalent

Synopsis:

#include <wcvector.h>
public:
int operator ==( const WCValVector & ) const;

Semantics:

The operator ==() public member function is the equivalence operator for the WCValVector<Type> class. Two vector objects are equivalent if they're the same object and share the same address.

Results:

A TRUE (non-zero) value is returned if the left hand side and right hand side vectors are the same object. A FALSE (zero) value is returned otherwise.

WCValVector<Type>::resize()

resize the vector

Synopsis:

#include <wcvector.h>
public:
int resize( size_t new_size );

Semantics:

The resize() public member function is used to change the vector size to be able to store new_size elements:

• If new_size is larger than the previous vector size, all elements are copied (using Type's copy constructor) into the newly sized vector, and new elements are initialized with Type's default constructor.
• If the vector is resized to a smaller size, the first new_size elements are copied. The remaining elements are destroyed using Type's destructor.

If the resize can't be performed and the out_of_memory exception is enabled, it's thrown.

Results:

The vector is resized to new_size. A TRUE value (non-zero) is returned if the resize is successful. A FALSE (zero) result is returned if the resize fails.

See also:

WCExcept::out_of_memory