path: root/src/jtutil/array.hh

// array.hh -- array template classes
// $Id$
//
// array1d - 1D array template
// array2d - 2D array template
// array3d - 3D array template
// array4d - 4D array template
//

//
// prerequisites:
//    <assert.h>
//    "jt/stdc.h"
//    "jt/util++.h"	// for jtutil::how_many_in_range()
//

//
// The templates defined in this file represent n-dimensional row-major
// contiguous arrays, parameterized by the data type (most commonly float
// or double, but could also be bool, int, long double, ...).  These
// arrays cannot be copied or passed to functions by value; use pass
// by reference instead.
//
// Stroustrup ("The C++ Programming Language", 3rd edition, appendix C.7)
// suggests the use of STL vectors of STL vectors to provide multidimensional
// arrays.  However, those "arrays" aren't contiguous in memory, so the
// compiler can't do strength reduction on any but the last subscript
// when the arrays are accessed in a loop.  In contrast, the arrays
// defined here are contiguous, and all subscripts can (should, if the
// compiler is good) be strength-reduced.
//
// The STL valarray templates offer a superset of the functionality of
// these templates, but they've only recently been provided with gcc;
// at some time in the future I may migrate these classes to become
// valarray wrappers.
//

#ifndef NDEBUG
//
// Full bounds checking is done on all array accesses.
//
#endif

//******************************************************************************

namespace jtutil
	  {
template <class fpt>
class	array1d
	{
public:
	// array info
	int min_i() const { return min_i_; }
	int max_i() const { return max_i_; }
	int N_i() const { return jtutil::how_many_in_range(min_i_, max_i_); }
	bool is_valid_i(int i) const { return (i >= min_i_) && (i <= max_i_); }
	bool is_valid_subscript(int i) const { return is_valid_i(i); }

	// normal-use access functions
	// ... rvalue
	fpt operator()(int i) const
		{
		assert( is_valid_subscript(i) );
		return array_[i - min_i_];
		}
	// ... lvalue
	fpt& operator()(int i)
		{
		assert( is_valid_subscript(i) );
		return array_[i - min_i_];
		}

	// get access to internal 0-origin 1D storage array
	// (low-level, dangerous, use with caution!)
	int N_array() const { return N_i(); }
	fpt* get_array() const { return array_; }

	// constructor, destructor
	// newly-constructed array elements are initialized to fpt(0)
	array1d(int min_i_in, int max_i_in);
	~array1d();

private:
	// we forbid copying and passing by value
	// by declaring the copy constructor and assignment operator
	// private, but never defining them
	array1d(const array1d<fpt>& rhs);
	array1d<fpt>& operator=(const array1d<fpt>& rhs);

private:
	// note we declare the array pointer first in the class
	// ==> it's probably at 0 offset
	// ==> we may get slightly faster array access
	fpt* array_;		// --> new-allocated 1D storage array

	// min/max array bounds
	const int min_i_, max_i_;
	};
	  };	// close namespace jtutil::

//******************************************************************************

