RWGOrderedVector(3C++)

Name
     RWGOrderedVector(val) - Rogue Wave library class

Synopsis
              #include <rw/gordvec.h>



              declare(RWGVector,val)
          declare(RWGOrderedVector,val)
          implement(RWGVector,val)
          implement(RWGOrderedVector,val)
          RWGOrderedVector(val) v;// Ordered vector of objects of val val.




Description
     Class RWGOrderedVector(val) represents an ordered collection of objects
     of val val.  Objects are ordered by the order of insertion and are
     accessible by index.  Duplicates are allowed.  RWGOrderedVector(val) is
     implemented as a vector, using macros defined in the standard C++ header
     file <generic.h>.  Note that it is a value-based collection: items are
     copied in and out of the collection.  The class val must have:
          a default constructor;

          well-defined copy semantics (val::val(const val&) or equiv.);

          well-defined assignment semantics (val::operator=(const val&) or
          equiv.);

          well-defined equality semantics (val::operator==(const val&) or
          equiv.).

     To use this class you must declare and implement its base class as well
     as the class itself.  For example, here is how you declare and implement
     an ordered collection of doubles:.Ex
         declare(RWGVector,double)                     // Declare base class



              declare(RWGOrderedVector,double)  // Declare ordered vector
          // In one and only one .cpp file you must put the following:
          implement(RWGVector,double)            // Implement base class
          implement(RWGOrderedVector,double)     // Implement ordered vector


     For each val of RWGOrderedVector you must include one (and only one) call
     to the macro implement somewhere in your code for both the

     RWGOrderedVector itself and for its base class RWGVector.

Persistence
     None

Example
     Here's an example that uses an ordered vector of RWCStrings.

              #include <rw/gordvec.h>
          #include <rw/cstring.h>
          #include <rw/rstream.h>
          declare(RWGVector,RWCString)
          declare(RWGOrderedVector,RWCString)
          implement(RWGVector,RWCString)
          implement(RWGOrderedVector,RWCString)
          main()  {
            RWGOrderedVector(RWCString) vec;
            RWCString one("First");
            vec.insert(one);
            vec.insert("Second");   // Automatic val conversion occurs
            vec.insert("Last");     // Automatic val conversion occurs
            for(size_t i=0; i<vec.entries(); i++)  cout << vec[i] << endl;
            return 0;
          }


     Program output:

              First
          Second
          Last

Public Constructors
              RWGOrderedVector(val)(size_t capac=RWDEFAULT_CAPACITY);


     Construct an ordered vector of elements of val val.  The initial capacity
     of the vector will be capac whose default value is RWDEFAULT_CAPACITY.
     The capacity will be automatically increased as necessary should too many
     items be inserted, a relatively expensive process because each item must
     be copied into the new storage.

Public Member Functions
              val
          operator()(size_t i) const;
          val&
          operator()(size_t i);


     Return the ith value in the vector.  The index i must be between 0 and
     one less than the number of items in the vector.  No bounds checking is
     performed.  The second variant can be used as an lvalue, the first
     cannot.

              val
          operator[](size_t i) const;
          val&
          operator[](size_t i);


     Return the ith value in the vector.  The index i must be between 0 and
     one less than the number of items in the vector.  Bounds checking will be
     performed.  The second variant can be used as an lvalue, the first
     cannot.

              void
          clear();


     Remove all items from the collection.

              const val*
          data() const;


     Returns a pointer to the raw data of self.  Should be used with care.

              size_t
          entries() const;


     Return the number of items currently in the collection.

              size_t
          index(val item) const;


     Perform a linear search of the collection returning the index of the
     first item that isEqual to the argument item.  If no item is found, then
     it returns RW_NPOS.

              void
          insert(val item);


     Add the new value item to the end of the collection.

              void
          insertAt(size_t indx, val item);


     Add the new value item to the collection at position indx.  The value of
     indx must be between zero and the length of the collection.  No bounds
     checking is performed.  Old items from index indx upwards will be shifted
     to higher indices.

              RWBoolean
          isEmpty() const;


     Returns TRUE if the collection has no entries.  FALSE otherwise.

              void
          size_t
          length() const;


     Synonym for entries().

              val
          pop();


     Removes and returns the last item in the vector.

              void
          push(val);


     Synonym for insert().

              removeAt(size_t indx);


     Removes the item at position indx from the collection.  The value of indx
     must be between zero and one less than the length of the collection.  No
     bounds checking is performed.  Old items from index indx+1 will be
     shifted to lower indices.  E.g., the item at index indx+1 will be moved
     to position indx, etc.

              void
          resize(size_t newCapacity);


     Change the capacity of the collection to newCapacity, which must be at
     least as large as the present number of items in the collection.  Note
     that the actual number of items in the collection does not change, just
     the capacity.