Public Types | Public Member Functions | Private Attributes | Friends | List of all members
ecl::Stencil< Array > Class Template Reference

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

#include <formatters.hpp>

Public Types

typedef Array::const_iterator const_iterator
 Uses the array's constant iterator type. More...
 
typedef Array::const_reference const_reference
 Uses the array's element const reference type. More...
 
typedef std::reverse_iterator< const_iteratorconst_reverse_iterator
 Uses the array's constant reverse iterator type. More...
 
typedef std::ptrdiff_t difference_type
 
typedef formatters::StencilFormatter< value_type, ArrayFormatter
 
typedef Array::iterator iterator
 Uses the array's iterator type. More...
 
typedef Array::reference reference
 Uses the array's element reference type. More...
 
typedef std::reverse_iterator< iteratorreverse_iterator
 Uses the array's reverse iterator type. More...
 
typedef std::size_t size_type
 Uses the array's type used to denote the length of the array. More...
 
typedef Array::value_type value_type
 Uses the array's element type. More...
 

Public Member Functions

reference at (size_type i)
 
const_reference at (size_type i) const
 
reference back ()
 
const_reference back () const
 
iterator begin ()
 
const_iterator begin () const
 
iterator end ()
 
const_iterator end () const
 
reference front ()
 
const_reference front () const
 
containers::BoundedListInitialiser< value_type, value_type * > operator<< (const value_type &value)
 
Stencil< Array > & operator= (const Stencil< Array > &s)
 This either resettles this stencil or copies across to it (depending on the rhs stencil). More...
 
reference operator[] (size_type i)
 
const_reference operator[] (size_type i) const
 
reverse_iterator rbegin ()
 
const_reverse_iterator rbegin () const
 
reverse_iterator rend ()
 
const_reverse_iterator rend () const
 
void resettle (const unsigned int &start_index, const unsigned int &n)
 Resettle the stencil on a different range over the same underlying array. More...
 
size_type size () const
 
 Stencil (Array &underlying_array, const unsigned int &start_index=0, const unsigned int &n=0)
 Initialises with a reference to the underlying container and boundary constraints. More...
 
 Stencil (Array &underlying_array, iterator begin_iter, iterator end_iter)
 Initialises with a reference to the underlying container and boundary constraints. More...
 
Stencil< Arraystencil (const unsigned int &start_index, const unsigned int &n) const
 Generate a sub-stencil. More...
 
virtual ~Stencil ()
 

Private Attributes

Arrayarray
 
iterator b_iter
 
iterator e_iter
 

Friends

template<typename OutputStream , typename ArrayType >
OutputStream & operator<< (OutputStream &ostream, const Stencil< ArrayType > &stencil)
 Insertion operator for stencils. More...
 

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:

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 46 of file stencil/formatters.hpp.

Member Typedef Documentation

◆ const_iterator

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

Uses the array's constant iterator type.

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

◆ const_reference

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

Uses the array's element const reference type.

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

◆ const_reverse_iterator

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 106 of file stencil/stencil.hpp.

◆ difference_type

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

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

◆ Formatter

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

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

◆ iterator

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

Uses the array's iterator type.

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

◆ reference

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

Uses the array's element reference type.

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

◆ reverse_iterator

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

Uses the array's reverse iterator type.

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

◆ size_type

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 103 of file stencil/stencil.hpp.

◆ value_type

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

Uses the array's element type.

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

Constructor & Destructor Documentation

◆ Stencil() [1/2]

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 127 of file stencil/stencil.hpp.

◆ Stencil() [2/2]

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 152 of file stencil/stencil.hpp.

◆ ~Stencil()

template<typename Array >
virtual ecl::Stencil< Array >::~Stencil ( )
inlinevirtual

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

Member Function Documentation

◆ at() [1/2]

template<typename Array >
reference ecl::Stencil< Array >::at ( size_type  i)
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 445 of file stencil/stencil.hpp.

◆ at() [2/2]

template<typename Array >
const_reference ecl::Stencil< Array >::at ( size_type  i) const
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 469 of file stencil/stencil.hpp.

◆ back() [1/2]

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 384 of file stencil/stencil.hpp.

◆ back() [2/2]

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 394 of file stencil/stencil.hpp.

◆ begin() [1/2]

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 280 of file stencil/stencil.hpp.

◆ begin() [2/2]

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 290 of file stencil/stencil.hpp.

◆ end() [1/2]

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 300 of file stencil/stencil.hpp.

◆ end() [2/2]

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 310 of file stencil/stencil.hpp.

◆ front() [1/2]

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 364 of file stencil/stencil.hpp.

◆ front() [2/2]

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 374 of file stencil/stencil.hpp.

◆ operator<<()

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 220 of file stencil/stencil.hpp.

◆ operator=()

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 254 of file stencil/stencil.hpp.

◆ operator[]() [1/2]

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 412 of file stencil/stencil.hpp.

◆ operator[]() [2/2]

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 429 of file stencil/stencil.hpp.

◆ rbegin() [1/2]

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 320 of file stencil/stencil.hpp.

◆ rbegin() [2/2]

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 330 of file stencil/stencil.hpp.

◆ rend() [1/2]

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 340 of file stencil/stencil.hpp.

◆ rend() [2/2]

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 350 of file stencil/stencil.hpp.

◆ resettle()

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 195 of file stencil/stencil.hpp.

◆ size()

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 490 of file stencil/stencil.hpp.

◆ stencil()

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 177 of file stencil/stencil.hpp.

Friends And Related Function Documentation

◆ operator<<

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 516 of file stencil/stencil.hpp.

Member Data Documentation

◆ array

template<typename Array >
Array& ecl::Stencil< Array >::array
private

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

◆ b_iter

template<typename Array >
iterator ecl::Stencil< Array >::b_iter
private

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

◆ e_iter

template<typename Array >
iterator ecl::Stencil< Array >::e_iter
private

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


The documentation for this class was generated from the following files:
ecl::Stencil::stencil
Stencil< Array > stencil(const unsigned int &start_index, const unsigned int &n) const
Generate a sub-stencil.
Definition: stencil/stencil.hpp:177
ecl::Stencil
A safe windowing class that opens onto array-like containers.
Definition: stencil/formatters.hpp:46
ecl::Array::stencil
Stencil< Array< Type, Size > > stencil(const unsigned int &start_index, const unsigned int &n)
Open a window (stencil) onto the array.
Definition: array_no_mem_check.hpp:271
FixedStencil
Stencil< Array< int, 5 > > FixedStencil
Definition: stencil.cpp:44
ecl::Stencil::array
Array & array
Definition: stencil/stencil.hpp:515


ecl_containers
Author(s): Daniel Stonier
autogenerated on Sun Aug 2 2020 03:12:14