namespace jtutil
	  {
template <class fpt>
class	array2d
	{
public:
	// array info
	int min_i() const { return min_i_; }
	int max_i() const { return max_i_; }
	int min_j() const { return min_j_; }
	int max_j() const { return max_j_; }
	int N_i() const { return jtutil::how_many_in_range(min_i_, max_i_); }
	int N_j() const { return jtutil::how_many_in_range(min_j_, max_j_); }
	bool is_valid_i(int i) const { return (i >= min_i_) && (i <= max_i_); }
	bool is_valid_j(int j) const { return (j >= min_j_) && (j <= max_j_); }
	bool is_valid_subscript(int i, int j) const
		{ return is_valid_i(i) && is_valid_j(j); }

	// subscripting functions
	// (low-level, dangerous, use with caution!)
	// FIXME: should we also provide the reverse mapping, i.e.
	//        subscript --> (i,j) ?
	int subscript_unchecked(int i, int j) const
		{ return offset_ + stride_i_*i + j; }
	int subscript(int i, int j) const
		{
		assert( is_valid_subscript(i,j) );
		const int posn = subscript_unchecked(i,j);
		// we want each assert() here to be on a separate source line,
		// so assert() failure message can pinpoint which index is bad
		assert(posn >= 0);
		assert(posn <= N_array_);
		return posn;
		}

	// normal-use access functions
	// ... rvalue
	fpt  operator()(int i, int j) const
		{ return array_[ subscript(i,j) ]; }
	// ... lvalue
	fpt& operator()(int i, int j)
		{ return array_[ subscript(i,j) ]; }

	// get access to internal 0-origin 1D storage array
	// (low-level, dangerous, use with caution!)
	int N_array() const { return N_array_; }
	fpt* get_array() const { return array_; }

	// constructor, destructor
	// newly-constructed array elements are initialized to fpt(0)
	array2d(int min_i_in, int max_i_in,
		int min_j_in, int max_j_in);
	~array2d();

private:
	// we forbid copying and passing by value
	// by declaring the copy constructor and assignment operator
	// private, but never defining them
	array2d(const array2d<fpt>& rhs);
	array2d<fpt>& operator=(const array2d<fpt>& rhs);

private:
	// note we declare the array pointer first in the class
	// ==> it's probably at 0 offset
	// ==> we may get slightly faster array access
	fpt* array_;		// --> new-allocated 1D storage array
	int N_array_;

	// subscripting info
	int offset_, stride_i_;

	// min/max array bounds
	const int min_i_, max_i_;
	const int min_j_, max_j_;
	};
	  };	// close namespace jtutil::

//******************************************************************************

namespace jtutil
	  {
template <class fpt>
class	array3d
	{
public:
	// array info
	int min_i() const { return min_i_; }
	int max_i() const { return max_i_; }
	int min_j() const { return min_j_; }
	int max_j() const { return max_j_; }
	int min_k() const { return min_k_; }
	int max_k() const { return max_k_; }
	int N_i() const { return jtutil::how_many_in_range(min_i_, max_i_); }
	int N_j() const { return jtutil::how_many_in_range(min_j_, max_j_); }
	int N_k() const { return jtutil::how_many_in_range(min_k_, max_k_); }
	bool is_valid_i(int i) const { return (i >= min_i_) && (i <= max_i_); }
	bool is_valid_j(int j) const { return (j >= min_j_) && (j <= max_j_); }
	bool is_valid_k(int k) const { return (k >= min_k_) && (k <= max_k_); }
	bool is_valid_subscript(int i, int j, int k) const
		{ return is_valid_i(i) && is_valid_j(j) && is_valid_k(k); }

	// subscripting functions
	// (low-level, dangerous, use with caution!)
	// FIXME: should we also provide the reverse mapping, i.e.
	//        subscript --> (i,j,k) ?
	int subscript_unchecked(int i, int j, int k) const
		{ return offset_ + stride_i_*i + stride_j_*j + k; }
	int subscript(int i, int j, int k) const
		{
		assert( is_valid_subscript(i,j,k) );
		const int posn = subscript_unchecked(i,j,k);
		// we want each assert() here to be on a separate source line,
		// so assert() failure message can pinpoint which index is bad
		assert(posn >= 0);
		assert(posn <= N_array_);
		return posn;
		}

	// normal-use access functions
	// ... rvalue
	fpt  operator()(int i, int j, int k) const
		{ return array_[ subscript(i,j,k) ]; }
	// ... lvalue
	fpt& operator()(int i, int j, int k)
		{ return array_[ subscript(i,j,k) ]; }

	// get access to internal 0-origin 1D storage array
	// (low-level, dangerous, use with caution!)
	int N_array() const { return N_array_; }
	fpt* get_array() const { return array_; }

	// constructor, destructor
	// newly-constructed array elements are initialized to fpt(0)
	array3d(int min_i_in, int max_i_in,
		int min_j_in, int max_j_in,
		int min_k_in, int max_k_in);
	~array3d();

private:
	// we forbid copying and passing by value
	// by declaring the copy constructor and assignment operator
	// private, but never defining them
	array3d(const array3d<fpt>& rhs);
	array3d<fpt>& operator=(const array3d<fpt>& rhs);

private:
	// note we declare the array pointer first in the class
	// ==> it's probably at 0 offset
	// ==> we may get slightly faster array access
	fpt* array_;		// --> new-allocated 1D storage array
	int N_array_;

	// subscripting info
	int offset_, stride_i_, stride_j_;

	// min/max array bounds
	const int min_i_, max_i_;
	const int min_j_, max_j_;
	const int min_k_, max_k_;
	};
	  };	// close namespace jtutil::

