Encapsulates a fixed-size, two-dimensional array. More...

#include <jem/base/tuple/Tuple.h>

Public Types
typedef T *	Iterator
	A random access iterator type. More...

typedef const T *	ConstIterator
	A read-only random access iterator type. More...

Public Member Functions
	Tuple ()
	Default constructor. More...

	Tuple (T a)
	Constructs a tuple given a single element. More...

	Tuple (T a, T b)
	Constructs a tuple given the first two elements. More...

	Tuple (T a, T b, T c)
	Constructs a tuple given the first three elements. More...

	Tuple (T a, T b, T c, T d)
	Constructs a tuple given the first four elements. More...

	Tuple (const TupleExpr< T, M, N > &rhs)
	Constructs a tuple from a tuple expression. More...

	Tuple (const Tuple &rhs)
	Creates a copy of another tuple. More...

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

ConstIterator	begin () const
	Returns a const iterator pointing to the begin of this tuple. More...

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

ConstIterator	end () const
	Returns a const iterator pointing to the end of this tuple. More...

Tuple &	operator= (const TupleExpr< T, M, N > &rhs)
	Copies a tuple expression. More...

Tuple &	operator= (const Tuple &rhs)
	Copies another tuple. More...

Tuple &	operator= (T rhs)
	Sets all elements in this tuple to a specified value. More...

void	swap (Tuple &rhs)
	Swaps the elements of this tuple with another one. More...

T &	operator[] (int i)
	Returns a reference to an element at a given index. More...

const T &	operator[] (int i) const
	Returns a const reference to an element at a given index. More...

T &	operator() (int i, int j)
	Returns a reference to an element at a given index pair. More...

T &	operator() (int i, int j)
	Returns a const reference to an element at a given index pair. More...

Tuple< T, N, M >	transpose () const
	Returns the transpose of this tuple. More...

T *	addr ()
	Returns a pointer to the elements in this tuple. More...

const T *	addr () const
	Returns a const pointer to the elements in this tuple. More...

Static Public Attributes
static const int	SIZE = M * N
	The size of a tuple. More...

Related Functions
(Note that these are not member functions.)
template<class T , int M, int N>
void	swap (Tuple< T, M, N > &lhs, Tuple< T, M, N > &rhs)
	Swaps two tuples. More...

template<class T , int M, int N>
io::DataInput &	operator>> (io::DataInput &in, Tuple< T, M, N > &t)
	Tuple de-serialization operator. More...

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

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

Detailed Description

template<class T, int M, int N = 1>
class jem::Tuple< T, M, N >

The class template Tuple implements a two-dimensional array of a fixed size. The first template parameter, T, sepcifies the type of the elements stored in a Tuple. The other two template parameters, M and N, specify the number of rows and columns, respectively, in a Tuple. Thus, the type Tuple<int,2,2> represents an integer matrix with two rows and two columns. Note that by default the number of columns equals one.

The elements in a Tuple can be accessed through two overloaded subscript operators. The first has two integer arguments and enables one to access a tuple as a matrix. The second one has only one integer argument and alllows one to access a tuple as a one-dimensional array. The latter operator is handy when either M or N equals one. This operator also enables one to access a particular tuple element directly and to exploit the specific way in the tuple elements are stored in memory (see below).

The Tuple class stores its elements in a statically allocated C/C++ array that is part of a Tuple instance. This means that the construction of a tuple is a cheap operation. This also means that a tuple with shape (M,N) requires the same amount of storage as a static C/C++ array of size (M * N).

The elements in a tuple are stored in column-major order. That is, if k denotes the index within the private C/C++ array at wich element (i,j) is stored, then k = i + j * M.

More specific information on the Tuple class is available in the following sections:

Tuple expressions - how to write expressions that operate on all elements of one or more tuples.

Tuple assignment operators - additional assignment operators that are not members of the Tuple class.

Tuple utility functions - a collection of handy functions that operate on tuples.

Tuple header files - an overview of the header files that you should include into your source code.

See also: TupleExpr.

Examples:: Tuple.cpp.

Member Typedef Documentation

template<class T, int M, int N = 1>

typedef T* jem::Tuple< T, M, N >::Iterator

A random access iterator type pointing to elements of type T. This iterator traverses the elements in a tuple in column-major order and fulfills the requirements of the random access iterator category of the standard C++ library.

template<class T, int M, int N = 1>

typedef const T* jem::Tuple< T, M, N >::ConstIterator

