[v3] List docs

[Jerry Quinn]

[only sent to libstdc++ before]

2003-07-13  Jerry Quinn  <jlquinn@optonline.net>

        *  include/bits/stl_list.h:  Document more functions.

*** stl_list.h.~1.28.~	Wed Jul  9 10:09:21 2003
--- stl_list.h	Sun Jul 13 17:07:48 2003
***************
*** 863,869 ****
    
      // [23.2.2.4] list operations
      /**
!      *  @doctodo
      */
      void
      splice(iterator __position, list& __x)
--- 863,874 ----
    
      // [23.2.2.4] list operations
      /**
!      *  @brief  Insert contents of another %list.
!      *  @param  position  Iterator referencing the element to insert before.
!      *  @param  x  Source list.
!      *
!      *  The elements of x are inserted in constant time in front of the
!      *  element referenced by position.  x becomes an empty list.
      */
      void
      splice(iterator __position, list& __x)
***************
*** 873,879 ****
      }
    
      /**
!      *  @doctodo
      */
      void
      splice(iterator __position, list&, iterator __i)
--- 878,890 ----
      }
    
      /**
!      *  @brief  Insert element from another %list.
!      *  @param  position  Iterator referencing the element to insert before.
!      *  @param  x  Source list.
!      *  @param  i  Iterator referencing the element to move.
!      *
!      *  Removes the element in list x referenced by i and inserts it into the
!      *  current list before position.
      */
      void
      splice(iterator __position, list&, iterator __i)
***************
*** 885,892 ****
      }
    
      /**
!      *  @doctodo
!     */
      void
      splice(iterator __position, list&, iterator __first, iterator __last)
      {
--- 896,912 ----
      }
    
      /**
!      *  @brief  Insert range from another %list.
!      *  @param  position  Iterator referencing the element to insert before.
!      *  @param  x  Source list.
!      *  @param  first  Iterator referencing the start of range in x.
!      *  @param  last  Iterator referencing the end of range in x.
!      *
!      *  Removes elements in the range [first,last) and inserts them before
!      *  position in constant time.
!      *
!      *  Undefined if position is in [first,last).
!    */
      void
      splice(iterator __position, list&, iterator __first, iterator __last)
      {
***************
*** 895,952 ****
      }
    
      /**
!      *  @doctodo
      */
      void
      remove(const _Tp& __value);
    
      /**
!      *  @doctodo
      */
      template<typename _Predicate>
        void
        remove_if(_Predicate);
    
      /**
!      *  @doctodo
      */
      void
      unique();
    
      /**
!      *  @doctodo
      */
      template<typename _BinaryPredicate>
        void
        unique(_BinaryPredicate);
    
      /**
!      *  @doctodo
      */
      void
      merge(list& __x);
    
      /**
!      *  @doctodo
      */
      template<typename _StrictWeakOrdering>
        void
        merge(list&, _StrictWeakOrdering);
    
      /**
!      *  @doctodo
      */
      void
      reverse() { __List_base_reverse(&this->_M_node); }
    
      /**
!      *  @doctodo
      */
      void
      sort();
    
      /**
!      *  @doctodo
      */
      template<typename _StrictWeakOrdering>
        void
--- 915,1021 ----
      }
    
      /**
!      *  @brief  Remove all elements equal to value.
!      *  @param  value  The value to remove.
!      *
!      *  Removes every element in the list equal to value.  Remaining elements
!      *  stay in list order.  Note that this function only erases the elements,
!      *  and that if the elements themselves are pointers, the pointed-to
!      *  memory is not touched in any way.  Managing the pointer is the user's
!      *  responsibilty.
      */
      void
      remove(const _Tp& __value);
    
      /**
!      *  @brief  Remove all elements satisfying a predicate.
!      *  @param  Predicate  Unary predicate function or object.
!      *
!      *  Removes every element in the list for which the predicate returns
!      *  true.  Remaining elements stay in list order.  Note that this function
!      *  only erases the elements, and that if the elements themselves are
!      *  pointers, the pointed-to memory is not touched in any way.  Managing
!      *  the pointer is the user's responsibilty.
      */
      template<typename _Predicate>
        void
        remove_if(_Predicate);
    
      /**
!      *  @brief  Remove consecutive duplicate elements.
!      *
!      *  For each consecutive set of elements with the same value, remove all
!      *  but the first one.  Remaining elements stay in list order.  Note that
!      *  this function only erases the elements, and that if the elements
!      *  themselves are pointers, the pointed-to memory is not touched in any
!      *  way.  Managing the pointer is the user's responsibilty.
      */
      void
      unique();
    
      /**
!      *  @brief  Remove consecutive elements satisfying a predicate.
!      *  @param  BinaryPredicate  Binary predicate function or object.
!      *
!      *  For each consecutive set of elements [first,last) that satisfy
!      *  predicate(first,i) where i is an iterator in [first,last), remove all
!      *  but the first one.  Remaining elements stay in list order.  Note that
!      *  this function only erases the elements, and that if the elements
!      *  themselves are pointers, the pointed-to memory is not touched in any
!      *  way.  Managing the pointer is the user's responsibilty.
      */
      template<typename _BinaryPredicate>
        void
        unique(_BinaryPredicate);
    
      /**
!      *  @brief  Merge sorted lists.
!      *  @param  x  Sorted list to merge.
!      *
!      *  Assumes that both x and this list are sorted according to
!      *  operator<().  Merges elements of x into this list in sorted order,
!      *  leaving x empty when complete.  Elements in this list precede elements
!      *  in x that are equal.
      */
      void
      merge(list& __x);
    
      /**
!      *  @brief  Merge sorted lists according to comparison function.
!      *  @param  x  Sorted list to merge.
!      *  @param  StrictWeakOrdering  Comparison function definining sort order.
!      *
!      *  Assumes that both x and this list are sorted according to
!      *  StrictWeakOrdering.  Merges elements of x into this list in sorted
!      *  order, leaving x empty when complete.  Elements in this list precede
!      *  elements in x that are equivalent according to StrictWeakOrdering().
      */
      template<typename _StrictWeakOrdering>
        void
        merge(list&, _StrictWeakOrdering);
    
      /**
!      *  @brief  Reverse the elements in list.
!      *
!      *  Reverse the order of elements in the list in linear time.
      */
      void
      reverse() { __List_base_reverse(&this->_M_node); }
    
      /**
!      *  @brief  Sort the elements.
!      *
!      *  Sorts the elements of this list in NlogN time.  Equivalent elements
!      *  remain in list order.
      */
      void
      sort();
    
      /**
!      *  @brief  Sort the elements according to comparison function.
!      *
!      *  Sorts the elements of this list in NlogN time.  Equivalent elements
!      *  remain in list order.
      */
      template<typename _StrictWeakOrdering>
        void