IterationPack::IterQuantityAccess< T_info > Class Template Reference

Interface to typed iteration quantities. More...

#include <IterationPack_IterQuantityAccess.hpp>

Inheritance diagram for IterationPack::IterQuantityAccess< T_info >:

Public Types
typedef IterQuantity::NoStorageAvailable	NoStorageAvailable
typedef IterQuantity::QuanityNotSet	QuanityNotSet
Public Types inherited from IterationPack::IterQuantity
enum	{ NONE_UPDATED = INT_MIN }
	Constant for value returned when no iteration quantity has been updated. More...

Public Member Functions
virtual T_info &	get_k (int offset)=0
	Return a reference for the k + offset iteration quanity. More...
virtual const T_info &	get_k (int offset) const =0
	Return a const reference for the k + offset iteration quanity. More...
virtual T_info &	set_k (int offset)=0
	Return a reference to the storage location for the k + offset iteration quanity. More...
virtual T_info &	set_k (int set_offset, int get_offset)=0
	Set the iteration quantity for the k + set_offset iteration to the k + get_offset iteration and return the reference to the k + set_offset iteration quantity. More...
Public Member Functions inherited from IterationPack::IterQuantity
virtual	~IterQuantity ()
virtual IterQuantity *	clone () const =0
virtual const char *	name () const =0
	Return the name (zero terminated string) of this quantity. More...
virtual bool	has_storage_k (int offset) const =0
	Determine if there is storage advailable for the k offset iteration quanity. More...
virtual bool	updated_k (int offset) const =0
	Determine if the quanity for the k offset iteration has been accessed by a call to set_k() (see IterQuantityAccess). More...
virtual int	last_updated () const =0
	Return the highest k such that updated_k(k) returns true. More...
virtual bool	will_loose_mem (int offset, int set_offset) const =0
	Determine if the memory for the k + offset quantityy will be lost if set_k(set_offset) is called (see IterQuantityAccess). More...
virtual void	set_not_updated_k (int offset)=0
	Causes updated_k(k) to return false. More...
virtual void	set_all_not_updated ()=0
	Causes updated_k(k) to return false for all k. More...
virtual void	next_iteration ()=0
	Shift the reference point from the k to the k+1 iteration. More...
virtual void	print_concrete_type (std::ostream &out) const =0
	Print to an output stream a description of this iteration quantity. More...
void	assert_has_storage_k (int offset) const
	Assert has_storage_k(offset) == true (throw NoStorageAvailable). More...
void	assert_updated_k (int offset) const
	Assert updated_k(offset) == true (throw QuanityNotSet). More...

Detailed Description

template<class T_info>
class IterationPack::IterQuantityAccess< T_info >

Interface to typed iteration quantities.

Quantities are updated, read and queried given the offset to the current iteration k. For example, to set a quantity for the k+1 iteration you would call set_k(+1). The functions ending with prefix_k(offset) are meant to suggest prefix k + offset. For example:

has_storage_k(+1) => has storage k+1
get_k(-1) => get k-1

Subclasses can implement this interface in a variety of ways. But they must follow a few simple rules:

• Only forward transitions are allowed. This effects the behavior of IterQuantity::has_storage_k() and set_k().

Note that any type that is to be used as an iteration quantity must at the bare minimum have the assignment operation defined for it.

The client should not have to worry about how much memory is available. Instead, it is for the object that configures the client to provide the appropriate subclass to meet the needs of the client.

Usage:

There are sevearl different techniques for using IterQuantityAccess<T_info>. An implementation subclass for IterQuantityAccess<T_info> will maintain one or more storage locations for iteration quantities that can be updateded and accessed. These storage locations need not be contiguous but this is the most common scenario (see IterQuantityAccessContiguous).

It is important to understand what a client is requesting and what is implied by various calls to get and set methods.

By calling the const version of get_k(offset), the client is expecting to gain read access to previously updated iteration quantity. This quantity should not be modified through this constant reference.

The non-const version of get_k(offset) is called by a client to gain read-write access to a reviously updated iteration quantity. The quantity can be further modified through this non-constant reference.

