Apache C++ Standard Library Reference Guide

## gslice

Library: Numerics

    Does not inherit

- Local Index
- Summary
- Synopsis
- Description
- Interface
- Constructors
- Accessors
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

gslice() | size() | start() | stride()

### Summary

A numeric array class used to represent a generalized slice from an array

### Synopsis

    #include <valarray>

    namespace std {
     class gslice;
    }

### Description

gslice represents a generalized slice from an array. A generalized slice contains a starting index, a set of lengths, and a set of strides. The number of lengths and strides must be equal. Together the lengths and strides allow a slice from a multiple dimension array (with the dimension equal to the number of strides) to be represented on a one-dimensional valarray. The gslice maps a set of `n` indices `(ij)`, where `n` is equal to the number of strides, to a single index `k`.

When applied to a valarray using the gslice subscript operator (see valarray), a gslice produces a gslice_array. The gslice_array class creates a view into the original valarray that is tailored to match parameters of the gslice. The elements in a gslice_array are references to the elements in the original array.

### Interface

    namespace std{

      class gslice {
      public:
        // constructors
        gslice();
        gslice(size_t, const valarray<size_t>&,
               const valarray<size_t>&);
        gslice(const gslice&);

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

### Constructors

    gslice();

Default constructor creates a gslice specifying no elements.

    gslice(size_t start, const valarray<size_t>& length,
           const valarray<size_t>& stride);

Creates a gslice with starting index, length, and stride as indicated by the arguments.

    gslice(const gslice&)

Creates a gslice with starting index, length, and stride as indicated by the slice argument.

### Accessors

    size_t start() const;

Returns the starting index of the gslice.

    valarray<size_t> size() const;

Returns a `valarray<size_t>` containing the lengths of the gslice.

    valarray<size_t> stride() const;

Returns a `valarray<size_t>` containing the strides of the gslice.

### Example

    //
    //  gslice.cpp
    //

    #include <valarray.h>  // Includes valarray and provides
                           // stream inserter.

    typedef std::valarray<int>    valarray_t;
    typedef std::valarray<size_t> selector_t;

    int main(void) {

      // Create a valarray of ints.
      valarray_t::value_type ibuf[27] =
                      { 0,  1,  2,  3,  4,  5,  6,  7,  8,
                        9, 10, 11, 12, 13, 14, 15, 16, 17,
                       18, 19, 20, 21, 22, 23, 24, 25, 26 };
      valarray_t  vi(ibuf, 27);

      // Create length and stride valarray
      selector_t::value_type length_buf[3] = {3,3,3};
      selector_t::value_type stride_buf[3] = {9,3,1};
      selector_t length_val(length_buf, 3);
      selector_t stride_val(stride_buf, 3);

      // Print out the valarray<int>.
      std::cout << "original valarray vi\n\n" << vi << "\n\n";

      // Print out all three dimensions (the entire valarray).
      std::cout << "vi[gslice(0,{3,3,3},{9,3,1})]\n\n"
                << vi[std::gslice(0,length_val,stride_val)]
                << "\n\n";

      // Print a two dimensional slice out of the middle.
      selector_t::value_type length_buf2[] = {3, 3};
      selector_t::value_type stride_buf2[] = {3, 1};
      selector_t             length_val2(length_buf2, 2);
      selector_t             stride_val2(stride_buf2, 2);

      std::cout << "vi[gslice(9,{3,3},{3,1})]\n\n"
                << vi[std::gslice(9,length_val2,stride_val2)]
                << "\n\n";

      // Print another two dimensional slice out of the middle but
      // orthogonal to one we just did.
      stride_val2[0] = 9;
      stride_val2[1] = 1;

      std::cout << "vi[gslice(3,{3,3},{9,1})]\n\n"
                << vi[std::gslice(3,length_val2,stride_val2)]
                << "\n\n";

      // Print out the last plane in the middle -- orthogonal to
      // both of the previous ones.
      stride_val2[0] = 3;
      stride_val2[1] = 9;

      std::cout << "vi[gslice(1,{3,3},{3,9})]\n\n"
                << vi[std::gslice(1,length_val2,stride_val2)]
                << "\n\n";

      // Now how about a diagonal slice, upper left front to lower right
      // back.
      stride_val2[0] = 3;
      stride_val2[1] = 10;

      std::cout << "vi[gslice(0,{3,3},{3,10})]\n\n"
                << vi[std::gslice(0,length_val2,stride_val2)]
                << "\n\n";

      return 0;
    }

    Program Output:
    original valarray vi

    [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,
    23,24,25,26]

    vi[gslice(0,{3,3,3},{9,3,1})]

    [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,
    23,24,25,26]

    vi[gslice(9,{3,3},{3,1})]

    [9,10,11,12,13,14,15,16,17]

    vi[gslice(3,{3,3},{9,1})]

    [3,4,5,12,13,14,21,22,23]

    vi[gslice(1,{3,3},{3,9})]

    [1,10,19,4,13,22,7,16,25]

    vi[gslice(0,{3,3},{3,10})]

    [0,10,20,3,13,23,6,16,26]

### See Also

valarray, slice_array, slice, gslice_array, mask_array, indirect_array

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 26.3.6