Implements a multi-dimensional array that supports slicing and array expressions. More...

#include <jem/base/array/Array.h>

Public Types
typedef Tuple< int, N >	Shape
	A type representing the shape of an array. More...

typedef ArrayIterator< T, N >	Iterator
	Array iterator type. More...

typedef Iterator	ConstIterator
	Read-only iterator type. More...

Public Member Functions
	Array ()
	Creates an empty array. More...

	Array (int n)
	Creates a one-dimensional array of a given length. More...

	Array (int n, int m)
	Creates a two-dimensional array with a given shape. More...

	Array (int n, int m, int p)
	Creates a three-dimensional array with a given shape. More...

	Array (int n, int m, int p, int q)
	Creates a four-dimensional array with a given shape. More...

	Array (const Shape &sh)
	Creates an array with a given shape. More...

	Array (const Array &rhs)
	Creates a shallow copy of another array. More...

	Array (const ArrayExpr< T, N > &rhs)
	Creates a new array given an array expression. More...

template<class InputIterator >
	Array (InputIterator first, InputIterator last)
	Creates an array given two input iterators. More...

	~Array ()
	Deallocates memory if necessary. More...

const Array &	operator= (const Array &rhs) const
	Copies the contents of another array. More...

const Array &	operator= (T rhs) const
	Sets all elements of this array to the same value. More...

const Array &	operator= (const ArrayExpr< T, N > &rhs) const
	Assigns an array expression to this array. More...

Iterator	begin () const
	Returns an iterator pointing to the begin of this array. More...

Iterator	end () const
	Returns an iterator pointing to the end of this array. More...

T &	front () const
	Returns a reference to the first element in an array. More...

T &	back () const
	Returns a reference to the last element in an array. More...

Array	clone () const
	Creates a deep copy of this array. More...

void	ref (const Array &rhs)
	Shallow assignment of another array. More...

void	swap (Array &rhs)
	Swaps the data blocks of two arrays. More...

T &	operator[] (int i) const
	Returns the element located at a given index. More...

template<class S >
Array	operator[] (const S &s) const
	Returns a one-dimensional slice of this array. More...

T &	operator() (int i, int j) const
	Returns the element located at a given index pair. More...

T &	operator() (int i, int j, int k) const
	Returns the element located at a given index tuple. More...

T &	operator() (int i, int j, int k, int p) const
	Returns the element located at a given index tuple. More...

template<class S1 , class S2 >
ArraySlice	operator() (const S1 &I, const S2 &J) const
	Returns a slice of a two-dimensional array. More...

template<class S1 , class S2 , class S3 >
ArraySlice	operator() (const S1 &I, const S2 &J, const S3 &K) const
	Returns a slice of a three-dimensional array. More...

template<class S1 , class S2 , class S3 , class S4 >
ArraySlice	operator() (const S1 &I, const S2 &J, const S3 &K, const S4 &L) const
	Returns a slice of a four-dimensional array. More...

Array	transpose () const
	Returns the transpose of this array. More...

Array	transpose (const Tuple< int, N > &perm) const
	Returns a generalized transpose of this array. More...

T &	getFast (int i) const
	Direct data access. More...

bool	isContiguous () const
	Tests whether this array is contiguous. More...

void	resize (int m)
	Modifies the size of a one-dimensional array. More...

void	resize (int m, int n)
	Modifies the shape of a two-dimensional array. More...

void	resize (int m, int n, int p)
	Modifies the shape of a three-dimensional array. More...

void	resize (int m, int n, int p, int q)
	Modifies the shape of a four-dimensional array. More...

void	resize (const Shape &sh)
	Modifies the shape of an array. More...

void	reshape (int m)
	Shrinks or expands a one-dimensional array. More...

void	reshape (int m, int n)
	Shrinks or expands a two-dimensional array. More...

void	reshape (int m, int n, int p)
	Shrinks or expands a three-dimensional array. More...

void	reshape (int m, int n, int p, int q)
	Shrinks or expands a four-dimensional array. More...

void	reshape (const Shape &sh)
	Shrinks or expands an array. More...

int	size () const
	Returns the size of a one-dimensional array. More...

int	size (int dim) const
	Returns one of the sizes of an array. More...

int	stride () const
	Returns the stride of a one-dimensional array. More...

int	stride (int dim) const
	Returns one of the strides of an array. More...

Shape	shape () const
	Returns the shape of this array. More...

T *	addr () const
	Returns a pointer to the data stored in this array. More...

T *	addr (int i) const
	Returns a pointer to a specified element stored in this array. More...

Static Public Attributes
static const int	RANK = N
	The rank of the `Array` class. More...