A random access iterator type pointing to elements of type const T. This iterator traverses the elements in a tuple in column-major order and fulfills the requirements of the random access iterator category of the standard C++ library.

Constructor & Destructor Documentation

template<class T, int M, int N = 1>

jem::Tuple< T, M, N >::Tuple ( )

Constructs a tuple with shape (M,N). The elements of this tuple are initialized by calling the default constructor of type T.

Precondition: The type T has a default constructor.

template<class T, int M, int N = 1>

jem::Tuple< T, M, N >::Tuple ( T a )

Constructs a tuple containing the value a as its first element.

Parameters

a	- the first element in the constructed tuple.

Precondition: SIZE >= 1
and the type T has a default constructor.

Postcondition: (*this)[0] == a

See also: makeTuple()

template<class T, int M, int N = 1>

jem::Tuple< T, M, N >::Tuple	(	T	a,
		T	b
	)

Constructs a tuple containing the values a and b as its first two elements.

Parameters

a	- the first element in the constructed tuple.
b	- the second element in the constructed tuple.

Precondition: SIZE >= 2
and the type T has a default constructor.

Postcondition: (*this)[0] == a && (*this)[1] == b

See also: makeTuple()

template<class T, int M, int N = 1>

jem::Tuple< T, M, N >::Tuple	(	T	a,
		T	b,
		T	c
	)

Constructs a tuple containing the values a, b and c as its first three elements.

Parameters

a	- the first element in the constructed tuple.
b	- the second element in the constructed tuple.
c	- the third element in the constructed tuple.

Precondition: SIZE >= 3
and the type T has a default constructor.

Postcondition: (*this)[0] == a && (*this)[1] == b && (*this)[2] == c

See also: makeTuple()

template<class T, int M, int N = 1>

jem::Tuple< T, M, N >::Tuple	(	T	a,
		T	b,
		T	c,
		T	d
	)

Constructs a tuple containing the values a, b, c and d as its first four elements.

Parameters

a	- the first element in the constructed tuple.
b	- the second element in the constructed tuple.
c	- the third element in the constructed tuple.
d	- the fourth element in the constructed tuple.

Precondition: SIZE >= 4
and the type T has a default constructor.

Postcondition: (*this)[0] == a && (*this)[1] == b && (*this)[2] == c && (*this)[3] == d

See also: makeTuple()

template<class T, int M, int N = 1>

jem::Tuple< T, M, N >::Tuple ( const TupleExpr< T, M, N > & rhs )

Constructs a tuple from the tuple expression rhs.

Parameters

rhs	- a tuple expression.

template<class T, int M, int N = 1>

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

Creates a deep copy of the rhs tuple.

Parameters

rhs	- the `Tuple` to be copied.

Postcondition: (*this)[i] == rhs[i] for all 0 <= i < SIZE

Member Function Documentation

template<class T, int M, int N = 1>

Iterator jem::Tuple< T, M, N >::begin ( )

Returns an iterator pointing to the first element in this tuple. The iterator is valid as long as this tuple exists.

Returns: An iterator pointing to the first element in this tuple.

template<class T, int M, int N = 1>

ConstIterator jem::Tuple< T, M, N >::begin ( ) const

Returns a const iterator pointing to the first element in this tuple. The iterator is valid as long as this tuple exists.

Returns: A const iterator pointing to the first element in this tuple.

template<class T, int M, int N = 1>

Iterator jem::Tuple< T, M, N >::end ( )

Returns an iterator pointing to one position past the last element in this tuple. The iterator is valid as long as this tuple exists.

Returns: An iterator pointing to the end of this tuple.

template<class T, int M, int N = 1>

ConstIterator jem::Tuple< T, M, N >::end ( ) const

Returns a const iterator pointing to one position past the last element in this tuple. The iterator is valid as long as this tuple exists.

Returns: A const iterator pointing to the end of this tuple.

template<class T, int M, int N = 1>

Tuple& jem::Tuple< T, M, N >::operator= ( const TupleExpr< T, M, N > & rhs )

Copies the elements of the tuple expression rhs into this tuple using the assignment operator of type T.

Parameters

rhs	- a tuple expression.

Returns: *this

Precondition: The type T has an assignment operator.

template<class T, int M, int N = 1>

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

Copies the elements of the tuple rhs into this tuple using the assignment operator of type T.

Parameters

rhs	- the `Tuple` to be copied.

Returns: *this

Precondition: The type T has an assignment operator.

