Scopira 20080306

Numeric arrays

The scopira::basekit::narray template class is the core numerical data array class in Scopira. It can be used to make arrays of any dimention and with any data type.

Some notes

Data access for multi-dimention arrays follow the x,y,z,etc style. In particular, matrices are x,y (rather than the mathematical convention of rows,cols). This is deliberate as to be consistant with higher dimention array.

STL-like begin()/end() iteration is supported.

You can always get at the raw data in an narray using the scopira::basekit::narray::c_array() method.

Use [] for 1-dimention (vector) access. Use () for 2-dimention (matrix) access. () is also used for 3+-dimention access via nindex objects.

When compiled in debug mode, all element access is tested via asserts(). This aids in debugging and development. Under release builds, these check is removed and all accesses are inlined -- just like native arrays.

Basic Example

This is an example of some basic usage of narrays.

  #include <scopira/tool/output.h>
  #include <scopira/basekit/narray.h>
  int main(void)
  {
    scopira::basekit::narray<double,2> M;     // this is a matrix of doubles
    scopira::basekit::narray<int,1> V;        // this is a vector of ints
    scopira::basekit::narray<float> F;        // this is a vector of floats (1 is the default when no dimention is sepecified)

    // resize the arrays
    M.resize(5, 4);
    V.resize(10);

    // set some initial values
    M.set_all(1.2);
    V.set_all(555);

    // so some data access
    // note that [] can ONLY be used in 1-dimentional vectors
    // () can be used for all dimentions
    M(0,0) = 22;                                // set top left corner of the matrix
    M(4, 3); = 33;                              // set bottom right corner of the matrix
    V[1] = 55;                                  // set the 2nd element in the vector

    OUTPUT << M.width() << "x" << M.height() << "; " << V.size() << '\n';
    OUTPUT << M << V << '\n';
  }

Slices

scopira::basekit::nslice is a template class that provides "slicing" for narrays. A slice is a small pointer into a subsection of a host-narray. A nslice has no data of it's own, it only knows where in the host narray it should be accessing. It is invalid to use a nslice after its hsot narray has been destroyed (or even simply resized).

A nslice has most of the same methods and access functions as an narray.

A nslice can have less dimentions that its host narray (but never more). For example, you can make a vector-like nslice out of a 2-dimention matrix narray.

An example:

  {
    scopira::basekit::narray<double,2> M;
    scopira::basekit::nslice<double,2> subM;
    scopira::basekit::nslice<double,1> subV;

    // initialize M
    M.resize(10, 5);
    M.set_all(99);

    // print out the top left elements (3 by 3 square)
    subM = M.xyslice(0, 0, 3, 3);
    OUTPUT << subM << '\n';

    // print out the 2nd column
    subV = M.yslice(1, 0, M.height());
    OUTPUT << subV << '\n';
  }