Related Functions
(Note that these are not member functions.)
Shape construction functions
Tuple< int, 1 >	shape (int n)
	Constructs a one-dimensional shape object. More...

Tuple< int, 2 >	shape (int m, int n)
	Constructs a two-dimensional shape object. More...

Tuple< int, 3 >	shape (int m, int n, int p)
	Constructs a three-dimensional shape object. More...

Tuple< int, 4 >	shape (int m, int n, int p, int q)
	Constructs a four-dimensional shape object. More...

Input and output operators
template<class T , int N>
io::DataInput &	operator>> (io::DataInput &in, Array< T, N > &a)
	Array de-serialization operator. More...

template<class T , int N>
io::DataOutput &	operator<< (io::DataOutput &out, const Array< T, N > &a)
	Array serialization operator. More...

template<class T , int N>
io::TextOutput &	operator<< (io::TextOutput &out, const Array< T, N > &a)
	Array print operator. More...

Detailed Description

template<class T, int N>
class jem::Array< T, N >

The Array class represents a multi-dimensional array of objects. It is a template class with two template parameters. The first parameter, T, specifies the type of the objects stored in the array. This type should define a default constructor and a copy constructor. The second parameter, N, specifies the rank – i.e. the number of dimensions – of the array. At this time, arrays up to rank four are supported. If the rank parameter is omitted, a default value of one is assumed.

Each array has a shape : an integer Tuple of length equal to the rank of the array. The elements of this Tuple specify the sizes of the array in each dimension. For instance, a three-dimensional array with shape (10,3,5) has size 10 in the first dimension, size 3 in the second dimension and size 5 in the third dimension.

The elements in an array are identified in the usual way by a set of integer indices ranging from zero to the corresponding array size minus one. Thus, the index pair (1,0) identifies the second element in the first column of a two-dimensional array.

An array stores its elements in a data block that may be shared with one or more other arrays. As a consequence, multiple arrays may provide different views to parts of the same data. For instance, a one-dimensional array may provide access to one column of a two-dimensional array. Another consequence of the shared storage scheme is that the elements of an array may be modified by modifying the elements of another array. In most cases this is the behavior one would expect, but in some cases it may lead to unexpected results. One should therefore always be aware that multiple arrays may share the same data.

The Array class provides a set of overloaded subscript and function-call operators that can be used to access the elements of an array. The Array class also provides a set of member functions that provide direct access to the data block pointed to by an array. Although one is advised to avoid these functions, they can be useful in the case that you need to pass the contents of an array to a function that expects a standard C/C++ array. They can also be useful to write optimized code sections that avoid redundant index calculations.

More information on using the Array class is provided in the following sections:

Array slices - how to select regular sections of an array.

Array selections - how to select non-regular sections of an array.

Array expressions - how to perform complex operations using simple array expressions.

Array assignment operators - additional assignment operators that are not member functions of the Array class.

Array utility functions - a collection of handy functions that operate on arrays.

Array header files - which header files should be included into your source files.

Note: The Array class uses a non-thread safe reference countaing scheme for sharing data blocks. This means that you should be very careful when using concurrent threads that manipulate the same array data block. The best way to avoid disastrous race conditions is not to share arrays between threads.; The Array class actually has three template arguments. The third argument – which by default equals the class Nil – is used to implement array expressions and is normally not visible to users of the Array class.; All the subscript operators of the Array class return non-const references even though the operators are declared as a const member functions. The reason is that multiple arrays may point to the same data block. Consequently, one could easily modify the elements of a const Array through a non-const Array that points to the same data block.

See also: ArrayExpr.

Examples:: Array.cpp, and game-of-life.cpp.

Member Typedef Documentation

template<class T, int N>

typedef Tuple<int,N> jem::Array< T, N >::Shape

The Shape type represents the shape of an array. It is an alias for Tuple<int,N>.

template<class T, int N>

typedef ArrayIterator<T,N> jem::Array< T, N >::Iterator

An iterator type pointing to elements of type T. This iterator type fulfills the requirements of the bi-directional iterator category of the standard C++ library. If the array rank N equals one, the iterator type fulfills the requirements of the random access iterator category of the standard C++ library.

An iterator of a multi-dimensional array traverses that array in column-major order. That is, the array index in the first dimension varies fastest while the array index in the last dimension varies slowest.

template<class T, int N>

typedef Iterator jem::Array< T, N >::ConstIterator

This is an alias for the Iterator type. The Array class does not provide a separate read-only iterator type since multiple arrays may share the same data. Thus, one can easily modify the elements of an array even if that array is declared constant.

Constructor & Destructor Documentation

template<class T, int N>

jem::Array< T, N >::Array ( )

