#include <container_classes.h>

Collaboration diagram for multi_arr< T, d, ALLOC, lgBC >:

Public Types
typedef random_access_iterator_tag	iterator_category

typedef T	value_type

typedef T &	reference

typedef const T &	const_reference

typedef T *	pointer

typedef const T *	const_pointer

typedef size_t	size_type

typedef ptrdiff_t	difference_type

typedef pntr< T, lgBC >	iterator

typedef const_pntr< T, lgBC >	const_iterator

typedef n_pointer< T, d-1, ALLOC, lgBC >	indexed_type

typedef const_n_pointer< T, d-1, ALLOC, lgBC >	const_indexed_type

Public Member Functions
	multi_arr ()

	multi_arr (const multi_geom< d, ALLOC > &g)

	multi_arr (size_type d1, size_type d2)

	multi_arr (size_type d1, size_type d2, size_type d3)

	multi_arr (size_type d1, size_type d2, size_type d3, size_type d4)

	multi_arr (size_type d1, size_type d2, size_type d3, size_type d4, size_type d5)

	multi_arr (size_type d1, size_type d2, size_type d3, size_type d4, size_type d5, size_type d6)

	multi_arr (const multi_arr &m)

	~multi_arr ()

void	clear ()

const multi_arr &	operator= (const multi_arr &m)

const multi_arr &	operator= (const T &val)

void	zero ()

void	invalidate ()

void	reserve (size_type i1)

void	reserve (size_type i1, size_type i2)

void	reserve (size_type i1, size_type i2, size_type i3)

void	reserve (size_type i1, size_type i2, size_type i3, size_type i4)

void	reserve (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5)

void	reserve (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5, size_type i6)

void	alloc ()

void	alloc (const multi_geom< d, ALLOC > &g)

void	alloc (size_type d1, size_type d2)

void	alloc (size_type d1, size_type d2, size_type d3)

void	alloc (size_type d1, size_type d2, size_type d3, size_type d4)

void	alloc (size_type d1, size_type d2, size_type d3, size_type d4, size_type d5)

void	alloc (size_type d1, size_type d2, size_type d3, size_type d4, size_type d5, size_type d6)

void	alloc (size_type index[])

const n_pointer< T, d, ALLOC, lgBC >	n_ptr ()

const const_n_pointer< T, d, ALLOC, lgBC >	n_ptr () const

const indexed_type	operator[] (size_type i)

const const_indexed_type	operator[] (size_type i) const

reference	at (size_type i1, size_type i2)

const_reference	at (size_type i1, size_type i2) const

reference	at (size_type i1, size_type i2, size_type i3)

const_reference	at (size_type i1, size_type i2, size_type i3) const

reference	at (size_type i1, size_type i2, size_type i3, size_type i4)

const_reference	at (size_type i1, size_type i2, size_type i3, size_type i4) const

reference	at (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5)

const_reference	at (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5) const

reference	at (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5, size_type i6)

const_reference	at (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5, size_type i6) const

iterator	ptr (size_type i1, size_type i2)

const_iterator	ptr (size_type i1, size_type i2) const

iterator	ptr (size_type i1, size_type i2, size_type i3)

const_iterator	ptr (size_type i1, size_type i2, size_type i3) const

iterator	ptr (size_type i1, size_type i2, size_type i3, size_type i4)

const_iterator	ptr (size_type i1, size_type i2, size_type i3, size_type i4) const

iterator	ptr (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5)

const_iterator	ptr (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5) const

iterator	ptr (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5, size_type i6)

const_iterator	ptr (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5, size_type i6) const

iterator	begin (size_type i1)

const_iterator	begin (size_type i1) const

iterator	begin (size_type i1, size_type i2)

const_iterator	begin (size_type i1, size_type i2) const

iterator	begin (size_type i1, size_type i2, size_type i3)

const_iterator	begin (size_type i1, size_type i2, size_type i3) const

iterator	begin (size_type i1, size_type i2, size_type i3, size_type i4)