//******************************************************************************

namespace jtutil
	  {
template <class fpt>
class	array4d
	{
public:
	// array info
	int min_i() const { return min_i_; }
	int max_i() const { return max_i_; }
	int min_j() const { return min_j_; }
	int max_j() const { return max_j_; }
	int min_k() const { return min_k_; }
	int max_k() const { return max_k_; }
	int min_l() const { return min_l_; }
	int max_l() const { return max_l_; }
	int N_i() const { return jtutil::how_many_in_range(min_i_, max_i_); }
	int N_j() const { return jtutil::how_many_in_range(min_j_, max_j_); }
	int N_k() const { return jtutil::how_many_in_range(min_k_, max_k_); }
	int N_l() const { return jtutil::how_many_in_range(min_l_, max_l_); }
	bool is_valid_i(int i) const { return (i >= min_i_) && (i <= max_i_); }
	bool is_valid_j(int j) const { return (j >= min_j_) && (j <= max_j_); }
	bool is_valid_k(int k) const { return (k >= min_k_) && (k <= max_k_); }
	bool is_valid_l(int l) const { return (l >= min_l_) && (l <= max_l_); }
	bool is_valid_subscript(int i, int j, int k, int l)
		const
		{
		return    is_valid_i(i) && is_valid_j(j)
		       && is_valid_k(k) && is_valid_l(l);
		}

	// subscripting functions
	// (low-level, dangerous, use with caution!)
	// FIXME: should we also provide the reverse mapping, i.e.
	//        subscript --> (i,j,k,l) ?
	int subscript_unchecked(int i, int j, int k, int l) const
		{
		return offset_ + stride_i_*i + stride_j_*j + stride_k_*k + l;
		}
	int subscript(int i, int j, int k, int l) const
		{
		assert( is_valid_subscript(i,j,k,l) );
		const int posn = subscript_unchecked(i,j,k,l);
		// we want each assert() here to be on a separate source line,
		// so assert() failure message can pinpoint which index is bad
		assert(posn >= 0);
		assert(posn <= N_array_);
		return posn;
		}

	// normal-use access functions
	// ... rvalue
	fpt  operator()(int i, int j, int k, int l) const
		{ return array_[ subscript(i,j,k,l) ]; }
	// ... lvalue
	fpt& operator()(int i, int j, int k, int l)
		{ return array_[ subscript(i,j,k,l) ]; }

	// get access to internal 0-origin 1D storage array
	// (low-level, dangerous, use with caution!)
	int N_array() const { return N_array_; }
	fpt* get_array() const { return array_; }

	// constructor, destructor
	// newly-constructed array elements are initialized to fpt(0)
	array4d(int min_i_in, int max_i_in,
		int min_j_in, int max_j_in,
		int min_k_in, int max_k_in,
		int min_l_in, int max_l_in);
	~array4d();

private:
	// we forbid copying and passing by value
	// by declaring the copy constructor and assignment operator
	// private, but never defining them
	array4d(const array4d<fpt>& rhs);
	array4d<fpt>& operator=(const array4d<fpt>& rhs);

private:
	// note we declare the array pointer first in the class
	// ==> it's probably at 0 offset
	// ==> we may get slightly faster array access
	fpt* array_;		// --> new-allocated 1D storage array
	int N_array_;

	// subscripting info
	int offset_, stride_i_, stride_j_, stride_k_;

	// min/max array bounds
	const int min_i_, max_i_;
	const int min_j_, max_j_;
	const int min_k_, max_k_;
	const int min_l_, max_l_;
	};
	  };	// close namespace jtutil::