Click on the banner to return to the Class Reference home page.
Return to the Appendix home page.

©Copyright 1996 Rogue Wave Software

RWTPtrOrderedVector<T>

Alternate template: Standard C++ Library not required

• Synopsis
• Please Note!
• Description
• Persistence
• Example
• Public Constructors
• Public Operators
• Public Member Functions
• Related Global Operators

#include <rw/tpordvec.h>

RWTPtrOrderedVector<T> ordvec;

RWTPtrOrderedVector<T> is a pointer-based ordered collection. That is, the items in the collection have a meaningful ordered relationship with respect to one another and can be accessed by an index number. The order is set by the order of insertion. Duplicates are allowed. The class is implemented as a vector, allowing efficient insertion and retrieval from the end of the collection, but somewhat slower from the beginning of the collection.

The class T must have:

• well-defined equality semantics (T::operator==(const T&)).

Isomorphic

#include <rw/tpordvec.h>
#include <rw/rstream.h>

main() {
  RWTPtrOrderedVector<double> vec;

  vec.insert(new double(22.0));
  vec.insert(new double(5.3));
  vec.insert(new double(-102.5));
  vec.insert(new double(15.0));
  vec.insert(new double(5.3));

  cout << vec.entries() << " entries\n" << endl;  // Prints "5"
  for (int i=0; i<vec.length(); i++)
    cout << *vec[i] << endl;

  vec.clearAndDestroy();
  return 0;
}

Program output:

5 entries
22
5.3
-102.5
15
5.3

Public Constructors
RWTPtrOrderedVector<T>(size_t capac=RWDEFAULT_CAPACITY);

Creates an empty ordered vector with capacity capac.  Should the number of items exceed this value, the vector will be resized automatically.


RWTPtrOrderedVector<T>(const RWTPtrOrderedVector<T>& c);

Constructs a new ordered vector as a shallow copy of c.  After construction, pointers will be shared between the two collections.


Public Operators
RWTPtrOrderedVector<T>&
operator=(const RWTPtrOrderedVector& c);

Sets self to a shallow copy of c.  Afterwards, pointers will be shared between the two collections.


T*&
operator()(size_t i);
T* const&
operator()(size_t i) const;

Returns a pointer to the ith value in the vector.  The first variant can be used as an lvalue, the second cannot.  The index i must be between zero and the number of items in the collection less one.  No bounds checking is performed.


T*&
operator[](size_t i);
T* const&
operator[](size_t i) const;

Returns a pointer to the ith value in the vector.  The first variant can be used as an lvalue, the second cannot.  The index i must be between zero and the number of items in the collection less one, or an exception of type RWBoundsError will be thrown.  


Public Member Functions
void
append(T* a);

Appends the item pointed to by a to the end of the vector.  The collection will automatically be resized if this causes the number of items in the collection to exceed the capacity.


T*&
at(size_t i);
T* const&
at(size_t i) const;

Returns a pointer to the ith value in the vector.  The first variant can be used as an lvalue, the second cannot.  The index i must be between zero and the number of items in the collection less one, or an exception of type RWBoundsError will be thrown.  


void
clear();

Removes all items from the collection.


void
clearAndDestroy();

Removes all items from the collection and deletes them.


RWBoolean
contains(const T* a) const;

Returns TRUE if the collection contains an item that is equal to the object pointed to by a, FALSE otherwise.  A linear search is done.  Equality is measured by the class-defined equality operator for type T.


T* const *
data() const;

Returns a pointer to the raw data of the vector.  The contents should not be changed.  Should be used with care.


size_t
entries() const;

Returns the number of items currently in the collection.


T*
find(const T* target) const;

Returns a pointer to the first object encountered which is equal to the object pointed to by target, or nil if no such object can be found.  Equality is measured by the class-defined equality operator for type T.


T*&
first();
T* const&
first() const;

Returns a pointer to the first item in the vector.  An exception of type RWBoundsError will occur if the vector is empty.


size_t
index(const T* a) const;

Performs a linear search, returning the index of the first object that is equal to the object pointed to by a, or RW_NPOS if there is no such object.  Equality is measured by the class-defined equality operator for type T.


void
insert(T* a);

Adds the object pointed to by a to the end of the vector.  The collection will be resized automatically if this causes the number of items to exceed the capacity.


void
insertAt(size_t i, T* a);

Adds the object pointed to by a at the index position i.  The item previously at position i is moved to i+1, etc.  The collection will be resized automatically if this causes the number of items to exceed the capacity.  The index i must be between 0 and the number of items in the vector or an exception of type RWBoundsError will occur.  


RWBoolean
isEmpty() const;

Returns TRUE if there are no items in the collection, FALSE otherwise.


T*&
last();
T* const&
last() const;

Returns a pointer to the last item in the collection.  If there are no items in the collection then an exception of type RWBoundsError will occur.


size_t
length() const;

Returns the number of items currently in the collection.


size_t
occurrencesOf(const T* a) const;

Performs a linear search, returning the number of objects in the collection that are equal to the object pointed to by a.  Equality is measured by the class-defined equality operator for type T.


void
prepend(T* a);

Adds the item pointed to by a to the beginning of the collection.  The collection will be resized automatically if this causes the number of items to exceed the capacity.


T*
remove(const T* a);

Performs a linear search, removing the first object which is equal to the object pointed to by a and returns a pointer to it, or nil if no such object could be found.  Equality is measured by the class-defined equality operator for type T.


size_t
removeAll(const T* a);

Performs a linear search, removing all objects which are equal to the object pointed to by a.  Returns the number of objects removed.  Equality is measured by the class-defined equality operator for type T.


T*
removeAt(size_t i);

Removes the object at index i and returns a pointer to it.  An exception of type RWBoundsError will be thrown if i is not a valid index.  Valid indices are from zero to the number of items in the list less one.


T*
removeFirst();

Removes the first item in the collection and returns a pointer to it.  An exception of type RWBoundsError will be thrown if the list is empty.


T*
removeLast();

Removes the last item in the collection and returns a pointer to it.  An exception of type RWBoundsError will be thrown if the list is empty.


void
resize(size_t N);

Changes the capacity of the collection to N.  Note that the number of objects in the collection does not change, just the capacity.


Related Global Operators
RWvostream&
operator<<(RWvostream& strm, 
       const RWTPtrOrderedVector<T>& coll);
RWFile&
operator<<(RWFile& strm, const RWTPtrOrderedVector<T>& coll);

Saves the collection coll onto the output stream strm, or a reference to it if it has already been saved.


RWvistream&
operator>>(RWvistream& strm, RWTPtrOrderedVector<T>& coll);
RWFile&
operator>>(RWFile& strm, RWTPtrOrderedVector<T>& coll);

Restores the contents of the collection coll from the input stream strm. 


RWvistream&
operator>>(RWvistream& strm, RWTPtrOrderedVector<T>*& p);
RWFile&
operator>>(RWFile& strm, RWTPtrOrderedVector<T>*& p);

Looks at the next object on the input stream strm and either creates a new collection off the heap and sets p to point to it, or sets p to point to a previously read instance.  If a collection is created off the heap, then you are responsible for deleting it.