gslice.h (gslice): Document.

2004-02-02  Jerry Quinn  <jlquinn@optonline.net>

	* include/bits/gslice.h (gslice):  Document.
	* include/bits/gslice_array.h (gslice_array):  Document.
	* include/bits/indirect_array (indirect_array):  Document.
	* include/bits/mask_array (mask_array):  Document.
	* include/bits/slice_array.h (slice,slice_array):  Document.
	* include/bits/stl_numeric.h (accumulate, inner_product, partial_sum,
	adjacent_difference):  Document
	* include/std/std_valarray.h (valarray):  Document.

From-SVN: r77153

1 files changed, 67 insertions, 27 deletions

diff --git a/libstdc++-v3/include/bits/gslice.h b/libstdc++-v3/include/bits/gslice.h
index c546028..92fd2d2 100644
--- a/libstdc++-v3/include/bits/gslice.h
+++ b/libstdc++-v3/include/bits/gslice.h
@@ -41,40 +41,80 @@
 
 namespace std {
     
+  /**
+   *  @brief  Class defining multi-dimensional subset of an array.
+   *
+   *  The slice class represents a multi-dimensional subset of an array,
+   *  specified by three parameter sets: start offset, size array, and stride
+   *  array.  The start offset is the index of the first element of the array
+   *  that is part of the subset.  The size and stride array describe each
+   *  dimension of the slice.  Size is the number of elements in that
+   *  dimension, and stride is the distance in the array between successive
+   *  elements in that dimension.  Each dimension's size and stride is taken
+   *  to begin at an array element described by the previous dimension.  The
+   *  size array and stride array must be the same size.
+   *
+   *  For example, if you have offset==3, stride[0]==11, size[1]==3,
+   *  stride[1]==3, then slice[0,0]==array[3], slice[0,1]==array[6],
+   *  slice[0,2]==array[9], slice[1,0]==array[14], slice[1,1]==array[17],
+   *  slice[1,2]==array[20].
+   */
     class gslice
     {
     public:
-        gslice ();
-        gslice (size_t, const valarray<size_t>&, const valarray<size_t>&);
-        // XXX: the IS says the copy-ctor and copy-assignment operators are
-        //      synthetized by the compiler but they are just unsuitable
-        //      for a ref-counted semantic
-        gslice(const gslice&);
-        ~gslice();
-
-        // XXX: See the note above.
-        gslice& operator= (const gslice&);
+      ///  Construct an empty slice.
+      gslice ();
+
+      /**
+       *  @brief  Construct a slice.
+       *
+       *  Constructs a slice with as many dimensions as the length of the @a l
+       *  and @a s arrays.
+       *
+       *  @param  o  Offset in array of first element.
+       *  @param  l  Array of dimension lengths.
+       *  @param  s  Array of dimension strides between array elements.
+       */
+      gslice(size_t, const valarray<size_t>&, const valarray<size_t>&);
+
+      // XXX: the IS says the copy-ctor and copy-assignment operators are
+      //      synthetized by the compiler but they are just unsuitable
+      //      for a ref-counted semantic
+      ///  Copy constructor.
+      gslice(const gslice&);
+
+      ///  Destructor.
+      ~gslice();
+
+      // XXX: See the note above.
+      ///  Assignment operator.
+      gslice& operator=(const gslice&);
         
-        size_t           start () const;
-        valarray<size_t> size () const;
-        valarray<size_t> stride () const;
+      ///  Return array offset of first slice element.
+      size_t           start() const;
+
+      ///  Return array of sizes of slice dimensions.
+      valarray<size_t> size() const;
+
+      ///  Return array of array strides for each dimension.
+      valarray<size_t> stride() const;
         
     private:
-        struct _Indexer {
-            size_t _M_count;
-            size_t _M_start;
-            valarray<size_t> _M_size;
-            valarray<size_t> _M_stride;
-            valarray<size_t> _M_index;
-            _Indexer(size_t, const valarray<size_t>&,
-                     const valarray<size_t>&);
-            void _M_increment_use() { ++_M_count; }
-            size_t _M_decrement_use() { return --_M_count; }
-        };
-
-        _Indexer* _M_index;
+      struct _Indexer {
+	size_t _M_count;
+	size_t _M_start;
+	valarray<size_t> _M_size;
+	valarray<size_t> _M_stride;
+	valarray<size_t> _M_index;
+	_Indexer(size_t, const valarray<size_t>&,
+		 const valarray<size_t>&);
+	void _M_increment_use() { ++_M_count; }
+	size_t _M_decrement_use() { return --_M_count; }
+      };
+
+      _Indexer* _M_index;
         
-        template<typename _Tp> friend class valarray;
+      template<typename _Tp> friend class valarray;
     };
     
     inline size_t