const_iterator	begin (size_type i1, size_type i2, size_type i3, size_type i4) const

iterator	begin (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5)

const_iterator	begin (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5) const

iterator	end (size_type i1)

const_iterator	end (size_type i1) const

iterator	end (size_type i1, size_type i2)

const_iterator	end (size_type i1, size_type i2) const

iterator	end (size_type i1, size_type i2, size_type i3)

const_iterator	end (size_type i1, size_type i2, size_type i3) const

iterator	end (size_type i1, size_type i2, size_type i3, size_type i4)

const_iterator	end (size_type i1, size_type i2, size_type i3, size_type i4) const

iterator	end (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5)

const_iterator	end (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5) const

reference	front (size_type i1)

const_reference	front (size_type i1) const

reference	front (size_type i1, size_type i2)

const_reference	front (size_type i1, size_type i2) const

reference	front (size_type i1, size_type i2, size_type i3)

const_reference	front (size_type i1, size_type i2, size_type i3) const

reference	front (size_type i1, size_type i2, size_type i3, size_type i4)

const_reference	front (size_type i1, size_type i2, size_type i3, size_type i4) const

reference	front (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5)

const_reference	front (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5) const

reference	back (size_type i1)

const_reference	back (size_type i1) const

reference	back (size_type i1, size_type i2)

const_reference	back (size_type i1, size_type i2) const

reference	back (size_type i1, size_type i2, size_type i3)

const_reference	back (size_type i1, size_type i2, size_type i3) const

reference	back (size_type i1, size_type i2, size_type i3, size_type i4)

const_reference	back (size_type i1, size_type i2, size_type i3, size_type i4) const

reference	back (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5)

const_reference	back (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5) const

size_type	size () const

size_type	capacity () const

bool	empty () const

pointer	data ()

const_pointer	data () const

const multi_geom< d, ALLOC > &	clone () const

valarray< T > &	vals ()

const valarray< T > &	vals () const

Private Member Functions
void	p_clear0 ()

void	p_clear1 ()

void	p_setupArray (size_type n1[], size_type n2[], const tree_vec *g, size_type l)

iterator	p_iterator (size_type i1, size_type i2) const

iterator	p_iterator_bc (size_type i1, size_type i2) const

iterator	p_iterator (size_type i1, size_type i2, size_type i3) const

iterator	p_iterator_bc (size_type i1, size_type i2, size_type i3) const

iterator	p_iterator (size_type i1, size_type i2, size_type i3, size_type i4) const

iterator	p_iterator_bc (size_type i1, size_type i2, size_type i3, size_type i4) const

iterator	p_iterator (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5) const

iterator	p_iterator_bc (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5) const

iterator	p_iterator (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5, size_type i6) const

iterator	p_iterator_bc (size_type i1, size_type i2, size_type i3, size_type i4, size_type i5, size_type i6) const

Private Attributes
multi_geom< d, ALLOC >	p_g

T **	p_psl [d-1]

valarray< T >	p_dsl

T *	p_ptr

T **	p_ptr2

T ***	p_ptr3

T ****	p_ptr4

T *****	p_ptr5

T ******	p_ptr6

Static Private Attributes
static const size_type	npos = static_cast<size_type>(-1)

Detailed Description

template<class T, int d, mem_layout ALLOC = MEM_LAYOUT_VAL, bool lgBC = lgBOUNDSCHECKVAL>
class multi_arr< T, d, ALLOC, lgBC >

multi_arr: generic class for allocating multidimensional arrays. A typical example of its use could be:

multi_arr<double,3> arr; // define a placeholder for the array
                  // the first argument is the type of data it holds
                  // the second argument is the number of dimensions
                  // (between 2 and 6)

arr.alloc(3,4,2); // this will allocate a 3x4x2 block of doubles
                  // memory will be allocated as a valarray, so each
                  // element will be initialized to T() -- this means
                  // that even POD types like double with be zeroed