The method set_k(offset) is called by a client so that it may fully initialize the iteration quantity which may not have been previously updated. The object pointed to by the non-const reference returned from set_k(offset) can not expected to have any more than a default initialization.

Finally, the method set_k(set_offset,get_offset) is called to explicitly update the iteration quantitiy at k + set_offset to the value at iteration k + get_offset. This method is most useful when the client simply wants to set the iteration quantity at the current iteration (set_offset = 0 to its value at the previous iteration (get_offset = -1). The outcome of this operation is insured no matter how the storage is managed by the subclass. The non-const reference returned from this method may be used to futher modify the just updated iteration quantity or the reference can just be discarded.

Definition at line 110 of file IterationPack_IterQuantityAccess.hpp.

Member Typedef Documentation

template<class T_info>

typedef IterQuantity::NoStorageAvailable IterationPack::IterQuantityAccess< T_info >::NoStorageAvailable

Definition at line 114 of file IterationPack_IterQuantityAccess.hpp.

template<class T_info>

typedef IterQuantity::QuanityNotSet IterationPack::IterQuantityAccess< T_info >::QuanityNotSet

Definition at line 116 of file IterationPack_IterQuantityAccess.hpp.

Member Function Documentation

template<class T_info>

virtual T_info& IterationPack::IterQuantityAccess< T_info >::get_k ( int  offset )

pure virtual

Return a reference for the k + offset iteration quanity.

Clients call this member function to access a quantity for a given iteration or modify the quantity which has already been set for that iteration.

Preconditions:

• this->updated_k(offset) == true (throw QuanityNotSet)

Implemented in IterationPack::IterQuantityAccessContiguous< T_info >.

template<class T_info>

virtual const T_info& IterationPack::IterQuantityAccess< T_info >::get_k ( int  offset ) const

pure virtual

Return a const reference for the k + offset iteration quanity.

Preconditions:

• this->updated_k(offset) == true (throw QuanityNotSet)

Clients call this member function to access a const quantity for a given iteration.

Implemented in IterationPack::IterQuantityAccessContiguous< T_info >.

template<class T_info>

virtual T_info& IterationPack::IterQuantityAccess< T_info >::set_k ( int  offset )

pure virtual

Return a reference to the storage location for the k + offset iteration quanity.

Precondtions:

• this->has_storage_k(offset) == true (throw NoStorageAvailable)

Postcondtions:

• this->updated_k(offset) == true
• this->updated_k(i) == false for i>/tt> in the set of { i : this->will_loose_mem(i,offset) == true } before this call.

This function will return a reference to the storage for the k + offset iteration quantity. Calling this function may cause the loss of memory for a back iteration. If will_loose_mem(back_offset,offset) returns true then updated_k(back_offset) will return false after this function returns (assuming an exception is not thrown).

The client should expect nothing more than simple default initialization of the object who's reference is returned from this method. The client is expected to use this reference to initalize this object appropriately. If the client does not sufficiently update the object at k + offset before the reference is let go, the object's reference can be required with a call to the non-const version of get_k(offset).

Implemented in IterationPack::IterQuantityAccessContiguous< T_info >.

template<class T_info>

virtual T_info& IterationPack::IterQuantityAccess< T_info >::set_k ( int  set_offset, int  get_offset  )

pure virtual

Set the iteration quantity for the k + set_offset iteration to the k + get_offset iteration and return the reference to the k + set_offset iteration quantity.

Parameters

set_offset	[in] The iteration offset to be set.
get_offset	[in[ The iteration offset to copy into the k + set_offset iteration.

Precondtions:

• this->has_storage_k(set_offset) == true (throw NoStorageAvailable)
• this->updated_k(get_offset) == true (throw QuanityNotSet)

Postcondtions:

• this->updated_k(set_offset) == true
• this->updated_k(i) == false for i>/tt> in the set of { i : this->will_loose_mem(i,offset) == true } before this call.

This method blends the functionality of the get_k() and the other set_k() methods. This method ensures that a quantity from one iteration (k + get_offset) will be properly and efficienlty copied into the storage location of another iteration (k + set_offset) not matter how storage is handled by the implementing subclass.

Implemented in IterationPack::IterQuantityAccessContiguous< T_info >.

---

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

• IterationPack_IterQuantityAccess.hpp