26 Numerics library [numerics]

26.7 Numeric arrays [numarray]

26.7.6 The gslice class [class.gslice]

26.7.6.1 Overview [class.gslice.overview]

namespace std {
  class gslice {
  public:
    gslice();
    gslice(size_t s, const valarray<size_t>& l, const valarray<size_t>& d);

    size_t           start() const;
    valarray<size_t> size() const;
    valarray<size_t> stride() const;
  };
}

This class represents a generalized slice out of an array.

A gslice is defined by a starting offset (s), a set of lengths (

l_{j}

), and a set of strides (

d_{j}

The number of lengths shall equal the number of strides.

A gslice represents a mapping from a set of indices (

i_{j}

), equal in number to the number of strides, to a single index k.

It is useful for building multidimensional array classes using the valarray template, which is one-dimensional.

The set of one-dimensional index values specified by a gslice are

k = s + \sum j i_{j} d_{j}

where the multidimensional indices

i_{j}

range in value from 0 to

l_{i j} - 1

[ Example

The gslice specification

start  = 3
length = {2, 4, 3}
stride = {19, 4, 1}

yields the sequence of one-dimensional indices

k = 3 + (0, 1) \times 19 + (0, 1, 2, 3) \times 4 + (0, 1, 2) \times 1

which are ordered as shown in the following table:

	 $(i_{0}, i_{1}, i_{2}, k) =$ 
		 $(0, 0, 0, 3)$ ,    
		 $(0, 0, 1, 4)$ ,    
		 $(0, 0, 2, 5)$ ,    
		 $(0, 1, 0, 7)$ ,    
		 $(0, 1, 1, 8)$ ,    
		 $(0, 1, 2, 9)$ ,    
		 $(0, 2, 0, 11)$ , 
		 $(0, 2, 1, 12)$ , 
		 $(0, 2, 2, 13)$ , 
		 $(0, 3, 0, 15)$ , 
		 $(0, 3, 1, 16)$ , 
		 $(0, 3, 2, 17)$ , 
		 $(1, 0, 0, 22)$ , 
		 $(1, 0, 1, 23)$ , 
		…      
		 $(1, 3, 2, 36)$

That is, the highest-ordered index turns fastest.

— end example

]

It is possible to have degenerate generalized slices in which an address is repeated.

[ Example

If the stride parameters in the previous example are changed to {1, 1, 1}, the first few elements of the resulting sequence of indices will be

	 $(0, 0, 0, 3)$ ,  
	 $(0, 0, 1, 4)$ ,  
	 $(0, 0, 2, 5)$ ,  
	 $(0, 1, 0, 4)$ ,  
	 $(0, 1, 1, 5)$ ,  
	 $(0, 1, 2, 6)$ ,  
	…

— end example

]

If a degenerate slice is used as the argument to the non-const version of operator[](const gslice&), the behavior is undefined.