casa::ArrayAccessor< T, Axis< U > > Class Template Reference
[Arrays]

#include <ArrayAccessor.h>

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

[legend]Collaboration diagram for casa::ArrayAccessor< T, Axis< U > >:

[legend]List of all members.

---

Detailed Description

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

Fast 1D accessor/iterator for nD array classes.

Intended use:

Part of API

Review Status

Reviewed By:

diepen@astron.nl<dt>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 351 of file ArrayAccessor.h.

Public Member Functions
	~ArrayAccessor ()
	Destructor.
void	init (const Array< T > &arr)
	(Re-)initialization to start of array (i.e.
	ArrayAccessor ()
	Default ctor.
	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 &	operator= (const ArrayAccessor< T, Axis< U > > &other)
	Assign from other compile-time accessor along same axis.
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	reset ()
	Reset to start of dimension or to specified pointer.
void	reset (const T *p)
template<class X>
const T &	next () const
	Get the value 'next' along the specified axis (e.g.
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)
	Get proper offset.
void	initStep ()
	Initialize some internal values.

---

Constructor & Destructor Documentation

template<class T, uInt U>

casa::ArrayAccessor< T, Axis< U > >::ArrayAccessor

(

)

[inline]

Default ctor.

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

Definition at line 358 of file ArrayAccessor.h.

template<class T, uInt U>

casa::ArrayAccessor< T, Axis< U > >::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 362 of file ArrayAccessor.h.

template<class T, uInt U>

casa::ArrayAccessor< T, Axis< U > >::ArrayAccessor

(

const ArrayAccessor< T, Axis< U > > &

other

)

[inline]

Construct from an ArrayAccessor along same axis.

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

Definition at line 366 of file ArrayAccessor.h.

template<class T, uInt U>

template<uInt X>

casa::ArrayAccessor< T, Axis< U > >::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 373 of file ArrayAccessor.h.

template<class T, uInt U>

casa::ArrayAccessor< T, Axis< U > >::ArrayAccessor

(

const ArrayAccessor< T, AxisN > &

other

)

[inline, explicit]

Definition at line 375 of file ArrayAccessor.h.

template<class T, uInt U>

casa::ArrayAccessor< T, Axis< U > >::~ArrayAccessor

(

)

[inline]

Destructor.

Definition at line 380 of file ArrayAccessor.h.

---

Member Function Documentation

template<class T, uInt U>

ArrayAccessor& casa::ArrayAccessor< T, Axis< U > >::operator=

(

const ArrayAccessor< T, Axis< U > > &

other

)

[inline]

Assign from other compile-time accessor along same axis.

Definition at line 386 of file ArrayAccessor.h.

template<class T, uInt U>

template<uInt X>

ArrayAccessor& casa::ArrayAccessor< T, Axis< U > >::operator=

(

const ArrayAccessor< T, Axis< X > > &

other

)

[inline]

Assign from other compile-time accessor along another axis.

Definition at line 393 of file ArrayAccessor.h.

template<class T, uInt U>

ArrayAccessor& casa::ArrayAccessor< T, Axis< U > >::operator=

(

const ArrayAccessor< T, AxisN > &

other

)

[inline]

Assign from run-time accessor along any axis.

Definition at line 397 of file ArrayAccessor.h.

template<class T, uInt U>

void casa::ArrayAccessor< T, Axis< U > >::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 402 of file ArrayAccessor.h.

template<class T, uInt U>

void casa::ArrayAccessor< T, Axis< U > >::reset

(

)

[inline]

Reset to start of dimension or to specified pointer.

Definition at line 407 of file ArrayAccessor.h.

template<class T, uInt U>

void casa::ArrayAccessor< T, Axis< U > >::reset

(

const T *

p

)

[inline]

Definition at line 408 of file ArrayAccessor.h.

template<class T, uInt U>

template<class X>

const T& casa::ArrayAccessor< T, Axis< U > >::next

(

)

const [inline]

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

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

Definition at line 419 of file ArrayAccessor.h.

References N.

template<class T, uInt U>

template<class X>

T& casa::ArrayAccessor< T, Axis< U > >::next

(

)

[inline]

Definition at line 422 of file ArrayAccessor.h.

References N.

template<class T, uInt U>

template<class X>

const T& casa::ArrayAccessor< T, Axis< U > >::prev

(

)

const [inline]

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

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

Definition at line 428 of file ArrayAccessor.h.

References N.

template<class T, uInt U>

template<class X>

T& casa::ArrayAccessor< T, Axis< U > >::prev

(

)

[inline]

Definition at line 431 of file ArrayAccessor.h.

References N.

template<class T, uInt U>

const T& casa::ArrayAccessor< T, Axis< U > >::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 436 of file ArrayAccessor.h.

template<class T, uInt U>

T& casa::ArrayAccessor< T, Axis< U > >::next

(

const AxisN

ax

)

[inline]

Definition at line 438 of file ArrayAccessor.h.

template<class T, uInt U>

const T& casa::ArrayAccessor< T, Axis< U > >::prev

(

const AxisN

ax

)

const [inline]

Definition at line 440 of file ArrayAccessor.h.

template<class T, uInt U>

T& casa::ArrayAccessor< T, Axis< U > >::prev

(

const AxisN

ax

)

[inline]

Definition at line 442 of file ArrayAccessor.h.

template<class T, uInt U>

template<class X>

const T& casa::ArrayAccessor< T, Axis< U > >::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 451 of file ArrayAccessor.h.

References N.

template<class T, uInt U>

template<class X>

T& casa::ArrayAccessor< T, Axis< U > >::index

(

const Int

ix

)

[inline]

Definition at line 454 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 456 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 458 of file ArrayAccessor.h.

template<class T, uInt U>

Bool casa::ArrayAccessor< T, Axis< U > >::operator==

(

const ArrayAccessor< T, Axis< U > > &

other

)

const [inline]

Comparison.

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

Definition at line 466 of file ArrayAccessor.h.

template<class T, uInt U>

Bool casa::ArrayAccessor< T, Axis< U > >::operator!=

(

const ArrayAccessor< T, Axis< U > > &

other

)

const [inline]

Definition at line 468 of file ArrayAccessor.h.

template<class T, uInt U>

Bool casa::ArrayAccessor< T, Axis< U > >::operator==

(

const T *

other

)

const [inline]

Definition at line 470 of file ArrayAccessor.h.

template<class T, uInt U>

Bool casa::ArrayAccessor< T, Axis< U > >::operator!=

(

const T *

other

)

const [inline]

Definition at line 471 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 476 of file ArrayAccessor.h.

References N.

template<class T, uInt U>

void casa::ArrayAccessor< T, Axis< U > >::initStep

(

)

[inline, private]

Initialize some internal values.

Definition at line 480 of file ArrayAccessor.h.

References N.

---

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

• casa/implement/Arrays/ArrayAccessor.h

---