Creates an empty array.

Postcondition: sum( abs( shape() ) ) == 0

template<class T, int N>

jem::Array< T, N >::Array ( int n )

explicit

Creates a one-dimensional array with length n. The elements of the array are initialized by the default constructor of type T.

Parameters

n	- an integer specifying the length of the array.

Precondition: RANK == 1 && n >= 0
and the type T has a default constructor.

Postcondition: this->size() == n && this->isContiguous()

template<class T, int N>

jem::Array< T, N >::Array	(	int	n,
		int	m
	)

Creates a two-dimensional array with shape (m,n). The elements of the array are initialized by the default constructor of type T.

Parameters

m	- an integer specifying the size of the array in the first dimension.
n	- an integer specifying the size of the array in the second dimension.

Precondition: RANK == 2 && m >= 0 && n >= 0
and the type T has a default constructor.

Postcondition: this->size(0) == m && this->size(1) == n && this->isContiguous()

template<class T, int N>

jem::Array< T, N >::Array	(	int	n,
		int	m,
		int	p
	)

Creates a three-dimensional array with shape (m,n,p). The elements of the array are initialized by the default constructor of type T.

Parameters

m	- an integer specifying the size of the array in the first dimension.
n	- an integer specifying the size of the array in the second dimension.
p	- an integer specifying the size of the array in the third dimension.

Precondition: RANK == 3 && m >= 0 && n >= 0 && p >= 0
and the type T has a default constructor.

Postcondition: this->size(0) == m && this->size(1) == n && this->size(2) == p && this->isContiguous()

template<class T, int N>

jem::Array< T, N >::Array	(	int	n,
		int	m,
		int	p,
		int	q
	)

Creates a four-dimensional array with shape (m,n,p,q). The elements of the array are initialized by the default constructor of type T.

Parameters

m	- an integer specifying the size of the array in the first dimension.
n	- an integer specifying the size of the array in the second dimension.
p	- an integer specifying the size of the array in the third dimension.
q	- an integer specifying the size of the array in the fourth dimension.

Precondition: RANK == 4 && m >= 0 && n >= 0 && p >= 0 && q >= 0
and the type T has a default constructor.

Postcondition: this->size(0) == m && this->size(1) == n && this->size(2) == p && this->size(3) == q && this->isContiguous()

template<class T, int N>

jem::Array< T, N >::Array ( const Shape & sh )

explicit

Creates an N-dimensional array with shape sh. The elements of the array are initialized by the default constructor of type T.

Parameters

sh	- the shape of the array.

Precondition: min(sh) >= 0
and the type T has a default constructor.

Postcondition: equal( this->shape(), sh ) &&
this->isContiguous()

See also: jem::shape().

template<class T, int N>

jem::Array< T, N >::Array ( const Array< T, N > & rhs )

The copy constructor of the Array class creates a shallow copy of the rhs array. This means that the newly created array points to the same data block as the original array. Any modifications in the new array will therefore be visible in the original array, and the other way around.

Because of the shallow copy semantics, returning an array from a function is a relatively cheap operation.

Parameters

rhs	- an `Array` object.

template<class T, int N>

jem::Array< T, N >::Array ( const ArrayExpr< T, N > & rhs )

Constructs an array from the array expression rhs. In contrast to the copy constructor, this constructor has deep copy semantics. This means that the new array does not share its data with the array expression.

The newly created array has the same shape as the rhs array expression.

Parameters

rhs	- an array expression.

Postcondition: equal( this->shape(), rhs.shape() ) && this->isContiguous()

template<class T, int N>

template<class InputIterator >

jem::Array< T, N >::Array	(	InputIterator	first,
		InputIterator	last
	)

Constructs a one-dimensional array containing copies of the elements between the input iterators first and last. The elements are copied by calling the copy constructor of type T.

Parameters

first	- an input iterator pointing to the first element to be copied into the new array.
last	- an input iterator pointing one position past the last element to be copied into this array.

Precondition: RANK == 1
and the type T has a copy constructor,
and the input iterator last is reachable from first.

Postcondition: this->size() == std::distance( first, last ) && this->isContiguous()

template<class T, int N>

jem::Array< T, N >::~Array ( )

The destructor of the Array class will deallocate the data block this array is pointing to if no other arrays are pointing to the same data block.

Member Function Documentation

template<class T, int N>

const Array& jem::Array< T, N >::operator= ( const Array< T, N > & rhs ) const

Copies the elements of the rhs array into this array. To be precise, the elements of the rhs array are copied into the data block this array is pointing to. The memory areas pointed to by the rhs array and this array should not overlap.

The elements are copied by calling the assignment operator of type T.

