From: Jerry Quinn Date: Tue, 3 Feb 2004 03:33:24 +0000 (+0000) Subject: gslice.h (gslice): Document. X-Git-Tag: releases/gcc-4.0.0~10441 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=7fb397a4b80067b7b5feda492aa4537d14bbcda7;p=thirdparty%2Fgcc.git gslice.h (gslice): Document. 2004-02-02 Jerry Quinn * 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 --- diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 751858f962bd..778fd062c480 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,14 @@ +2004-02-02 Jerry Quinn + + * 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. + 2004-02-02 Benjamin Kosnik * docs/html/19_diagnostics/howto.html: Move verbose terminate diff --git a/libstdc++-v3/include/bits/gslice.h b/libstdc++-v3/include/bits/gslice.h index c546028703a9..92fd2d2e6387 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&, const valarray&); - // 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&, const valarray&); + + // 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 () const; - valarray stride () const; + /// Return array offset of first slice element. + size_t start() const; + + /// Return array of sizes of slice dimensions. + valarray size() const; + + /// Return array of array strides for each dimension. + valarray stride() const; private: - struct _Indexer { - size_t _M_count; - size_t _M_start; - valarray _M_size; - valarray _M_stride; - valarray _M_index; - _Indexer(size_t, const valarray&, - const valarray&); - 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 _M_size; + valarray _M_stride; + valarray _M_index; + _Indexer(size_t, const valarray&, + const valarray&); + void _M_increment_use() { ++_M_count; } + size_t _M_decrement_use() { return --_M_count; } + }; + + _Indexer* _M_index; - template friend class valarray; + template friend class valarray; }; inline size_t diff --git a/libstdc++-v3/include/bits/gslice_array.h b/libstdc++-v3/include/bits/gslice_array.h index 508eb7c9ab76..f6a0520ffcb1 100644 --- a/libstdc++-v3/include/bits/gslice_array.h +++ b/libstdc++-v3/include/bits/gslice_array.h @@ -41,23 +41,48 @@ namespace std { + /** + * @brief Reference to multi-dimensional subset of an array. + * + * A gslice_array is a reference to the actual elements of an array + * specified by a gslice. The way to get a gslice_array is to call + * operator[](gslice) on a valarray. The returned gslice_array then + * permits carrying operations out on the referenced subset of elements in + * the original valarray. For example, operator+=(valarray) will add + * values to the subset of elements in the underlying valarray this + * gslice_array refers to. + * + * @param Tp Element type. + */ template class gslice_array { public: typedef _Tp value_type; + /// Assign slice elements to corresponding elements of @a v. void operator=(const valarray<_Tp>&) const; + /// Multiply slice elements by corresponding elements of @a v. void operator*=(const valarray<_Tp>&) const; + /// Divide slice elements by corresponding elements of @a v. void operator/=(const valarray<_Tp>&) const; + /// Modulo slice elements by corresponding elements of @a v. void operator%=(const valarray<_Tp>&) const; + /// Add corresponding elements of @a v to slice elements. void operator+=(const valarray<_Tp>&) const; + /// Subtract corresponding elements of @a v from slice elements. void operator-=(const valarray<_Tp>&) const; + /// Logical xor slice elements with corresponding elements of @a v. void operator^=(const valarray<_Tp>&) const; + /// Logical and slice elements with corresponding elements of @a v. void operator&=(const valarray<_Tp>&) const; + /// Logical or slice elements with corresponding elements of @a v. void operator|=(const valarray<_Tp>&) const; + /// Left shift slice elements by corresponding elements of @a v. void operator<<=(const valarray<_Tp>&) const; + /// Right shift slice elements by corresponding elements of @a v. void operator>>=(const valarray<_Tp>&) const; + /// Assign all slice elements to @a t. void operator=(const _Tp&) const; template @@ -92,10 +117,14 @@ namespace std { gslice_array(_Array<_Tp>, const valarray&); // this constructor needs to be implemented. + /// Copy constructor. Both slices refer to the same underlying array. gslice_array(const gslice_array&); // not implemented gslice_array(); + + /// Assignment operator. Assigns slice elements to corresponding + /// elements of @a a. gslice_array& operator= (const gslice_array&); }; diff --git a/libstdc++-v3/include/bits/indirect_array.h b/libstdc++-v3/include/bits/indirect_array.h index cb81aabf77fc..77a7f40464a3 100644 --- a/libstdc++-v3/include/bits/indirect_array.h +++ b/libstdc++-v3/include/bits/indirect_array.h @@ -42,66 +42,96 @@ namespace std { + /** + * @brief Reference to arbitrary subset of an array. + * + * An indirect_array is a reference to the actual elements of an array + * specified by an ordered array of indices. The way to get an indirect_array is to + * call operator[](valarray) on a valarray. The returned + * indirect_array then permits carrying operations out on the referenced + * subset of elements in the original valarray. + * + * For example, if an indirect_array is obtained using the array (4,2,0) as + * an argument, and then assigned to an array containing (1,2,3), then the + * underlying array will have array[0]==3, array[2]==2, and array[4]==1. + * + * @param Tp Element type. + */ template - class indirect_array - { - public: - typedef _Tp value_type; - - // XXX: This is a proposed resolution for DR-253. - indirect_array& operator=(const indirect_array&); + class indirect_array + { + public: + typedef _Tp value_type; + + // XXX: This is a proposed resolution for DR-253. + /// Assignment operator. Assigns elements to corresponding elements + /// of @a a. + indirect_array& operator=(const indirect_array&); - void operator=(const valarray<_Tp>&) const; - void operator*=(const valarray<_Tp>&) const; - void operator/=(const valarray<_Tp>&) const; - void operator%=(const valarray<_Tp>&) const; - void operator+=(const valarray<_Tp>&) const; - void operator-=(const valarray<_Tp>&) const; - void operator^=(const valarray<_Tp>&) const; - void operator&=(const valarray<_Tp>&) const; - void operator|=(const valarray<_Tp>&) const; - void operator<<=(const valarray<_Tp>&) const; - void operator>>=(const valarray<_Tp>&) const; - void operator= (const _Tp&) const; - // ~indirect_array(); + /// Assign slice elements to corresponding elements of @a v. + void operator=(const valarray<_Tp>&) const; + /// Multiply slice elements by corresponding elements of @a v. + void operator*=(const valarray<_Tp>&) const; + /// Divide slice elements by corresponding elements of @a v. + void operator/=(const valarray<_Tp>&) const; + /// Modulo slice elements by corresponding elements of @a v. + void operator%=(const valarray<_Tp>&) const; + /// Add corresponding elements of @a v to slice elements. + void operator+=(const valarray<_Tp>&) const; + /// Subtract corresponding elements of @a v from slice elements. + void operator-=(const valarray<_Tp>&) const; + /// Logical xor slice elements with corresponding elements of @a v. + void operator^=(const valarray<_Tp>&) const; + /// Logical and slice elements with corresponding elements of @a v. + void operator&=(const valarray<_Tp>&) const; + /// Logical or slice elements with corresponding elements of @a v. + void operator|=(const valarray<_Tp>&) const; + /// Left shift slice elements by corresponding elements of @a v. + void operator<<=(const valarray<_Tp>&) const; + /// Right shift slice elements by corresponding elements of @a v. + void operator>>=(const valarray<_Tp>&) const; + /// Assign all slice elements to @a t. + void operator= (const _Tp&) const; + // ~indirect_array(); - template - void operator=(const _Expr<_Dom, _Tp>&) const; - template - void operator*=(const _Expr<_Dom, _Tp>&) const; - template - void operator/=(const _Expr<_Dom, _Tp>&) const; - template - void operator%=(const _Expr<_Dom, _Tp>&) const; - template - void operator+=(const _Expr<_Dom, _Tp>&) const; - template - void operator-=(const _Expr<_Dom, _Tp>&) const; - template - void operator^=(const _Expr<_Dom, _Tp>&) const; - template - void operator&=(const _Expr<_Dom, _Tp>&) const; - template - void operator|=(const _Expr<_Dom, _Tp>&) const; - template - void operator<<=(const _Expr<_Dom, _Tp>&) const; - template - void operator>>=(const _Expr<_Dom, _Tp>&) const; - - private: - indirect_array(const indirect_array&); - indirect_array(_Array<_Tp>, size_t, _Array); - - friend class valarray<_Tp>; - friend class gslice_array<_Tp>; + template + void operator=(const _Expr<_Dom, _Tp>&) const; + template + void operator*=(const _Expr<_Dom, _Tp>&) const; + template + void operator/=(const _Expr<_Dom, _Tp>&) const; + template + void operator%=(const _Expr<_Dom, _Tp>&) const; + template + void operator+=(const _Expr<_Dom, _Tp>&) const; + template + void operator-=(const _Expr<_Dom, _Tp>&) const; + template + void operator^=(const _Expr<_Dom, _Tp>&) const; + template + void operator&=(const _Expr<_Dom, _Tp>&) const; + template + void operator|=(const _Expr<_Dom, _Tp>&) const; + template + void operator<<=(const _Expr<_Dom, _Tp>&) const; + template + void operator>>=(const _Expr<_Dom, _Tp>&) const; + + private: + /// Copy constructor. Both slices refer to the same underlying array. + indirect_array(const indirect_array&); + indirect_array(_Array<_Tp>, size_t, _Array); + + friend class valarray<_Tp>; + friend class gslice_array<_Tp>; - const size_t _M_sz; - const _Array _M_index; - const _Array<_Tp> _M_array; + const size_t _M_sz; + const _Array _M_index; + const _Array<_Tp> _M_array; - // not implemented - indirect_array(); - }; + // not implemented + indirect_array(); + }; template inline diff --git a/libstdc++-v3/include/bits/mask_array.h b/libstdc++-v3/include/bits/mask_array.h index ba67db70e9bf..a5d13d7162de 100644 --- a/libstdc++-v3/include/bits/mask_array.h +++ b/libstdc++-v3/include/bits/mask_array.h @@ -42,6 +42,21 @@ namespace std { + /** + * @brief Reference to selected subset of an array. + * + * A mask_array is a reference to the actual elements of an array specified + * by a bitmask in the form of an array of bool. The way to get a + * mask_array is to call operator[](valarray) on a valarray. The + * returned mask_array then permits carrying operations out on the + * referenced subset of elements in the original valarray. + * + * For example, if a mask_array is obtained using the array (false, true, + * false, true) as an argument, the mask array has two elements referring + * to array[1] and array[3] in the underlying array. + * + * @param Tp Element type. + */ template class mask_array { @@ -49,16 +64,27 @@ namespace std { typedef _Tp value_type; void operator=(const valarray<_Tp>&) const; + /// Multiply slice elements by corresponding elements of @a v. void operator*=(const valarray<_Tp>&) const; + /// Divide slice elements by corresponding elements of @a v. void operator/=(const valarray<_Tp>&) const; - void operator%=(const valarray<_Tp>&) const; - void operator+=(const valarray<_Tp>&) const; - void operator-=(const valarray<_Tp>&) const; - void operator^=(const valarray<_Tp>&) const; + /// Modulo slice elements by corresponding elements of @a v. + void operator%=(const valarray<_Tp>&) const; + /// Add corresponding elements of @a v to slice elements. + void operator+=(const valarray<_Tp>&) const; + /// Subtract corresponding elements of @a v from slice elements. + void operator-=(const valarray<_Tp>&) const; + /// Logical xor slice elements with corresponding elements of @a v. + void operator^=(const valarray<_Tp>&) const; + /// Logical and slice elements with corresponding elements of @a v. void operator&=(const valarray<_Tp>&) const; + /// Logical or slice elements with corresponding elements of @a v. void operator|=(const valarray<_Tp>&) const; - void operator<<=(const valarray<_Tp>&) const; + /// Left shift slice elements by corresponding elements of @a v. + void operator<<=(const valarray<_Tp>&) const; + /// Right shift slice elements by corresponding elements of @a v. void operator>>=(const valarray<_Tp>&) const; + /// Assign all slice elements to @a t. void operator=(const _Tp&) const; // ~mask_array (); @@ -94,10 +120,14 @@ namespace std { const _Array _M_mask; const _Array<_Tp> _M_array; + /// Copy constructor. Both slices refer to the same underlying array. mask_array (const mask_array&); // not implemented mask_array(); + + /// Assignment operator. Assigns elements to corresponding elements + /// of @a a. mask_array& operator=(const mask_array&); }; diff --git a/libstdc++-v3/include/bits/slice_array.h b/libstdc++-v3/include/bits/slice_array.h index ad33a474672d..fb4a810cc37c 100644 --- a/libstdc++-v3/include/bits/slice_array.h +++ b/libstdc++-v3/include/bits/slice_array.h @@ -41,14 +41,39 @@ namespace std { + /** + * @brief Class defining one-dimensional subset of an array. + * + * The slice class represents a one-dimensional subset of an array, + * specified by three parameters: start offset, size, and stride. The + * start offset is the index of the first element of the array that is part + * of the subset. The size is the total number of elements in the subset. + * Stride is the distance between each successive array element to include + * in the subset. + * + * For example, with an array of size 10, and a slice with offset 1, size 3 + * and stride 2, the subset consists of array elements 1, 3, and 5. + */ class slice { public: + /// Construct an empty slice. slice(); + + /** + * @brief Construct a slice. + * + * @param o Offset in array of first element. + * @param d Number of elements in slice. + * @param s Stride between array elements. + */ slice(size_t, size_t, size_t); + /// Return array offset of first slice element. size_t start() const; + /// Return size of slice. size_t size() const; + /// Return array stride of slice. size_t stride() const; private: @@ -78,6 +103,19 @@ namespace std slice::stride() const { return _M_st; } + /** + * @brief Reference to one-dimensional subset of an array. + * + * A slice_array is a reference to the actual elements of an array + * specified by a slice. The way to get a slice_array is to call + * operator[](slice) on a valarray. The returned slice_array then permits + * carrying operations out on the referenced subset of elements in the + * original valarray. For example, operator+=(valarray) will add values + * to the subset of elements in the underlying valarray this slice_array + * refers to. + * + * @param Tp Element type. + */ template class slice_array { @@ -85,22 +123,37 @@ namespace std typedef _Tp value_type; // This constructor is implemented since we need to return a value. + /// Copy constructor. Both slices refer to the same underlying array. slice_array(const slice_array&); // This operator must be public. See DR-253. + /// Assignment operator. Assigns slice elements to corresponding + /// elements of @a a. slice_array& operator=(const slice_array&); + /// Assign slice elements to corresponding elements of @a v. void operator=(const valarray<_Tp>&) const; + /// Multiply slice elements by corresponding elements of @a v. void operator*=(const valarray<_Tp>&) const; + /// Divide slice elements by corresponding elements of @a v. void operator/=(const valarray<_Tp>&) const; + /// Modulo slice elements by corresponding elements of @a v. void operator%=(const valarray<_Tp>&) const; + /// Add corresponding elements of @a v to slice elements. void operator+=(const valarray<_Tp>&) const; + /// Subtract corresponding elements of @a v from slice elements. void operator-=(const valarray<_Tp>&) const; + /// Logical xor slice elements with corresponding elements of @a v. void operator^=(const valarray<_Tp>&) const; + /// Logical and slice elements with corresponding elements of @a v. void operator&=(const valarray<_Tp>&) const; + /// Logical or slice elements with corresponding elements of @a v. void operator|=(const valarray<_Tp>&) const; + /// Left shift slice elements by corresponding elements of @a v. void operator<<=(const valarray<_Tp>&) const; + /// Right shift slice elements by corresponding elements of @a v. void operator>>=(const valarray<_Tp>&) const; + /// Assign all slice elements to @a t. void operator=(const _Tp &) const; // ~slice_array (); diff --git a/libstdc++-v3/include/bits/stl_numeric.h b/libstdc++-v3/include/bits/stl_numeric.h index 7b901a543150..d4eb358a7d47 100644 --- a/libstdc++-v3/include/bits/stl_numeric.h +++ b/libstdc++-v3/include/bits/stl_numeric.h @@ -66,6 +66,17 @@ namespace std { + /** + * @brief Accumulate values in a range. + * + * Accumulates the values in the range [first,last) using operator+(). The + * initial value is @a init. The values are processed in order. + * + * @param first Start of range. + * @param last End of range. + * @param init Starting value to add other values to. + * @return The final sum. + */ template _Tp accumulate(_InputIterator __first, _InputIterator __last, _Tp __init) @@ -79,6 +90,19 @@ namespace std return __init; } + /** + * @brief Accumulate values in a range with operation. + * + * Accumulates the values in the range [first,last) using the function + * object @a binary_op. The initial value is @a init. The values are + * processed in order. + * + * @param first Start of range. + * @param last End of range. + * @param init Starting value to add other values to. + * @param binary_op Function object to accumulate with. + * @return The final sum. + */ template _Tp accumulate(_InputIterator __first, _InputIterator __last, _Tp __init, @@ -93,6 +117,20 @@ namespace std return __init; } + /** + * @brief Compute inner product of two ranges. + * + * Starting with an initial value of @a init, multiplies successive + * elements from the two ranges and adds each product into the accumulated + * value using operator+(). The values in the ranges are processed in + * order. + * + * @param first1 Start of range 1. + * @param last1 End of range 1. + * @param first2 Start of range 2. + * @param init Starting value to add other values to. + * @return The final inner product. + */ template _Tp inner_product(_InputIterator1 __first1, _InputIterator1 __last1, @@ -108,6 +146,22 @@ namespace std return __init; } + /** + * @brief Compute inner product of two ranges. + * + * Starting with an initial value of @a init, applies @a binary_op2 to + * successive elements from the two ranges and accumulates each result into + * the accumulated value using @a binary_op1. The values in the ranges are + * processed in order. + * + * @param first1 Start of range 1. + * @param last1 End of range 1. + * @param first2 Start of range 2. + * @param init Starting value to add other values to. + * @param binary_op1 Function object to accumulate with. + * @param binary_op2 Function object to apply to pairs of input values. + * @return The final inner product. + */ template _Tp @@ -126,6 +180,20 @@ namespace std return __init; } + /** + * @brief Return list of partial sums + * + * Accumulates the values in the range [first,last) using operator+(). + * As each successive input value is added into the total, that partial sum + * is written to @a result. Therefore, the first value in result is the + * first value of the input, the second value in result is the sum of the + * first and second input values, and so on. + * + * @param first Start of input range. + * @param last End of input range. + * @param result Output to write sums to. + * @return Iterator pointing just beyond the values written to result. + */ template _OutputIterator partial_sum(_InputIterator __first, _InputIterator __last, @@ -148,6 +216,20 @@ namespace std return ++__result; } + /** + * @brief Return list of partial sums + * + * Accumulates the values in the range [first,last) using operator+(). + * As each successive input value is added into the total, that partial sum + * is written to @a result. Therefore, the first value in result is the + * first value of the input, the second value in result is the sum of the + * first and second input values, and so on. + * + * @param first Start of input range. + * @param last End of input range. + * @param result Output to write sums to. + * @return Iterator pointing just beyond the values written to result. + */ template _OutputIterator partial_sum(_InputIterator __first, _InputIterator __last, @@ -170,6 +252,17 @@ namespace std return ++__result; } + /** + * @brief Return differences between adjacent values. + * + * Computes the difference between adjacent values in the range + * [first,last) using operator-() and writes the result to @a result. + * + * @param first Start of input range. + * @param last End of input range. + * @param result Output to write sums to. + * @return Iterator pointing just beyond the values written to result. + */ template _OutputIterator adjacent_difference(_InputIterator __first, @@ -193,6 +286,18 @@ namespace std return ++__result; } + /** + * @brief Return differences between adjacent values. + * + * Computes the difference between adjacent values in the range + * [first,last) using the function object @a binary_op and writes the + * result to @a result. + * + * @param first Start of input range. + * @param last End of input range. + * @param result Output to write sums to. + * @return Iterator pointing just beyond the values written to result. + */ template _OutputIterator adjacent_difference(_InputIterator __first, _InputIterator __last, diff --git a/libstdc++-v3/include/std/std_valarray.h b/libstdc++-v3/include/std/std_valarray.h index 7dac89dadb01..9cec1d34ccfd 100644 --- a/libstdc++-v3/include/std/std_valarray.h +++ b/libstdc++-v3/include/std/std_valarray.h @@ -95,6 +95,17 @@ namespace std namespace std { + /** + * @brief Smart array designed to support numeric processing. + * + * A valarray is an array that provides constraints intended to allow for + * effective optimization of numeric array processing by reducing the + * aliasing that can result from pointer representations. It represents a + * one-dimensional array from which different multidimensional subsets can + * be accessed and modified. + * + * @param Tp Type of object in the array. + */ template class valarray { @@ -108,25 +119,95 @@ namespace std typedef _Tp value_type; // _lib.valarray.cons_ construct/destroy: + /// Construct an empty array. valarray(); + + /// Construct an array with @a n elements. explicit valarray(size_t); + + /// Construct an array with @a n elements initialized to @a t. valarray(const _Tp&, size_t); + + /// Construct an array initialized to the first @a n elements of @a t. valarray(const _Tp* __restrict__, size_t); + + /// Copy constructor. valarray(const valarray&); + + /// Construct an array with the same size and values in @a sa. valarray(const slice_array<_Tp>&); + + /// Construct an array with the same size and values in @a ga. valarray(const gslice_array<_Tp>&); + + /// Construct an array with the same size and values in @a ma. valarray(const mask_array<_Tp>&); + + /// Construct an array with the same size and values in @a ia. valarray(const indirect_array<_Tp>&); + template valarray(const _Expr<_Dom,_Tp>& __e); ~valarray(); // _lib.valarray.assign_ assignment: + /** + * @brief Assign elements to an array. + * + * Assign elements of array to values in @a v. Results are undefined + * if @a v is not the same size as this array. + * + * @param v Valarray to get values from. + */ valarray<_Tp>& operator=(const valarray<_Tp>&); + + /** + * @brief Assign elements to a value. + * + * Assign all elements of array to @a t. + * + * @param t Value for elements. + */ valarray<_Tp>& operator=(const _Tp&); + + /** + * @brief Assign elements to an array subset. + * + * Assign elements of array to values in @a sa. Results are undefined + * if @a sa is not the same size as this array. + * + * @param sa Array slice to get values from. + */ valarray<_Tp>& operator=(const slice_array<_Tp>&); + + /** + * @brief Assign elements to an array subset. + * + * Assign elements of array to values in @a ga. Results are undefined + * if @a ga is not the same size as this array. + * + * @param ga Array slice to get values from. + */ valarray<_Tp>& operator=(const gslice_array<_Tp>&); + + /** + * @brief Assign elements to an array subset. + * + * Assign elements of array to values in @a ma. Results are undefined + * if @a ma is not the same size as this array. + * + * @param ma Array slice to get values from. + */ valarray<_Tp>& operator=(const mask_array<_Tp>&); + + /** + * @brief Assign elements to an array subset. + * + * Assign elements of array to values in @a ia. Results are undefined + * if @a ia is not the same size as this array. + * + * @param ia Array slice to get values from. + */ valarray<_Tp>& operator=(const indirect_array<_Tp>&); template valarray<_Tp>& @@ -134,45 +215,196 @@ namespace std // _lib.valarray.access_ element access: // XXX: LWG to be resolved. + /** + * Return a reference to the i'th array element. + * + * The C++ spec defines the const version to return Tp instead of + * the more useful const Tp&. This issue is being reviewed in DR389. + * + * @param i Index of element to return. + * @return Reference to the i'th element. + */ const _Tp& operator[](size_t) const; + + /// Return a reference to the i'th array element. _Tp& operator[](size_t); + // _lib.valarray.sub_ subset operations: + /** + * @brief Return an array subset. + * + * Returns a new valarray containing the elements of the array + * indicated by the slice argument. The new valarray is the size of + * the input slice. @see slice. + * + * @param s The source slice. + * @return New valarray containing elements in @a s. + */ _Expr<_SClos<_ValArray,_Tp>, _Tp> operator[](slice) const; + + /** + * @brief Return a reference to an array subset. + * + * Returns a new valarray containing the elements of the array + * indicated by the slice argument. The new valarray is the size of + * the input slice. @see slice. + * + * @param s The source slice. + * @return New valarray containing elements in @a s. + */ slice_array<_Tp> operator[](slice); + + /** + * @brief Return an array subset. + * + * Returns a slice_array referencing the elements of the array + * indicated by the slice argument. @see gslice. + * + * @param s The source slice. + * @return Slice_array referencing elements indicated by @a s. + */ _Expr<_GClos<_ValArray,_Tp>, _Tp> operator[](const gslice&) const; + + /** + * @brief Return a reference to an array subset. + * + * Returns a new valarray containing the elements of the array + * indicated by the gslice argument. The new valarray is + * the size of the input gslice. @see gslice. + * + * @param s The source gslice. + * @return New valarray containing elements in @a s. + */ gslice_array<_Tp> operator[](const gslice&); + + /** + * @brief Return an array subset. + * + * Returns a new valarray containing the elements of the array + * indicated by the argument. The input is a valarray of bool which + * represents a bitmask indicating which elements should be copied into + * the new valarray. Each element of the array is added to the return + * valarray if the corresponding element of the argument is true. + * + * @param m The valarray bitmask. + * @return New valarray containing elements indicated by @a m. + */ valarray<_Tp> operator[](const valarray&) const; + + /** + * @brief Return a reference to an array subset. + * + * Returns a new mask_array referencing the elements of the array + * indicated by the argument. The input is a valarray of bool which + * represents a bitmask indicating which elements are part of the + * subset. Elements of the array are part of the subset if the + * corresponding element of the argument is true. + * + * @param m The valarray bitmask. + * @return New valarray containing elements indicated by @a m. + */ mask_array<_Tp> operator[](const valarray&); + + /** + * @brief Return an array subset. + * + * Returns a new valarray containing the elements of the array + * indicated by the argument. The elements in the argument are + * interpreted as the indices of elements of this valarray to copy to + * the return valarray. + * + * @param i The valarray element index list. + * @return New valarray containing elements in @a s. + */ _Expr<_IClos<_ValArray, _Tp>, _Tp> operator[](const valarray&) const; + + /** + * @brief Return a reference to an array subset. + * + * Returns an indirect_array referencing the elements of the array + * indicated by the argument. The elements in the argument are + * interpreted as the indices of elements of this valarray to include + * in the subset. The returned indirect_array refers to these + * elements. + * + * @param i The valarray element index list. + * @return Indirect_array referencing elements in @a i. + */ indirect_array<_Tp> operator[](const valarray&); // _lib.valarray.unary_ unary operators: + /// Return a new valarray by applying unary + to each element. typename _UnaryOp<__unary_plus>::_Rt operator+() const; + + /// Return a new valarray by applying unary - to each element. typename _UnaryOp<__negate>::_Rt operator-() const; + + /// Return a new valarray by applying unary ~ to each element. typename _UnaryOp<__bitwise_not>::_Rt operator~() const; + + /// Return a new valarray by applying unary ! to each element. typename _UnaryOp<__logical_not>::_Rt operator!() const; // _lib.valarray.cassign_ computed assignment: + /// Multiply each element of array by @a t. valarray<_Tp>& operator*=(const _Tp&); + + /// Divide each element of array by @a t. valarray<_Tp>& operator/=(const _Tp&); + + /// Set each element e of array to e % @a t. valarray<_Tp>& operator%=(const _Tp&); + + /// Add @a t to each element of array. valarray<_Tp>& operator+=(const _Tp&); + + /// Subtract @a t to each element of array. valarray<_Tp>& operator-=(const _Tp&); + + /// Set each element e of array to e ^ @a t. valarray<_Tp>& operator^=(const _Tp&); + + /// Set each element e of array to e & @a t. valarray<_Tp>& operator&=(const _Tp&); + + /// Set each element e of array to e | @a t. valarray<_Tp>& operator|=(const _Tp&); + + /// Left shift each element e of array by @a t bits. valarray<_Tp>& operator<<=(const _Tp&); + + /// Right shift each element e of array by @a t bits. valarray<_Tp>& operator>>=(const _Tp&); + + /// Multiply elements of array by corresponding elements of @a v. valarray<_Tp>& operator*=(const valarray<_Tp>&); + + /// Divide elements of array by corresponding elements of @a v. valarray<_Tp>& operator/=(const valarray<_Tp>&); + + /// Modulo elements of array by corresponding elements of @a v. valarray<_Tp>& operator%=(const valarray<_Tp>&); + + /// Add corresponding elements of @a v to elements of array. valarray<_Tp>& operator+=(const valarray<_Tp>&); + + /// Subtract corresponding elements of @a v from elements of array. valarray<_Tp>& operator-=(const valarray<_Tp>&); + + /// Logical xor corresponding elements of @a v with elements of array. valarray<_Tp>& operator^=(const valarray<_Tp>&); + + /// Logical or corresponding elements of @a v with elements of array. valarray<_Tp>& operator|=(const valarray<_Tp>&); + + /// Logical and corresponding elements of @a v with elements of array. valarray<_Tp>& operator&=(const valarray<_Tp>&); + + /// Left shift elements of array by corresponding elements of @a v. valarray<_Tp>& operator<<=(const valarray<_Tp>&); + + /// Right shift elements of array by corresponding elements of @a v. valarray<_Tp>& operator>>=(const valarray<_Tp>&); template @@ -198,18 +430,93 @@ namespace std // _lib.valarray.members_ member functions: + /// Return the number of elements in array. size_t size() const; - _Tp sum() const; + + /** + * @brief Return the sum of all elements in the array. + * + * Accumulates the sum of all elements into a Tp using +=. The order + * of adding the elements is unspecified. + */ + _Tp sum() const; + + /// Return the minimum element using operator<(). _Tp min() const; + + /// Return the maximum element using operator<(). _Tp max() const; // // FIXME: Extension // _Tp product () const; + /** + * @brief Return a shifted array. + * + * A new valarray is constructed as a copy of this array with elements + * in shifted positions. For an element with index i, the new position + * is i - n. The new valarray is the same size as the current one. + * New elements without a value are set to 0. Elements whos new + * position is outside the bounds of the array are discarded. + * + * Positive arguments shift toward index 0, discarding elements [0, n). + * Negative arguments discard elements from the top of the array. + * + * @param n Number of element positions to shift. + * @return New valarray with elements in shifted positions. + */ valarray<_Tp> shift (int) const; + + /** + * @brief Return a rotated array. + * + * A new valarray is constructed as a copy of this array with elements + * in shifted positions. For an element with index i, the new position + * is (i - n) % size(). The new valarray is the same size as the + * current one. Elements that are shifted beyond the array bounds are + * shifted into the other end of the array. No elements are lost. + * + * Positive arguments shift toward index 0, wrapping around the top. + * Negative arguments shift towards the top, wrapping around to 0. + * + * @param n Number of element positions to rotate. + * @return New valarray with elements in shifted positions. + */ valarray<_Tp> cshift(int) const; + + /** + * @brief Apply a function to the array. + * + * Returns a new valarray with elements assigned to the result of + * applying func to the corresponding element of this array. The new + * array is the same size as this one. + * + * @param func Function of Tp returning Tp to apply. + * @return New valarray with transformed elements. + */ _Expr<_ValFunClos<_ValArray,_Tp>,_Tp> apply(_Tp func(_Tp)) const; + + /** + * @brief Apply a function to the array. + * + * Returns a new valarray with elements assigned to the result of + * applying func to the corresponding element of this array. The new + * array is the same size as this one. + * + * @param func Function of const Tp& returning Tp to apply. + * @return New valarray with transformed elements. + */ _Expr<_RefFunClos<_ValArray,_Tp>,_Tp> apply(_Tp func(const _Tp&)) const; + + /** + * @brief Resize array. + * + * Resize this array to be @a size and set all elements to @a c. All + * references and iterators are invalidated. + * + * @param size New array size. + * @param c New value for all elements. + */ void resize(size_t __size, _Tp __c = _Tp()); private: