A safe windowing class that opens onto array-like containers. More...

#include <stencil.hpp>

Public Types
typedef Array::const_iterator	const_iterator
	Uses the array's constant iterator type.
typedef Array::const_reference	const_reference
	Uses the array's element const reference type.
typedef std::reverse_iterator < const_iterator >	const_reverse_iterator
	Uses the array's constant reverse iterator type.
typedef std::ptrdiff_t	difference_type
typedef formatters::StencilFormatter < value_type, Array >	Formatter
typedef Array::iterator	iterator
	Uses the array's iterator type.
typedef Array::reference	reference
	Uses the array's element reference type.
typedef std::reverse_iterator < iterator >	reverse_iterator
	Uses the array's reverse iterator type.
typedef std::size_t	size_type
	Uses the array's type used to denote the length of the array.
typedef Array::value_type	value_type
	Uses the array's element type.
Public Member Functions
reference	at (size_type i) throw (StandardException)
const_reference	at (size_type i) const throw (StandardException)
reference	back () ecl_assert_throw_decl(StandardException)
const_reference	back () const ecl_assert_throw_decl(StandardException)
iterator	begin () ecl_assert_throw_decl(StandardException)
const_iterator	begin () const ecl_assert_throw_decl(StandardException)
iterator	end () ecl_assert_throw_decl(StandardException)
const_iterator	end () const ecl_assert_throw_decl(StandardException)
reference	front () ecl_assert_throw_decl(StandardException)
const_reference	front () const ecl_assert_throw_decl(StandardException)
containers::BoundedListInitialiser < value_type, value_type * >	operator<< (const value_type &value)
Stencil< Array > &	operator= (const Stencil< Array > &s) ecl_assert_throw_decl(StandardException)
	This either resettles this stencil or copies across to it (depending on the rhs stencil).
reference	operator[] (size_type i) ecl_assert_throw_decl(StandardException)
const_reference	operator[] (size_type i) const ecl_assert_throw_decl(StandardException)
reverse_iterator	rbegin () ecl_assert_throw_decl(StandardException)
const_reverse_iterator	rbegin () const ecl_assert_throw_decl(StandardException)
reverse_iterator	rend () ecl_assert_throw_decl(StandardException)
const_reverse_iterator	rend () const ecl_assert_throw_decl(StandardException)
void	resettle (const unsigned int &start_index, const unsigned int &n) ecl_assert_throw_decl(StandardException)
	Resettle the stencil on a different range over the same underlying array.
size_type	size () const
	Stencil (Array &underlying_array, iterator begin_iter, iterator end_iter) ecl_assert_throw_decl(StandardException)
	Initialises with a reference to the underlying container and boundary constraints.
	Stencil (Array &underlying_array, const unsigned int &start_index=0, const unsigned int &n=0) ecl_assert_throw_decl(StandardException)
	Initialises with a reference to the underlying container and boundary constraints.
Stencil< Array >	stencil (const unsigned int &start_index, const unsigned int &n) const ecl_assert_throw_decl(StandardException)
	Generate a sub-stencil.
virtual	~Stencil ()
Private Attributes
Array &	array
iterator	b_iter
iterator	e_iter
Friends
template<typename OutputStream , typename ArrayType >
OutputStream &	operator<< (OutputStream &ostream, const Stencil< ArrayType > &stencil)
	Insertion operator for stencils.

Detailed Description

template<typename Array>
class ecl::Stencil< Array >

A safe windowing class that opens onto array-like containers.

Functions often require access to just a portion of an array. In these cases pointers are typically used, but these end up being dangerous alot of times. The underlying array may disappear, or its size may change and the resulting pointers are left dangling, pointing at rubbish.

This class allows such an operation to be performed with two additional benefits:

It provides additional container like functionality.
Users references and range checking to ensure critical problems cannot arise.

Currently this works with anything that measures up to the ecl concept of a container.

Usage:

 typedef Array<int,5> FixedArray;
 typedef Stencil< FixedArray > FixedStencil;

 FixedArray array;
 array << 1,2,3,4,5;
 FixedStencil stencil(array,1,3); // windows from index 1 to 3
 std::cout << stencil[1] << std::endl; // accesses array[2];

See also:: ecl::ContainerConcept, ecl::Array.

Definition at line 72 of file stencil/stencil.hpp.

Member Typedef Documentation

template<typename Array>

typedef Array::const_iterator ecl::Stencil< Array >::const_iterator

Uses the array's constant iterator type.

Definition at line 82 of file stencil/stencil.hpp.

template<typename Array>

typedef Array::const_reference ecl::Stencil< Array >::const_reference

Uses the array's element const reference type.

Definition at line 84 of file stencil/stencil.hpp.

template<typename Array>

typedef std::reverse_iterator<const_iterator> ecl::Stencil< Array >::const_reverse_iterator

Uses the array's constant reverse iterator type.

Definition at line 92 of file stencil/stencil.hpp.

template<typename Array>

typedef std::ptrdiff_t ecl::Stencil< Array >::difference_type

Definition at line 90 of file stencil/stencil.hpp.

template<typename Array>

typedef formatters::StencilFormatter<value_type,Array> ecl::Stencil< Array >::Formatter

Definition at line 93 of file stencil/stencil.hpp.

template<typename Array>

typedef Array::iterator ecl::Stencil< Array >::iterator

Uses the array's iterator type.

Definition at line 81 of file stencil/stencil.hpp.

template<typename Array>

typedef Array::reference ecl::Stencil< Array >::reference

Uses the array's element reference type.

Definition at line 83 of file stencil/stencil.hpp.

template<typename Array>

typedef std::reverse_iterator<iterator> ecl::Stencil< Array >::reverse_iterator

Uses the array's reverse iterator type.

Definition at line 91 of file stencil/stencil.hpp.

template<typename Array>

typedef std::size_t ecl::Stencil< Array >::size_type

Uses the array's type used to denote the length of the array.

Definition at line 89 of file stencil/stencil.hpp.

template<typename Array>

typedef Array::value_type ecl::Stencil< Array >::value_type

Uses the array's element type.

Definition at line 78 of file stencil/stencil.hpp.

Constructor & Destructor Documentation

template<typename Array>

ecl::Stencil< Array >::Stencil	(	Array &	underlying_array,
		iterator	begin_iter,
		iterator	end_iter
	)		`[inline]`

Initialises with a reference to the underlying container and boundary constraints.

Sets up the underlying storage container along with boundary constraints in the style of stl containers.

Concept Check: makes sure the template parameter provided for the class is a container type with the required functionality.

Parameters:

underlying_array	: reference to the underlying array.
begin_iter	: start of the stencil window.
end_iter	: end of the stencil window.

Exceptions:

:	StandardException : throws if the indices provided are out of range [debug mode only].

Definition at line 113 of file stencil/stencil.hpp.

template<typename Array>

ecl::Stencil< Array >::Stencil	(	Array &	underlying_array,
		const unsigned int &	start_index = `0`,
		const unsigned int &	n = `0`
	)		`[inline]`

Initialises with a reference to the underlying container and boundary constraints.

Sets up the underlying storage container along with boundary constraints in the style of eigen block intialisations.

Concept Check: makes sure the template parameter provided for the class is a container type with the required functionality.

Parameters:

underlying_array	: reference to the underlying array.
start_index	: start of the stencil window.
n	: number of elements to include in the window.

Exceptions:

:	StandardException : throws if the indices provided are out of range [debug mode only].

Definition at line 138 of file stencil/stencil.hpp.

template<typename Array>

virtual ecl::Stencil< Array >::~Stencil ( ) [inline, virtual]

Definition at line 148 of file stencil/stencil.hpp.

Member Function Documentation

template<typename Array>

reference ecl::Stencil< Array >::at ( size_type i ) throw (StandardException) [inline]

Accesses elements in the stencil, returning references to the requested element. This accessor always does range checks. Compare this with the [] accessor which only checks if NDEBUG is not defined.

Parameters:

i	: the index of the requested element.

Returns:: reference : a reference to the requested element.

Exceptions:

:	StandardException : throws if range is requested element is out of range.

Definition at line 431 of file stencil/stencil.hpp.

template<typename Array>

const_reference ecl::Stencil< Array >::at ( size_type i ) const throw (StandardException) [inline]

Accesses elements in the stencil, returning references to the requested element. This accessor always does range checks. Compare this with the [] accessor which only checks if NDEBUG is not defined. This also ensures the references are constant, which in turn ensures the contents cannot of the array cannot be modified.

Parameters:

i	: the index of the requested element.

Returns:: const_reference : a const_reference to the requested element.

Exceptions:

:	StandardException : throws if range is requested element is out of range.

Definition at line 455 of file stencil/stencil.hpp.

template<typename Array>

reference ecl::Stencil< Array >::back ( ) [inline]

Generates an reference to the last element in the array.

Returns:: reference : reference to the last element in the array.

Exceptions:

:	StandardException : throws if the underlying array changed size and the stencil is now out of range [debug mode only].

Definition at line 370 of file stencil/stencil.hpp.

template<typename Array>

const_reference ecl::Stencil< Array >::back ( ) const [inline]

Generates a constant reference to the last element in the array (cannot change the value).

Returns:: const_reference : const_reference to the last element in the array.

Exceptions:

:	StandardException : throws if the underlying array changed size and the stencil is now out of range [debug mode only].

Definition at line 380 of file stencil/stencil.hpp.

template<typename Array>

iterator ecl::Stencil< Array >::begin ( ) [inline]

Generates a pointer (iterator) pointing to the start of the stencil.

Returns:: iterator : points to the beginning of the stencil.

Exceptions:

:	StandardException : throws if the underlying array changed size and the stencil is now out of range [debug mode only].

Definition at line 266 of file stencil/stencil.hpp.

template<typename Array>

const_iterator ecl::Stencil< Array >::begin ( ) const [inline]

Generates a const pointer (iterator) pointing to the start of the array.

Returns:: const_iterator : constant pointer (iterator) pointing to the end of the array.

Exceptions:

:	StandardException : throws if the underlying array changed size and the stencil is now out of range [debug mode only].

Definition at line 276 of file stencil/stencil.hpp.

template<typename Array>

iterator ecl::Stencil< Array >::end ( ) [inline]

Generates an pointer (iterator) pointing to the end of the array.

Returns:: iterator : points to the end of the array.

Exceptions:

:	StandardException : throws if the underlying array changed size and the stencil is now out of range [debug mode only].

Definition at line 286 of file stencil/stencil.hpp.

template<typename Array>

const_iterator ecl::Stencil< Array >::end ( ) const [inline]

Generates a const pointer (iterator) pointing to the end of the array.

Returns:: const_iterator : constant pointer (iterator) pointing to the end of the array.

Exceptions:

:	StandardException : throws if the underlying array changed size and the stencil is now out of range [debug mode only].

Definition at line 296 of file stencil/stencil.hpp.

template<typename Array>

reference ecl::Stencil< Array >::front ( ) [inline]

Generates an reference to the first element in the array.

Returns:: reference : reference to the first element in the array.

Exceptions:

:	StandardException : throws if the underlying array changed size and the stencil is now out of range [debug mode only].

Definition at line 350 of file stencil/stencil.hpp.

template<typename Array>

const_reference ecl::Stencil< Array >::front ( ) const [inline]

Generates a constant reference to the first element in the array (cannot change the value).

Returns:: const_reference : const_reference to the first element in the array.

Exceptions:

:	StandardException : throws if the underlying array changed size and the stencil is now out of range [debug mode only].

Definition at line 360 of file stencil/stencil.hpp.

template<typename Array>

containers::BoundedListInitialiser<value_type,value_type*> ecl::Stencil< Array >::operator<< ( const value_type & value ) [inline]

Provides a comma initialisation facility. This initiates the comma initialiser with an iterator to the underlying array and then leaves the initialiser to do the rest. The initialiser will do range checking if NDEBUG is not defined.

 Array<int,4> array; // At this point it is uninitialised.
 array << 1,2,3,4;    // If NDEBUG is not defined, this will throw if you exceed the range.

Parameters:

value : the first value to enter , ElementType, ArraySizeinto the array.

Returns:: BoundedListInitialiser : the comma initialiser mechanism.

Definition at line 206 of file stencil/stencil.hpp.

template<typename Array>

Stencil<Array>& ecl::Stencil< Array >::operator= ( const Stencil< Array > & s ) [inline]

This either resettles this stencil or copies across to it (depending on the rhs stencil).

The assignment operator has one of two effects - it will either reassign this stencil if both stencils work on the same underlying array, OR it copies across if acting on two different arrays.

Usage:

The first case, resettling:

 Array<char> array(5); array << 1,2,3,4,5;
 Stencil< Array<char> > stencil = array.stencil(1,2);
 stencil = array.stencil(0,3); // Here we can repeat the reassignment

The second case, copying:

 Array<char> array1(5); array1 << 1,2,3,4,5;
 Array<char> array2(6); array2 << 1,2,3,4,5,6;
 Stencil< Array<char> > stencil = array1.stencil(1,2);
 stencil = array2.stencil(2,2); // Here we just flood fill the stencil - make sure the capacity is sufficient!

Parameters:

s

Returns:: Stencil<Array> : a handle to this stencil

Exceptions:

:	StandardException : if copying from another stencil/array, throws if size exceeded [debug mode only].

Definition at line 240 of file stencil/stencil.hpp.

template<typename Array>

reference ecl::Stencil< Array >::operator[] ( size_type i ) [inline]

Accesses elements in the stencil, returning references to the requested element. This accessor only does range checks in debug mode (NDEBUG is not defined). Compare this with the at() accessor which always checks if the range is exceeded.

Returns:: reference : a reference to the requested element.

Exceptions:

:	StandardException : throws if range is requested element is out of range [debug mode only].

Definition at line 398 of file stencil/stencil.hpp.

template<typename Array>

const_reference ecl::Stencil< Array >::operator[] ( size_type i ) const [inline]

Accesses elements in the stencil, returning references to the requested element. This accessor only does range checks in debug mode (NDEBUG is not defined). Compare this with the at() accessor which always checks if the range is exceeded. This also ensures the references are constant, which in turn ensures the contents cannot of the array cannot be modified.

Returns:: const_reference : a constant reference to the requested element.

Exceptions:

:	StandardException : throws if range is requested element is out of range [debug mode only].

Definition at line 415 of file stencil/stencil.hpp.

template<typename Array>

reverse_iterator ecl::Stencil< Array >::rbegin ( ) [inline]

Generates a reverse iterator pointing to the end of the array.

Returns:: reverse_iterator : points to the end of the array.

Exceptions:

:	StandardException : throws if the underlying array changed size and the stencil is now out of range [debug mode only].

Definition at line 306 of file stencil/stencil.hpp.

template<typename Array>

const_reverse_iterator ecl::Stencil< Array >::rbegin ( ) const [inline]

Generates a constant reverse iterator pointing to the end of the array.

Returns:: const_reverse_iterator : constant reverse iterator pointing to the end of the array.

Exceptions:

:	StandardException : throws if the underlying array changed size and the stencil is now out of range [debug mode only].

Definition at line 316 of file stencil/stencil.hpp.

template<typename Array>

reverse_iterator ecl::Stencil< Array >::rend ( ) [inline]

Generates a reverse iterator pointing to the beginning of the array.

Returns:: reverse_iterator : points to the beginning of the array.

Exceptions:

:	StandardException : throws if the underlying array changed size and the stencil is now out of range [debug mode only].

Definition at line 326 of file stencil/stencil.hpp.

template<typename Array>

const_reverse_iterator ecl::Stencil< Array >::rend ( ) const [inline]

Generates a constant reverse iterator pointing to the beginning of the array.

Returns:: const_reverse_iterator : constant reverse iterator pointing to the beginning of the array.

Exceptions:

:	StandardException : throws if the underlying array changed size and the stencil is now out of range [debug mode only].

Definition at line 336 of file stencil/stencil.hpp.

template<typename Array>

void ecl::Stencil< Array >::resettle	(	const unsigned int &	start_index,
		const unsigned int &	n
	)		`[inline]`

Resettle the stencil on a different range over the same underlying array.

Resets the range of the stencil operating on the currently referenced array. Using a starting index + size is in line with the way eigen blocks and segments work.

Parameters:

start_index	: start of the stencil window.
n	: number of elements to include in the window.

Exceptions:

:	StandardException : throws if the indices provided are out of range [debug mode only].

Definition at line 181 of file stencil/stencil.hpp.

template<typename Array>

size_type ecl::Stencil< Array >::size ( ) const [inline]

The size of the stencil.

Returns:: size_type : the size of the stencil.

Definition at line 476 of file stencil/stencil.hpp.

template<typename Array>

Stencil<Array> ecl::Stencil< Array >::stencil	(	const unsigned int &	start_index,
		const unsigned int &	n
	)		const `[inline]`

Generate a sub-stencil.

Opens another window on this stencil. Using a starting index + size is in line with the way eigen blocks and segments work.

Parameters:

start_index	: start of the stencil window.
n	: number of elements to include in the window.

Returns:: Stencil<Array> : the generated sub-stencil.

Exceptions:

:	StandardException : throws if the indices provided are out of range [debug mode only].

Definition at line 163 of file stencil/stencil.hpp.

Friends And Related Function Documentation

template<typename Array>

template<typename OutputStream , typename ArrayType >

OutputStream& operator<<	(	OutputStream &	ostream,
		const Stencil< ArrayType > &	stencil
	)		`[friend]`

Insertion operator for stencils.

Insertion operator for sending the stencil to an output stream. This is raw, and has no formatting.

Concept Check: makes sure the template parameter provided for the stream is a stream type with the required functionality.

Parameters:

ostream	: the output stream.
stencil	: the stencil to be inserted.

Template Parameters:

OutputStream	: the stream being used.
ArrayType	: the type of the underlying array.

Returns:: OutputStream : continue streaming with the updated output stream.

Definition at line 510 of file stencil/stencil.hpp.

Member Data Documentation

template<typename Array>

Array& ecl::Stencil< Array >::array [private]

Definition at line 501 of file stencil/stencil.hpp.

template<typename Array>

iterator ecl::Stencil< Array >::b_iter [private]

Definition at line 502 of file stencil/stencil.hpp.

template<typename Array>

iterator ecl::Stencil< Array >::e_iter [private]

Definition at line 502 of file stencil/stencil.hpp.

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

stencil/stencil.hpp

Public Types

Public Member Functions

Private Attributes

Friends

Detailed Description

template<typename Array> class ecl::Stencil< Array >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

template<typename Array>
class ecl::Stencil< Array >