Parameters

rhs	- the array to be copied.

Returns: *this

Precondition: equals( this->shape(), rhs.shape() )
and the type T has an assignment operator.

Note: In contrast to the copy constructor, the assignment operator of the Array class has deep copy semantics.

See also: Array assignment operators.

template<class T, int N>

const Array& jem::Array< T, N >::operator= ( T rhs ) const

Assigns all elements of this array the value rhs by calling the assignment operator of type T.

Parameters

rhs	- the value to be copied.

Returns: *this

Precondition: The type T has an assignment operator.

See also: Array assignment operators.

template<class T, int N>

const Array& jem::Array< T, N >::operator= ( const ArrayExpr< T, N > & rhs ) const

Copies the elements of the array expression rhs into this array. To be precise, the elements of the rhs array expression are copied into the data block this array is pointing to.

The elements are copied by calling the assignment operator of type T.

Parameters

rhs	- an array expression.

Returns: *this

Precondition: equal( this->shape(), rhs.shape() )
and the type T has an assignment operator.

See also: Array assignment operators.

template<class T, int N>

Iterator jem::Array< T, N >::begin ( ) const

Returns an iterator pointing to the first element in this array, or end() if this array is empty. The iterator is valid as long as the data block pointed to by this array is not deallocated.

Returns: An iterator pointing to the first element in this array, or end() if the array is empty.

template<class T, int N>

Iterator jem::Array< T, N >::end ( ) const

Returns an iterator pointing one position past the last element in this array. The iterator is valid as long as the data block pointed to by this array is not deallocated.

Returns: An iterator pointing one position past the last element in this array.

template<class T, int N>

T& jem::Array< T, N >::front ( ) const

Returns a reference to the first element in a one-dimensional array. This reference is valid as long as the data block pointed to by this array is not deallocated.

Returns: A reference to the first element in this array: (*this)[0].

Precondition: RANK == 1 && this->size() > 0

template<class T, int N>

T& jem::Array< T, N >::back ( ) const

Returns a reference to the last element in a one-dimensional array. This reference is valid as long as the data block pointed to by this array is not deallocated.

Returns: A reference to the last element in this array: (*this)[ size() - 1 ].

Precondition: RANK == 1 && this->size() > 0

template<class T, int N>

Array jem::Array< T, N >::clone ( ) const

Returns a deep copy of this array. That is, the returned array contains copies of the elements in this array. The returned array is guaranteed to be contiguous. In other words:

clone().isContiguous() == true.

Returns: A deep copy of this array.

See also: isContiguous().

template<class T, int N>

void jem::Array< T, N >::ref ( const Array< T, N > & rhs )

After calling the ref member function, this array will point to the same data block as the rhs array. Consequently, any modifications to this array will be visible in the rhs array, and the other way around.

Parameters

rhs	- an array of the same rank as this array.

Postcondition: equals( this->shape(), rhs.shape() ) && this->addr() == rhs.addr()

template<class T, int N>

void jem::Array< T, N >::swap ( Array< T, N > & rhs )

Swaps the data blocks and shapes of this array and the rhs array. Thus, after calling the member swap, this array has the shape of the rhs array and points to the data block of that array. Conversely, the rhs array has the shape of this array and points to the data block of this array.

Parameters

rhs	- an array of the same rank as this array.

template<class T, int N>

T& jem::Array< T, N >::operator[] ( int i ) const

Returns a reference to the i-th element of a one-dimensional array. This reference is valid as long as the data block pointed to by this array is not deallocated.

Parameters

i	- a valid array index.

Returns: addr()[ i * stride() ]

Precondition: RANK == 1 && i >= 0 && i < this->size()

template<class T, int N>

template<class S >

Array jem::Array< T, N >::operator[] ( const S & s ) const

Returns a one-dimensional Array object that refers to a section of this array. This operator is only supported by one-dimensional arrays.

Parameters

s	- a `Slice` instance or an instance of a class derived from `Slice`.

Returns: A slice of this array.

Precondition: RANK == 1

See also: Array slices.

template<class T, int N>

T& jem::Array< T, N >::operator()	(	int	i,
		int	j
	)		const

Returns a reference to the element (i,j) of a two-dimensional array. The reference is valid as long as the data block pointed to by this array is not deallocated.

Parameters

i	- a valid array index in the first dimension.
j	- a valid array index in the second dimension.

Returns: addr()[ i * stride(0) + j * stride(1) ]

Precondition: RANK == 2 && i >= 0 && i < this->size(0) && j >= 0 && j < this->size(1)

template<class T, int N>

T& jem::Array< T, N >::operator()	(	int	i,
		int	j,
		int	k
	)		const