multi_arr<double,3> arr(3,4,2); // shorthand for the above

The following is an alternative way of allocating the array. It is very similar to the pre-multi_arr way of allocating arrays. In ARPA_TYPE arrays this will help you save memory since only the data elements that are really needed will be allocated. In C_TYPE allocation, the smallest rectangular block will be allocated that can hold all the data. This will use more memory in return for somewhat improved CPU speed. Tests carried out in 2007 showed that the speed advantage of C_TYPE arrays was only 1 to 2 percent. Hence the memory savings were deemed more important and ARPA_TYPE arrays were made the default. However, C_TYPE arrays are guaranteed to be compatible with C code, so these should be used if they are meant to be passed on to C library routines. The example below allocates a triangular matrix.

arr.reserve(3);
for( int i=0, i < 3; ++i )
{
  arr.reserve( i, i+1 ); // note that size does not need to be constant!
  for( int j=0, j < i+1; ++j )
    arr.reserve( i, j, j+1 );
}
arr.alloc();

these are plausible ways to use the multi_arr class:

arr.invalidate(); // this will set float or double arrays to all SNaN
                  // it will set any other type array to all 0xff bytes.
arr.zero();       // this will set the array to all zero
arr = -1;         // this will set the array to all -1.

arr[0][0][0] = 1.;
arr[0][0][1] = 2.;
double x = arr[0][0][0]*arr[0][0][1];

multi_arr<double,2,C_TYPE> a(10,10); // allocate C_TYPE array
C_library_routine( a.data(), ... );  // and call C library routine with it

arr.clear();      // this will deallocate the array
                  // the destructor will also automatically deallocate

the multi_arr class comes with iterators that allow you to speed up memory access even further. using iterators as shown below will generally speed up the code significantly since it avoids calculating the array index over and over inside the body of the loop. especially in tight loops over arrays with high dimension this can become a significant overhead! a const_iterator is also supplied for read-only access, but no reverse_iterators. you can define and initialize an iterator as follows

multi_arr<double,3>::iterator p = arr.begin(n,k);

the notation multi_arr<double,3>::iterator is rather cumbersome, so it may be convenient to define something like:

typedef multi_arr<double,3>::iterator md3i;
typedef multi_arr<double,3>::const_iterator md3ci;

all the possible combinations for bool, long, realnum and double multi_arr's are predefined below.

this is a plausible way to use an iterator:

for( int k=0; i < 4; k++ )
{
  for( md3i p = arr.begin(n,k); p != arr.end(n,k); ++p )
    *p = 3.;
}

however, since many compilers have a hard time figuring out that arr.end() has no side effects, it is better to do the following:

for( int k=0; i < 4; k++ )
{
  md3i end = arr.end(n,k);
  for( md3i p = arr.begin(n,k); p != end; ++p )
    *p = 3.;
}

NB NB – the memory layout may change in future editions, so user code should not make any assumptions about the layout. the only exception is that the user may safely assume that for the default memory layout the last index runs over contiguous memory. this allows for efficient iterator access. the example above was OK since arr[n][k][0] and arr[n][k][1] are guaranteed to be adjacent. however the next example is not OK:

!! WRONG !!, arr[n][k-1][1] and arr[n][k][0] may NOT be adjacent

md3i p = arr.begin(n,0);
for( int k=0; i < 4; k++ )
  for( int i=0; i < 2; i++ )
    *p++ = 3.;   // ERROR, this may segfault.
                 // bounds checking will catch this (see below for enabling this)

you can also use iterators for array-like access via []:

double sum = 0.;
for( int k=0; i < 4; k++ )
{
  md3ci p = arr.begin(n,k);
  for( int i=0; i < 2; i++ )
    sum += p[i];
}

last, but not least, the multi_arr class supports array bounds checking, both for direct access through the indexing method, as well as iterator access. To enable bounds checking, simply define the preprocessor macro BOUNDS_CHECK during compilation. the resulting code will be MUCH slower, so this should only be used as a debugging tool.