rw_slist(3C++)

Name
     rw_slist<T> - Rogue Wave library class

Synopsis
              #include <rw/rwstl/slist.h>
          rw_slist<T> list;




Description
     Class rw_slist<T> maintains a collection of T, implemented as a singly-
     linked list.  Since this is a value based list, objects are copied into
     and out of the links that make up the list.  As with all classes that
     meet the ANSI sequence specification, rw_slist provides for iterators
     that reference its elements.  Operations that alter the contents of
     rw_slist will invalidate iterators that reference items at or after the
     location of change.

Public Typedefs
              typedef T                  value_type;
          typedef T&                 reference;
          typedef const T&           const_reference;
          typedef (unsigned)         size_type; //from Allocator<Node>


     Iterators over rw_slist<T> are forward iterators.

              typedef (scoped Iterator)       iterator;
          typedef (scoped ConstIterator)  const_iterator;



Public Constructors
              rw_slist<T>();


     Construct an empty rw_slist<T>.

              rw_slist<T>(const rw_slist<T>& list);


     Construct an rw_slist<T> which is a copy of list.  Each element from list
     will be copied into self.

              rw_slist<T>(size_type count, const T& value);


     Construct an rw_slist<T> containing exactly count copies of value.

              rw_slist<T>(const_iterator first, const_iterator bound);


     Construct an rw_slist<T> containing a copy of each element referenced by
     the range starting at first and bounded by bound.

              rw_slist<T>(const T* first, const T* bound);


     Construct an rw_slist<T> containing a copy of each element referenced by
     the range starting at first and bounded by bound.

Public Destructor
              ~rw_slist<T>();


     The destructor releases the memory used by the links.

Accessors
              iterator
          begin();


     The iterator returned references the first item in self.  If self is
     empty, the iterator is equal to end().

              const_iterator
          begin() const;


     The iterator returned references the first item in self.  If self is
     empty, the iterator is equal to end().

              iterator
          end();


     The iterator returned marks the location "off the end" of self.  It may
     not be dereferenced.

              const_iterator
          end() const;


     The iterator returned marks the location "off the end" of self.  It may
     not be dereferenced.

              T&
          front();


     References the first item in the list as an L-value.  If self is empty,
     the behavior is undefined.

              const T&
          front();


     References the first item in the list as an R-value.  If self is empty,
     the behavior is undefined.

Const Public Member Functions
              bool
          empty() const;


     Returns true if self is empty.

              size_type
          size() const;


     Returns the number of items currently held in self.

Mutators
              iterator
          erase(iterator iter);


     Removes from self the element referenced by iter.  If iter does not
     reference an actual item contained in self, the effect is undefined.
     Returns an iterator referencing the location just after the erased item.

              iterator
          erase(iterator first, iterator bound);


     Removes from self the elements referenced by the range beginning at first
     and bounded by bound.  Returns an iterator referencing a position just
     after the last erased item.  If first does not reference an item in self
     (and if first and bound are not equal), the effect is undefined.

              iterator
          insert(iterator loc, const T& val);


     Insert val just prior to the place referenced by loc.  Returns an
     iterator referencing the newly inserted element.  (Note:
     ++(list.insert(loc,val))==loc; )

              iterator
          insert(iterator loc, const_iterator first, const_iterator bound);

     Insert a copy of each item in the range beginning at first and bounded by
     bound into self at a place just prior to the place referenced by loc.
     Returns an iterator referencing the last newly inserted element.  (Note:
     ++(list.insert(loc,first,bound))==loc; )

              iterator
          insert(iterator loc, const T* first, const T* bound);


     Insert a copy of each item in the range beginning at first and bounded by
     bound into self at a place just prior to the place referenced by loc.
     Returns an iterator referencing the last newly inserted element.  (Note:
     ++(list.insert(loc,first,bound))==loc; )

              void
          pop_front();


     Erases the first element of self.  If self is empty, the effect is
     undefined.

              void
          push_back(const T& item);


     Inserts item as the last element of the list.

              void
          push_front(const T& item);


     Inserts item as the first element of the list.

              void
          reverse();


     Reverses the order of the nodes containing the elements in self.

              void
          sort();


     Sorts self according to T::operator<(T) or equivalent.  Runs in time
     proportional to N log(N) where N is the number of elements.This is method
     does not copy or destroy any of the items exchanged during the sort, but
     adjusts the order of the links in the list.

              void
          swap(rw_slist<T>& other);

     Exchanges the contents of self with other retaining the ordering of each.
     This is method does not copy or destroy any of the items exchanged, but
     re-links the lists.

              void
          unique();


     Removes from self all but the first element from each equal range.  A
     precondition is that any duplicate elements are adjacent.

Special Methods for Lists
              void
          merge(rw_slist& donor);


     Assuming both donor and self are sorted, moves every item from donor into
     self, leaving donor empty, and self sorted.  If either list is unsorted,
     the move will take place, but the result may not be sorted.  This method
     does not copy or destroy the items in donor, but re-links list nodes into
     self.

              void
          splice(iterator to, rw_slist<T>& donor);


     Insert the entire contents of donor into self, just before the position
     referenced by to,  leaving donor empty.  This method does not copy or
     destroy any of the items moved, but re-links the list nodes from donor
     into self.

              void
          splice(iterator to, rw_slist<T>& donor, iterator from);


     Remove from donor and insert into self, just before location to, the item
     referenced by from.  If from does not reference an actual item contained
     in donor the effect is undefined.  This method does not copy or destroy
     the item referenced by from, but re-links the node containing it from
     donor into self.

              void
          splice(iterator to, rw_slist<T>& donor, iterator from_start,
                 iterator from_bound);


     Remove from donor and insert into self just before location to, the items
     referenced by the range beginning with from_start and bounded by
     from_bound.  If that range does not refer to items contained by donor,
     the effect is undefined.  This method does not copy or destroy the items
     referenced by the range, but re-links those list nodes from donor into

     self.

Related Global Operators
              bool
          operator==(const rw_slist<T>& lhs, const rw_slist<T>& rhs);


     Returns true if lhs and rhs have the same number of elements and each
     element of rhs tests equal (T::operator==() or equivalent) to the
     corresponding element of lhs.

              bool
          operator<(const rw_slist<T>& lhs, const rw_slist<T>& rhs);


     Returns the result of calling

                   lexicographical_compare(lhs.begin(), lhs.end(),
                     rhs.begin(), rhs.end());