Returns a reference to the element (i,j,k) of a three-dimensional array. This reference is valid as long as the data block pointed to by this array is not deallocated.

Parameters

i	- a valid array index in the first dimension.
j	- a valid array index in the second dimension.
k	- a valid array index in the third dimension.

Returns: addr()[ i * stride(0) + j * stride(1) + k * stride(2) ]

Precondition: RANK == 3 && i >= 0 && i < this->size(0) && j >= 0 && j < this->size(1) && k >= 0 && k < this->size(2)

template<class T, int N>

T& jem::Array< T, N >::operator()	(	int	i,
		int	j,
		int	k,
		int	p
	)		const

Returns a reference to the element (i,j,k,p) of a four-dimensional array. This reference is valid as long as the data block pointed to by this array is not deallocated.

Parameters

i	- a valid array index in the first dimension.
j	- a valid array index in the second dimension.
k	- a valid array index in the third dimension.
p	- a valid array index in the fourth dimension.

Returns: addr()[ i * stride(0) + j * stride(1) + k * stride(2) + p * stride(3) ]

Precondition: RANK == 4 && i >= 0 && i < this->size(0) && j >= 0 && j < this->size(1) && k >= 0 && k < this->size(2) && p >= 0 && p < this->size(3)

template<class T, int N>

template<class S1 , class S2 >

ArraySlice jem::Array< T, N >::operator()	(	const S1 &	I,
		const S2 &	J
	)		const

Returns a one-dimensional or two-dimensional Array object that refers to a rectangular section of this two-dimensional array. The returned array points to the same data block as this array.

Note that the return type ArraySlice is a dummy type; depending on the types of the template parameters S1 and S2, ArraySlice is either equal to Array<T,1> or Array<T,2>.

Parameters

I	- a `Slice` or a valid integer index in the first dimension
J	- a `Slice` or a valid integer index in the second dimension.

Returns: A rectangular slice of this two-dimensional array.

Precondition: RANK == 2
and if I is an integer: I >= 0 && I < this->size(0);
and if J is an integer: J >= 0 && J < this->size(1).

See also: Array slices.

template<class T, int N>

template<class S1 , class S2 , class S3 >

ArraySlice jem::Array< T, N >::operator()	(	const S1 &	I,
		const S2 &	J,
		const S3 &	K
	)		const

Returns a one-dimensional, two-dimensional or three-dimensional Array object that refers to a rectangular section of this three-dimensional array. The returned array points to the same data block as this array.

Note that the return type ArraySlice is a dummy type; depending on the types of the template parameters S1 and S2, ArraySlice is either equal to Array<T,1>, Array<T,2>, or Array<T,3>.

Parameters

I	- a `Slice` or a valid integer index in the first dimension.
J	- a `Slice` or a valid integer index in the second dimension.
K	- a `Slice` or a valid integer index in the third dimension.

Returns: A rectangular slice of this three-dimensional array.

Precondition: RANK == 3
and if I is an integer: I >= 0 && I < this->size(0);
and if J is an integer: J >= 0 && J < this->size(1);
and if K is an integer: K >= 0 && K < this->size(2).

See also: Array slices.

template<class T, int N>

template<class S1 , class S2 , class S3 , class S4 >

ArraySlice jem::Array< T, N >::operator()	(	const S1 &	I,
		const S2 &	J,
		const S3 &	K,
		const S4 &	L
	)		const

Returns a one-dimensional, two-dimensional, three-dimensional, or four-dimensional Array object that refers to a rectangular section of this four-dimensional array. The returned array points to the same data block as this array.

Note that the return type ArraySlice is a dummy type; depending on the types of the template parameters S1 and S2, ArraySlice is either equal to Array<T,1>, Array<T,2>, Array<T,3>, Array<T,4>.

Parameters

I	- a `Slice` or a valid integer index in the first dimension.
J	- a `Slice` or a valid integer index in the second dimension.
K	- a `Slice` or a valid integer index in the third dimension.
L	- a `Slice` or a valid integer index in the fourth dimension.

Returns: A rectangular slice of this four-dimensional array.

Precondition: RANK == 4
and if I is an integer: I >= 0 && I < this->size(0);
and if J is an integer: J >= 0 && J < this->size(1);
and if K is an integer: K >= 0 && K < this->size(2);
and if L is an integer: L >= 0 && L < this->size(3).

See also: Array slices.

template<class T, int N>

Array jem::Array< T, N >::transpose ( ) const

Returns a view of this array with reversed dimensions. That is, the first dimension of the returned array corresponds with the last dimension of this array; the second dimension of the returned array correponds with the second to last dimension of this array; etc. The returned array points to the same data block as this array; any modifications to the returned array are therefore also visible in this array.

Here is an example:

Array<int,3> a ( 3, 4, 5 );
Array<int,3> b ( a.transpose() );
b        = 0;
b(0,1,2) = 1;
b(1,2,3) = 1;

After executing these statements, all elements of a are zero, except for the elements a(2,1,0) and a(3,2,1).

This function is equivalent with:

Tuple<int,N> perm;
int          i;
for ( i = 0; i < N; i++ )
{
  perm[i] = N - i - 1;
}
return this->transpose ( perm );

Returns: The transpose of this array.

template<class T, int N>

Array jem::Array< T, N >::transpose ( const Tuple< int, N > & perm ) const

Returns the generalized transpose of this array. The transposed array contains the same elements as this array, but its dimensions have been permuted according to the Tuple perm. To be precise, dimension 0 of the transposed array corresponds with dimension perm[0] of this array; dimension 1 of the transposed array corresponds with dimension perm[1] of this array; etc.

Example:

Array<int,3> a ( 2, 2, 2   );
Array<int,3> b ( a.shape() );
Array<int,3> c ( a.shape() );
b = a.transpose ( makeTuple( 1, 0, 2 ) );
c = a.transpose ( makeTuple( 2, 1, 0 ) );

After executing this code fragment, the following expressions will be true for all valid index tuples (i j,k):

b(j,i,k) == a(i,j,k);

c(k,j,i) == a(i,j,k);

Note that the transposed array points to the same data block as this array; all modifications to the transposed array will therefore be visible in this array.

Parameters

perm	- a permutation `Tuple` specifying how the dimensions of the transposed array are related to the dimensions of this array.

Returns: The generalized transpose of this array.

Precondition: RANK > 1

template<class T, int N>

T& jem::Array< T, N >::getFast ( int i ) const

Returns a reference to the i-th element stored in the part of the data block that this array is pointing to. The reference is valid as long as the data block pointed to by this array is not deallocated.

Parameters

i	- a valid index.

Returns: addr()[i]

template<class T, int N>

bool jem::Array< T, N >::isContiguous ( ) const

Tests whether the elements of this array are stored contiguously in memory. A one-dimensional array is contiguous if its stride equals one. A multi-dimensional array is contiguous if the following two conditions are fulfilled:

stride(0) == 1;
stride(i) == size(i - 1) * stride(i - 1).

for all 0 < i < N.

Note that a two-dimensional array is contiguous if its elements are stored contiguously in column-major order. Also note that the elements of a contiguous array are stored in the same way as the elements of a Fortran-77 array.

Returns: true if the elements of this array are stored contiguously in memory, and false otherwise.

template<class T, int N>

void jem::Array< T, N >::resize ( int m )

Sets the size of this one-dimensional array to m. Calling this function has the same effect as:

this->resize ( shape(m) )

Parameters

m	– the new size of this array.

Precondition: RANK == 1 && m >= 0

Postcondition: this->size() == m

See also: resize ( const Shape& )

template<class T, int N>

void jem::Array< T, N >::resize	(	int	m,
		int	n
	)

Sets the shape of this two-dimensional array to (m,n). Calling this function has the same effect as:

this->resize ( shape( m, n ) )

Parameters

m	- the new array size in the first dimension.
n	- the new array size in the second dimension.

Precondition: RANK == 2 && m >= 0 && n >= 0

Postcondition: this->size(0) == m && this->size(1) == n

See also: resize ( const Shape& )

template<class T, int N>

void jem::Array< T, N >::resize	(	int	m,
		int	n,
		int	p
	)

Sets the shape of this three-dimensional array to (m,n,p). Calling this function has the same effect as:

this->resize ( shape( m, n, p ) )

Parameters

m	- the new array size in the first dimension.
n	- the new array size in the second dimension.
p	- the new array size in the third dimension.

Precondition: RANK == 3 && m >= 0 && n >= 0 && p >= 0

Postcondition: this->size(0) == m && this->size(1) == n && this->size(2) == p

See also: resize ( const Shape& )

template<class T, int N>

void jem::Array< T, N >::resize	(	int	m,
		int	n,
		int	p,
		int	q
	)

Sets the shape of this four-dimensional array to (m,n,p,q). Calling this function has the same effect as:

this->resize ( shape( m, n, p, q ) )

Parameters

m	- the new array size in the first dimension.
n	- the new array size in the second dimension.
p	- the new array size in the third dimension.
q	- the new array size in the fourth dimension.

Precondition: RANK == 4 && m >= 0 && n >= 0 && p >= 0 && q >= 0

Postcondition: this->size(0) == m && this->size(1) == n && this->size(2) == p && this->size(3) == q

See also: resize ( const Shape& )

template<class T, int N>

void jem::Array< T, N >::resize ( const Shape & sh )

Sets the shape of this array to sh. From a logical point of view, calling this function has the same effect as executing the following statement:

this->ref ( Array<T,N>( sh ) )

However, there are two subtle differences between the resize function and the above statement. First, the resize function will re-use the data block this array is pointing to, provided that the block is large enough and that the block is not shared with another array. Consequently, the resize function can be significantly faster than the above statement. The second difference is that the resize function may not immediately call the destructor of the array elements that are no longer used (the destructor will be called eventually when the data block of the array is deallocated). This means that you should be careful when calling the resize function for an array containing elements with a non-trivial destructor.

The resize function does not preserve the contents of an array. That is, after calling the resize function you should not make any assumptions about the values of the array elements. Use the member function reshape if you want to modify the shape of an array and also preserve its contents.

An array is guaranteed to be contiguous after calling its resize member function.

Parameters

sh	- the new shape of this array.

Precondition: min( sh ) >= 0

Postcondition: equal( this->shape(), sh ) && this->isContiguous()

See also: reshape( const Shape& )

template<class T, int N>

void jem::Array< T, N >::reshape ( int m )

Shrinks or expands this one-dimensional array so that its size becomes m. Calling this function has the same effect as:

this->reshape ( shape(m) )

Parameters

m	– the new size of this array.

Precondition: RANK == 1 && m >= 0

Postcondition: this->size() == m

See also: reshape ( const Shape& )

template<class T, int N>

void jem::Array< T, N >::reshape	(	int	m,
		int	n
	)

Shrinks or expands this two-dimensional array so that its shape becomes (m,n). Calling this function has the same effect as:

this->reshape ( shape( m, n ) )

Parameters

m	- the new array size in the first dimension.
n	- the new array size in the second dimension.

Precondition: RANK == 2 && m >= 0 && n >= 0

Postcondition: this->size(0) == m && this->size(1) == n

See also: reshape ( const Shape& )

template<class T, int N>

void jem::Array< T, N >::reshape	(	int	m,
		int	n,
		int	p
	)

Shrinks or expands this three-dimensional array so that its shape becomes (m,n,p). Calling this function has the same effect as:

this->reshape ( shape( m, n, p ) )

Parameters

m	- the new array size in the first dimension.
n	- the new array size in the second dimension.
p	- the new array size in the third dimension.

Precondition: RANK == 3 && m >= 0 && n >= 0 && p >= 0

Postcondition: this->size(0) == m && this->size(1) == n && this->size(2) == p

See also: reshape ( const Shape& )

template<class T, int N>

void jem::Array< T, N >::reshape	(	int	m,
		int	n,
		int	p,
		int	q
	)

Shrinks or expands this four-dimensional array so that its shape becomes (m,n,p,q). Calling this function has the same effect as:

this->reshape ( shape( m, n, p, q ) )

Parameters

m	- the new array size in the first dimension.
n	- the new array size in the second dimension.
p	- the new array size in the third dimension.
q	- the new array size in the fourth dimension.

Precondition: RANK == 4 && m >= 0 && n >= 0 && p >= 0 && q >= 0

Postcondition: this->size(0) == m && this->size(1) == n && this->size(2) == p && this->size(3) == q

See also: reshape ( const Shape& )

template<class T, int N>

void jem::Array< T, N >::reshape ( const Shape & sh )

Shrinks or expands this array so that its shape becomes sh. All elements of this array that are located within the shape sh are preserved. Any additional elements are initialized by calling the default constructor of type T. All elements within this array that are not located within the shape sh are destroyed by calling the destructor of type T.

If this array does not share its data with another array, the reshape function will try to expand or shrink its current data block. If that is not possible, or if the data block is shared with another array, the reshape function will allocate a new data block and copy the current array elements to that new block. To be precise, it only copies the elements that are located within the shape sh to the new block.

An array is guaranteed to be contiguous after calling its reshape member function.

Parameters

sh	- the new shape of this array.

Precondition: min( sh ) >= 0

Postcondition: equal( this->shape(), sh ) && this->isContiguous()

See also: resize( const Shape& )

template<class T, int N>

int jem::Array< T, N >::size ( ) const

Returns the number of elements stored in this one-dimensional array.

Returns: The length of this array.

Precondition: RANK == 1

template<class T, int N>

int jem::Array< T, N >::size ( int dim ) const

Returns the size of this array in the dimension dim. For instance, if a is a two-dimensional array, then a.size(0) equals the number of rows, while a.size(1) equals the number of columns.

Parameters

dim	- a dimension index.

Returns: this->shape()[dim]

Precondition: dim >= 0 && dim < N

template<class T, int N>

int jem::Array< T, N >::stride ( ) const

Returns the stride of this one-dimensional array. The stride specifies how far apart the elements of this array are stored in memory. If the stride equals one, then all elements are stored contiguously in memory. In this case, the array is said to be contiguous.

You will probably need this function if you want to access the elements of a one-dimensional array directly.

Returns: The stride of this array.

Precondition: RANK == 1

See also: isContigous().

template<class T, int N>

int jem::Array< T, N >::stride ( int dim ) const

Returns the stride of this array in the dimension dim. This stride specifies the distance (in terms of memory addresses) between two consecutive elements in the dimension dim.

You will probably need this function if you want to access the elements of an array directly.

Parameters

dim	- the dimension index.

Returns: The stride of this array in the dimension dim.

Precondition: dim >= 0 && dim < N

See also: isContigous().

template<class T, int N>

Shape jem::Array< T, N >::shape ( ) const

Returns a tuple of length N containing the sizes of this array in all its dimensions. For instance, if this is a two-dimensional array with five rows and seven columns, then the function shape returns a tuple containing the values (5,7).

Returns: The shape of this array.

template<class T, int N>

T* jem::Array< T, N >::addr ( ) const

Returns the memory address of the first element stored in this array. This pointer remains valid as long as the data block is not deallocated.

Returns: A pointer to the elements stored in this array.

template<class T, int N>

T* jem::Array< T, N >::addr ( int i ) const

Returns the memory address of the i-th element stored in this one-dimensional array. The pointer remains valid as long as the data block is not deallocated.

Returns: addr() + ( stride() * i )

Precondition: RANK == 1

Friends And Related Function Documentation

template<class T, int N>

Tuple< int, 1 > shape ( int n )

Parameters

n	- the element of the returned tuple.

Returns: Tuple<int,1> ( n )

Precondition: n >= 0

template<class T, int N>

Tuple< int, 2 > shape	(	int	m,
		int	n
	)

Parameters

m	- the first element of the returned tuple.
n	- the second element of the returned tuple.

Returns: Tuple<int,2> ( m, n )

Precondition: m >= 0 && n >= 0

template<class T, int N>

Tuple< int, 3 > shape	(	int	m,
		int	n,
		int	p
	)

Parameters

m	- the first element of the returned tuple.
n	- the second element of the returned tuple.
p	- the third element of the returned tuple.

Returns: Tuple<int,3> ( m, n, p )

Precondition: m >= 0 && n >= 0 && p >= 0

template<class T, int N>

Tuple< int, 4 > shape	(	int	m,
		int	n,
		int	p,
		int	q
	)

Parameters

m	- the first element of the returned tuple.
n	- the second element of the returned tuple.
p	- the third element of the returned tuple.
q	- the fourth element of the returned tuple.

Returns: Tuple<int,4> ( m, n, p, q )

Precondition: m >= 0 && n >= 0 && p >= 0 && q >= 0

template<class T , int N>

io::DataInput & operator>>	(	io::DataInput &	in,
		Array< T, N > &	a
	)

Parameters

in	- the `DataInputStream` from which the array is to be read.
a	- the `Array` to be read.

Returns: in

Exceptions

io::IOException	- if an IO error occurs.
io::SerializationException	- if the data input stream is corrupt.

Precondition: The following operator has been defined:
io::DataInput& operator >> ( io::DataInput&, T& )

template<class T , int N>

io::DataOutput & operator<<	(	io::DataOutput &	out,
		const Array< T, N > &	a
	)

Parameters

out	- the data output stream to which the array is to be written.
a	- the `Array` to be written.

Returns: out

Exceptions

io::IOException - if an IO error occurs.

Precondition: The following operator has been defined:
io::DataOutput& operator << ( io::DataOutput&, const T& )

template<class T , int N>

io::TextOutput & operator<<	(	io::TextOutput &	out,
		const Array< T, N > &	a
	)

Parameters

out	- the text output stream to which the array is to be written.
a	- the array to be printed.

Returns: out

Exceptions

io::IOException - if an IO error occurs.

Precondition: The following operator has been defined:
io::TextOutput& operator << ( io::TextOutput&, cont T& )

Member Data Documentation

template<class T, int N>

const int jem::Array< T, N >::RANK = N

static

RANK specifies the rank of the Array class. It is an integer constant equal to the second template parameter N.

Public Types

Public Member Functions

Static Public Attributes

Related Functions

Detailed Description

template<class T, int N> class jem::Array< T, N >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

template<class T, int N>
class jem::Array< T, N >