template<class T, int M, int N = 1>

Tuple& jem::Tuple< T, M, N >::operator= ( T rhs )

Sets all elements in this tuple to the value rhs using the assignment operator of type T.

Parameters

rhs	- the value to which the elements in this tuple should be set.

Returns: *this

Precondition: The type T has an assignment operator.

template<class T, int M, int N = 1>

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

Swaps the elements in this tuple with the elements in the rhs tuple using the assignment operator of type T.

Parameters

rhs	- the `Tuple` wich which the elements in this tuple should be swapped.

Precondition: The type T has an assignment operator.

template<class T, int M, int N = 1>

T& jem::Tuple< T, M, N >::operator[] ( int i )

Returns a reference to the i-th element in this tuple. The reference is valid as long as this tuple exists.

Parameters

i	- a valid index.

Returns: this->addr()[i]

Precondition: i >= 0 && i < SIZE

template<class T, int M, int N = 1>

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

Returns a const reference to the i-th element in this tuple. The reference is valid as long as this tuple exists.

Parameters

i	- a valid index.

Returns: this->addr()[i]

Precondition: i >= 0 && i < SIZE

template<class T, int M, int N = 1>

T& jem::Tuple< T, M, N >::operator()	(	int	i,
		int	j
	)

Returns a reference to the element at location (i,j) in this tuple. The reference is valid as long as this tuple exists.

Parameters

i	- a valid row index.
j	- a valid column index.

Returns: this->addr()[i + j * M]

Precondition: i >= 0 && i < M && j >= 0 && j < N

template<class T, int M, int N = 1>

T& jem::Tuple< T, M, N >::operator()	(	int	i,
		int	j
	)

Returns a const reference to the element at location (i,j) in this tuple. The reference is valid as long as this tuple exists.

Parameters

i	- a valid row index.
j	- a valid column index.

Returns: this->addr()[i + j * M]

Precondition: i >= 0 && i < M && j >= 0 && j < N

template<class T, int M, int N = 1>

Tuple<T,N,M> jem::Tuple< T, M, N >::transpose ( ) const

Returns the transpose of this tuple. That is, the element (i,j) in the returned tuple is a copy of the element (j,i) in this tuple.

Precondition: The type T has an assignment operator.

Returns: The transpose of this tuple.

template<class T, int M, int N = 1>

T* jem::Tuple< T, M, N >::addr ( )

Returns a pointer to the array containing the elements stored in this tuple. The pointer is valid as long as this tuple exists.

Returns: A pointer to the elements in this tuple.

template<class T, int M, int N = 1>

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

Returns a const pointer to the array containing the elements stored in this tuple. The pointer is valid as long as this tuple exists.

Returns: A const pointer to the elements in this tuple.

Friends And Related Function Documentation

template<class T , int M, int N>

void swap	(	Tuple< T, M, N > &	lhs,
		Tuple< T, M, N > &	rhs
	)

lhs.swap( rhs )

template<class T , int M, int N>

io::DataInput & operator>>	(	io::DataInput &	in,
		Tuple< T, M, N > &	t
	)

Parameters

in	- a data input stream.
t	- the `Tuple` to be extracted from the data input stream.

Returns: in

Precondition: The type T provides a de-serialization operator.

Exceptions

io::IOException - if an I/O error occurs.

template<class T , int M, int N>

io::DataOutput & operator<<	(	io::DataOutput &	out,
		const Tuple< T, M, N > &	t
	)

Parameters

out	- a data output stream.
t	- the `Tuple` to be written to the data output stream.

Returns: out

Precondition: The type T provides a serialization operator.

Exceptions

io::IOException - if an I/O error occurs.

template<class T , int M, int N>

io::TextOutput & operator<<	(	io::TextOutput &	out,
		const Tuple< T, M, N > &	t
	)

Parameters

out	- a text output stream.
t	- the `Tuple` to be printed to the text output stream.

Returns: out

Precondition: The type T provides a text output operator.

Exceptions

io::IOException - if an I/O error occurs.

Member Data Documentation

template<class T, int M, int N = 1>

const int jem::Tuple< T, M, N >::SIZE = M * N

static

The integer constant SIZE equals the total number of elements stored in a tuple.

Public Types

Public Member Functions

Static Public Attributes

Related Functions

Detailed Description

template<class T, int M, int N = 1> class jem::Tuple< T, M, N >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

template<class T, int M, int N = 1>
class jem::Tuple< T, M, N >