Fast 1D accessor/iterator for nD array classes. More...

#include <ArrayAccessor.h>

Inheritance diagram for casa::ArrayAccessor< T, Axis >:

Public Member Functions
	ArrayAccessor ()
	Constructors.
	ArrayAccessor (const Array< T > &arr)
	Construct an accessor from specified Array along the selected axis.
	ArrayAccessor (const ArrayAccessor< T, Axis< U > > &other)
	Construct from an ArrayAccessor along same axis.
template<uInt X>
	ArrayAccessor (const ArrayAccessor< T, Axis< X > > &other)
	Construct from accessor along another (or run-time) axis.
	ArrayAccessor (const ArrayAccessor< T, AxisN > &other)
	~ArrayAccessor ()
	Destructor.
ArrayAccessor &	operator= (const ArrayAccessor< T, Axis< U > > &other)
	Assignment (copy semantics)
template<uInt X>
ArrayAccessor &	operator= (const ArrayAccessor< T, Axis< X > > &other)
	Assign from other compile-time accessor along another axis.
ArrayAccessor &	operator= (const ArrayAccessor< T, AxisN > &other)
	Assign from run-time accessor along any axis.
void	init (const Array< T > &arr)
	(Re-)initialization to start of array (i.e.
void	reset ()
	Reset to start of dimension or to specified pointer.
void	reset (const T *p)
template<class X >
const T &	next () const
	Indexing operations along another axis than the one of the current object.
template<class X >
T &	next ()
template<class X >
const T &	prev () const
	Get the value 'previous' along the specified axis (e.g.
template<class X >
T &	prev ()
const T &	next (const AxisN ax) const
	Get the next or previous along the specified run-time axis.
T &	next (const AxisN ax)
const T &	prev (const AxisN ax) const
T &	prev (const AxisN ax)
template<class X >
const T &	index (const Int ix) const
	Give the value indexed with respect to the current accessor value along the axis specified as either a compile-time or a run-time axis.
template<class X >
T &	index (const Int ix)
const T &	index (const Int ix, const AxisN ax) const
T &	index (const Int ix, const AxisN ax)
Bool	operator== (const ArrayAccessor< T, Axis< U > > &other) const
	Comparison.
Bool	operator!= (const ArrayAccessor< T, Axis< U > > &other) const
Bool	operator== (const T *other) const
Bool	operator!= (const T *other) const
Private Member Functions
Int	initOff (Int x, uInt ax)

void	initStep ()
	Initialize some internal values.

Detailed Description

template<class T, uInt U>
class casa::ArrayAccessor< T, Axis >

Fast 1D accessor/iterator for nD array classes.

Intended use:

Public interface

Review Status

Reviewed By:: Ger van Diepen
Date Reviewed:: 2002/12/01
Test programs:: tArrayAccessor
Demo programs:: dArrayAccessor

Prerequisite

Array indexing and access methods ( Array )

Etymology

Array and access, rather than Iterator, which would suggest more standard-like interfaces

Synopsis

Accessing a large multi-dimensional array by varying the indices of the array can be a slow process. Timing indications are that for a cube indexing with 3 indices was about seven times slower than using a standard 1D C-like index into an array of basic Int types. Improvements have made this less, partly due to some pre-calculation necessary for this class, but can still be a factor of more than 3 slower. There are a variety of ways to access elements cube(i,j,k):

Complete random access in all dimensions will need the use of the indexing: cube(i,j,k); or cube(IPosition(3)) as described in the Array and Cube classes
Ordered access of all (or most) elements in an Array (in memory order) can be best achieved by the use of Array's STLIterator classes. This is the fastest way for non-contiguous arrays, and only slightly slower than the use of getStorage for contiguous arrays.
Ordered access along memory order can also be achieved by the use of the

getStorage() method. For contiguous arrays this could be slightly faster than the use of the STLIterator (about 10% faster), but slower for non-contiguous arrays. In addition it needs additional memory resources, which will lead to extra overhead. The general use of getStorage is discouraged with the introduction of the STLIterator. It should only be used when an interface to routines in other languages is needed (like Fortran), or when a large Array is known to be contiguous, and the data have to be referenced many times.
Access along one or more axes of a (large) multi-dimensional array is best achieved using the ArrayAccessor class. Its total access time is about 2 times faster than indexing (for cubes, more for more indices),
Special iteration (like in chunks) are catered for by the ArrayIterator , MatrixIterator , VectorIterator classes.

The ArrayAccessor class is an iterator like pointer to the data in the array. It is a 1-dimensional accessor. It is created with either a constant (at compile time) axis indicator, or with a run-time axis selector. ArrayAccessor constructor accepts a const Array<>. However, the underlying Array class can be modified at this moment. In future a ConstArrayAccessor class is foreseen.

        Matrix<Double> mat(1000,500); // A 1000*500 matrix
        // Fill Matrix ..\.
        // Loop over index 1, than index 0:
        for (ArrayAccessor<Double, Axis<1> > i(mat); i != i.end(); ++i) {
          for (ArrayAccessor<Double, Axis<0> > j(i); j |= j.end(); ++j) {
            // Actions on *j (which points to mat(j,i)) or j[n]
            // (which points to mat(j+n,i))
        }}

For run-time indices it would look like:

        Matrix<Double> mat(1000,500); // A 1000*500 matrix
        // Fill Matrix ..\.
        // Loop over index 1, than index 0:
        for (ArrayAccessor<Double, AxisN> i(mat, AxisN(1));
              i != i.end(); ++i) {
          for (ArrayAccessor<Double, AxisN> j(i,AxisN(0)); j |= j.end(); ++j) {
            // Actions on *j (which points to mat(j,i)) or j[n]
            // (which points to mat(j+n,i))
        }}

Compile-time and run-time axes can be mixed in constructors and assignments.

Tip: Like in all comparable situations, memory allocation within a loop can slow down processes; For that reason the example above can be better written (about 25% faster) as:

Matrix<Double> mat(1000,500); // A 1000*500 matrix ArrayAccessor<Double, Axis<0> > j; // accessor pre-allocated // Fill Matrix ;;; // Loop over index 1, than index 0: for (ArrayAccessor<Double, Axis<1> > i(mat); i != i;end(); ++i) { for (j=i; j |= j;end(); ++j) { // Actions on *j (which points to mat(j,i)) or j[n] // (which points to mat(j+n,i)) }}

Tip: The underlying Array classes are structured with the first index varying fastest; This means that in general (due to caching and swapping) operations are fastest when Axis<0> > is in the innermost loop (if possible of course);
The demonstrator and test programs have more examples.

The accessors can be dereferenced by the dereference operator (*) and by the index operator ([Int]), which can handle negative values. Points around the accessor in any axis direction can be addressed along any axis by the templated methods next(), prev() and index(Int). Either run-time or compile-time axes can be used (see example).

An accessor can be re-initialized with the init() function. It can also be reset() to any pointer value. Mthods end(), begin(), rbegin() and rend() are available for loop control (like in the STL iterators). In addition each of these can have an optional integer argument, specifying an offset (in points along the current axis).

Operations ++ -- += -= are available.

This class is available for Axis<n> and AxisN specializations only.

Example

        // get a cube and fill it
        Cube<Double> cub(5,2,4);
        indgen(cub);
        // Loop over axes 2-0 and use index() over axis 1
        for (ArrayAccessor<Double, Axis<2> > i(cub); i != i.end() ; ++i) {
          for (ArrayAccessor<Double, Axis<0> > j(i);
            j != j.end(); ++j) {
            // show result
            cout << *j << ", " << j.index<Axis<1> >(1) << endl;
           };
        };

See the demonstrator program in aips/implement/Arrays/test/dArrayAccessor.cc and the test program tArrayAccessor for more examples.

Motivation

To speed up especially interpolation code

Template Type Argument Requirements (T)

Any valid Array templating argument

Template Type Argument Requirements (U)

A class Axis<n>
Class AxisN

Thrown Exceptions

Exceptions created in the Array class
Addressing errors

To Do

add a ConstArrayAccessor class

Definition at line 350 of file ArrayAccessor.h.

Constructor & Destructor Documentation

template<class T , uInt U>

casa::ArrayAccessor< T, Axis >::ArrayAccessor ( ) [inline]

Constructors.

Default ctor. Note only available to accommodate containers of ArrayAccessors. Use init() to initialize.

Definition at line 357 of file ArrayAccessor.h.

template<class T , uInt U>

casa::ArrayAccessor< T, Axis >::ArrayAccessor ( const Array< T > & arr ) [inline, explicit]

Construct an accessor from specified Array along the selected axis.

The accessor will point to the first element along the axis (i.e. at (0,0,...)).

Definition at line 361 of file ArrayAccessor.h.

template<class T , uInt U>

casa::ArrayAccessor< T, Axis >::ArrayAccessor ( const ArrayAccessor< T, Axis > & other ) [inline]

Construct from an ArrayAccessor along same axis.

The accessor will point at the same element as the originator.

Definition at line 365 of file ArrayAccessor.h.

template<class T , uInt U>

template<uInt X>

casa::ArrayAccessor< T, Axis >::ArrayAccessor ( const ArrayAccessor< T, Axis< X > > & other ) [inline, explicit]

Construct from accessor along another (or run-time) axis.

The accessor will point to the same element (but will be oriented along another axis).

Definition at line 372 of file ArrayAccessor.h.

template<class T , uInt U>

casa::ArrayAccessor< T, Axis >::ArrayAccessor ( const ArrayAccessor< T, AxisN > & other ) [inline, explicit]

Definition at line 374 of file ArrayAccessor.h.

template<class T , uInt U>

casa::ArrayAccessor< T, Axis >::~ArrayAccessor ( ) [inline]

Destructor.

Definition at line 379 of file ArrayAccessor.h.

Member Function Documentation

template<class T , uInt U>

template<class X >

const T& casa::ArrayAccessor< T, Axis >::index ( const Int ix ) const [inline]

Give the value indexed with respect to the current accessor value along the axis specified as either a compile-time or a run-time axis.

E.g. a.index<Axis<3> >(5) or a.index(5, AxisN(3)).

Definition at line 450 of file ArrayAccessor.h.

References N.

template<class T , uInt U>

template<class X >

T& casa::ArrayAccessor< T, Axis >::index ( const Int ix ) [inline]

Definition at line 453 of file ArrayAccessor.h.

References N.

template<class T , uInt U>

const T& casa::ArrayAccessor< T, Axis< U > >::index	(	const Int	ix,
		const AxisN	ax
	)		const `[inline]`

Definition at line 455 of file ArrayAccessor.h.

template<class T , uInt U>

T& casa::ArrayAccessor< T, Axis< U > >::index	(	const Int	ix,
		const AxisN	ax
	)		`[inline]`

Definition at line 457 of file ArrayAccessor.h.

template<class T , uInt U>

void casa::ArrayAccessor< T, Axis >::init ( const Array< T > & arr ) [inline]

(Re-)initialization to start of array (i.e.

element (0,0,0,...))

Reimplemented from casa::ArrayBaseAccessor< T >.

Definition at line 401 of file ArrayAccessor.h.

template<class T , uInt U>

Int casa::ArrayAccessor< T, Axis< U > >::initOff	(	Int	x,
		uInt	ax
	)		`[inline, private]`

Get proper offset

Definition at line 475 of file ArrayAccessor.h.

References N.

template<class T , uInt U>

void casa::ArrayAccessor< T, Axis >::initStep ( ) [inline, private]

Initialize some internal values.

Definition at line 479 of file ArrayAccessor.h.

References N.

template<class T , uInt U>

template<class X >

const T& casa::ArrayAccessor< T, Axis >::next ( ) const [inline]

Indexing operations along another axis than the one of the current object.

See for the indexing and iterator operations along the object's axis ArrayBaseAccessor

Get the value 'next' along the specified axis (e.g. with a.next<Axis<2> >())

Definition at line 418 of file ArrayAccessor.h.

References N.

template<class T , uInt U>

template<class X >

T& casa::ArrayAccessor< T, Axis >::next ( ) [inline]

Definition at line 421 of file ArrayAccessor.h.

References N.

template<class T , uInt U>

const T& casa::ArrayAccessor< T, Axis >::next ( const AxisN ax ) const [inline]

Get the next or previous along the specified run-time axis.

E.g. a.prev(AxisN(2)).

Definition at line 435 of file ArrayAccessor.h.

template<class T , uInt U>

T& casa::ArrayAccessor< T, Axis >::next ( const AxisN ax ) [inline]

Definition at line 437 of file ArrayAccessor.h.

template<class T , uInt U>

Bool casa::ArrayAccessor< T, Axis >::operator!= ( const ArrayAccessor< T, Axis > & other ) const [inline]

Definition at line 467 of file ArrayAccessor.h.

template<class T , uInt U>

Bool casa::ArrayAccessor< T, Axis >::operator!= ( const T * other ) const [inline]

Definition at line 470 of file ArrayAccessor.h.

template<class T , uInt U>

ArrayAccessor& casa::ArrayAccessor< T, Axis >::operator= ( const ArrayAccessor< T, Axis > & other ) [inline]

Assignment (copy semantics)

Assign from other compile-time accessor along same axis

Definition at line 385 of file ArrayAccessor.h.

template<class T , uInt U>

template<uInt X>

ArrayAccessor& casa::ArrayAccessor< T, Axis >::operator= ( const ArrayAccessor< T, Axis< X > > & other ) [inline]

Assign from other compile-time accessor along another axis.

Definition at line 392 of file ArrayAccessor.h.

template<class T , uInt U>

ArrayAccessor& casa::ArrayAccessor< T, Axis >::operator= ( const ArrayAccessor< T, AxisN > & other ) [inline]

Assign from run-time accessor along any axis.

Definition at line 396 of file ArrayAccessor.h.

template<class T , uInt U>

Bool casa::ArrayAccessor< T, Axis >::operator== ( const ArrayAccessor< T, Axis > & other ) const [inline]

Comparison.

The comparisons are done for the accessor pointer value. They can be used to control loops.

Definition at line 465 of file ArrayAccessor.h.

template<class T , uInt U>

Bool casa::ArrayAccessor< T, Axis >::operator== ( const T * other ) const [inline]

Definition at line 469 of file ArrayAccessor.h.

template<class T , uInt U>

template<class X >

const T& casa::ArrayAccessor< T, Axis >::prev ( ) const [inline]

Get the value 'previous' along the specified axis (e.g.

with a.prev<Axis<2> >())

Definition at line 427 of file ArrayAccessor.h.

References N.

template<class T , uInt U>

template<class X >

T& casa::ArrayAccessor< T, Axis >::prev ( ) [inline]

Definition at line 430 of file ArrayAccessor.h.

References N.

template<class T , uInt U>

const T& casa::ArrayAccessor< T, Axis >::prev ( const AxisN ax ) const [inline]

Definition at line 439 of file ArrayAccessor.h.

template<class T , uInt U>

T& casa::ArrayAccessor< T, Axis >::prev ( const AxisN ax ) [inline]

Definition at line 441 of file ArrayAccessor.h.

template<class T , uInt U>

void casa::ArrayAccessor< T, Axis >::reset ( ) [inline]

Reset to start of dimension or to specified pointer.

Definition at line 406 of file ArrayAccessor.h.

template<class T , uInt U>

void casa::ArrayAccessor< T, Axis >::reset ( const T * p ) [inline]

Definition at line 407 of file ArrayAccessor.h.

The documentation for this class was generated from the following file:

casacore/casa/Arrays/ArrayAccessor.h

Public Member Functions

Private Member Functions

Detailed Description

template<class T, uInt U> class casa::ArrayAccessor< T, Axis< U > >

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Motivation

Template Type Argument Requirements (T)

Template Type Argument Requirements (U)

Thrown Exceptions

To Do

Constructor & Destructor Documentation

Member Function Documentation

template<class T, uInt U>
class casa::ArrayAccessor< T, Axis< U > >