An Aggregate implements a Parameter that is a list of Parameters. More...

#include <Parameter.hh>

Inheritance diagram for Aggregate:

Collaboration diagram for Aggregate:

Classes
class	Depth_Iterator
	A Depth_Iterator is a bidirectional iterator over an Aggregate's Parameter list and, depth-first, over the Parameter list of each Aggregate encountered. More...
Public Types
enum	{ CASE_INSENSITIVE, CASE_SENSITIVE }
	Flags for find case sensitivity argument. More...
typedef Parameter_List::const_iterator	const_iterator
	Identify the iterator for compilers that need help.
typedef Depth_Iterator	depth_iterator
	A specialized iterator that descends into Aggregates in the Parameter list.
typedef Parameter_List::iterator	iterator
	Identify the iterator for compilers that need help.
typedef Vectal< Parameter >	Parameter_List
	Aggregate as a Vectal (vector) of Parameters.
Public Member Functions
Aggregate &	add (const Parameter &parameter)
	Adds a clone of the Parameter to the end of the Aggregate's Parameter list.
Aggregate &	add (Parameter *parameter)
	Adds the Parameter to the end of the Aggregate's Parameter list.
	Aggregate (const Aggregate &aggregate)
	Copy constructor.
	Aggregate (Parser &parser, const std::string name="")
	Constructs an Aggregate using a Parser to provide its contents.
	Aggregate (const std::string name="", const idaeim::PVL::Parameter::Type type_code=Default_Subtype)
	Constructs an empty Aggregate.
	Aggregate (const Parameter &parameter)
	Copy constructor from a Parameter.
Depth_Iterator	begin_depth ()
	Gets a Depth_Iterator positioned at the beginning of this Aggregate.
Aggregate *	clone () const
	Clones the Aggregate by making a copy of itself.
int	compare (const Parameter &parameter) const
	Compares this Aggregate with another Parameter.
Aggregate &	copy_in (const Aggregate &aggregate)
	Copies the Parameter list in an Aggregate into this Aggregate's list.
Depth_Iterator	end_depth ()
	Gets a Depth_Iterator positioned at the end of this Aggregate.
void	entering (Parameter *parameter)
	Sets the parent of a Parameter to this Aggregate.
Parameter *	find (const std::string &pathname, bool case_sensitive=false, int skip=0, idaeim::PVL::Parameter::Type type=(Type)(ASSIGNMENT\|AGGREGATE)) const
	Find a named Parameter.
bool	is (const Type type) const
	Test if the Parameter is of some Type.
bool	is_Aggregate () const
	Test if this is an Aggregate.
bool	is_Group () const
	Test if this is a Group Aggregate.
bool	is_Object () const
	Test if this is a Group Aggregate.
Aggregate &	move_in (Aggregate &aggregate)
	Moves the Parameter list in an Aggregate into this Aggregate's list.
Aggregate &	operator= (const Parameter &parameter)
	Assigns a Parameter to this Aggregate.
Aggregate &	operator= (const Aggregate &parameter)
	Assigns an Aggregate to this Aggregate.
Aggregate &	operator= (const Assignment &parameter)
	Assigns an Assignment to this Aggregate.
Aggregate &	operator= (const Value &value)
	An Aggregate doesn't have a Value, so this always throws an Invalid_Argument exception.
const Parameter &	operator[] (unsigned int index) const
	Gets the Parameter at an index of the Aggregate list.
Parameter &	operator[] (unsigned int index)
	Gets the Parameter at an index of the Aggregate list.
void	read (std::istream &in=std::cin)
	Reads an input stream parsed as PVL syntax into this Aggregate.
void	read (Parser &parser)
	Parameters read by a Parser are added to this Aggregate.
Parameter *	remove (size_type index)
	Removes a Parameter at an element index of the Aggregate's Parameter list.
Parameter *	remove (Parameter *parameter)
	Removes a Parameter from the Aggregate's Parameter list.
Parameter *	remove (iterator position)
	Removes a Parameter at an iterator position from the Aggregate's Parameter list.
Parameter *	remove_depth (Parameter *parameter)
	Removes a Parameter from the Aggregate's Parameter list or any of its sub-lists.
void	removing (Parameter *parameter)
	Resets the parent of a Parameter to NULL.
size_type	total_size ()
	Counts the number of Parameters in the Aggregate's Parameter list and, recursively, the number of Parameters in the Parameter list of each Aggregate in the list.
Aggregate &	type (const int type)
	Sets the Type specification.
Type	type () const
	Gets the Type specification.
std::string	type_name () const
	Gets the name for this Aggregate's Type specification.
Value &	value () const
	An Aggregate doesn't have a Value, so this always throws an Invalid_Argument exception.
	~Aggregate ()
	Destroys an Aggregate by clearing the Parameter list.
Static Public Member Functions
static Type	default_type ()
	Gets the default Type specification to be used when constructing a new Aggregate without a Type specified.
static Type	default_type (const int type)
	Sets the default Type specification to be used when constructing a new Aggregate without a Type specified.

Detailed Description

An Aggregate implements a Parameter that is a list of Parameters.

An Aggregate provides for the hierarchical structuring of Parameters.

The list is provided by subclassing a Vectal of Parameters. A Vectal is a vector of virtual objects that are stored as pointers but for which reference semantics are offered in the access interface. However, the normal value functionality is also provided by copying (actually cloning) objects into the list and deleting them on removal. An Aggregate ensures that, normally, whenever a Parameter is entered into its list the parent of the Parameter is set to the Aggregate. Thus the hierarchical relationships are automatically maintained. Provision is also made for pulling a Parameter from an Aggregate's list without deleting it, but also automatically resetting its parent to NULL to correctly reflect that it is no longer a member of the Aggregate hierarchy.

In addition to the normal vector interators for traversing an Aggregate's Parameter list, specialized Depth_Iterators are provided that descend into Aggregates encountered in a Parameter list. They continue iterating the parent list where they left off after completing the interation of a child Aggregate. They also remember the root Aggregate where they started, which is where they will end. These iterators are bidirectional with some random access capabilities.

See also:: Vectal

Member Typedef Documentation

typedef Vectal<Parameter> Parameter_List

Aggregate as a Vectal (vector) of Parameters.

typedef Parameter_List::iterator iterator

Identify the iterator for compilers that need help.

Reimplemented from Vectal< Parameter >.

typedef Parameter_List::const_iterator const_iterator

Identify the iterator for compilers that need help.

Reimplemented from Vectal< Parameter >.

typedef Depth_Iterator depth_iterator

A specialized iterator that descends into Aggregates in the Parameter list.

Member Enumeration Documentation

anonymous enum

Flags for find case sensitivity argument.

Enumerator:

CASE_INSENSITIVE
CASE_SENSITIVE

Constructor & Destructor Documentation

Aggregate	(	const std::string	name = `""`,
		const idaeim::PVL::Parameter::Type	type_code = `Default_Subtype`
	)		`[explicit]`

Constructs an empty Aggregate.

Parameters:

name	The Parameter name.
type_code	The Type specification code for the Aggregate.

See also:: type(Type)

Aggregate ( const Aggregate & aggregate )

Copy constructor.

The entire Parameter list is replicated (cloned).

Parameters:

aggregate The Aggregate to copy.

See also:: Parameter::Parameter(Parameter)

Aggregate ( const Parameter & parameter )

Copy constructor from a Parameter.

If the Parameter being copied is an Aggregate, it is assigned to the new Aggregate. If, however, the Parameter is an Assignment, it is copied as the first element in the new Aggregate's Parameter list.

Parameters:

parameter The Parameter to copy.

Aggregate	(	Parser &	parser,
		const std::string	name = `""`
	)

Constructs an Aggregate using a Parser to provide its contents.

This is the same as constructing an empty Aggregate and then using the Parser::add_parameters(Aggregate&) method on it. Note that the Parameters obtained from the Parser are all added as elements of the new Aggregate. Thus even if the Parser only finds one Parameter - e.g. from a string defining a single Group - the result will be an Aggregate containing a single Parameter element.

Note: If the new Aggregate is given the name Parser::CONTAINER_NAME then when the Aggregate is written to an ostream, only the content Parameters will be written.

Parameters:

parser	The Parser from which to get content Parameters.
name	The name for the Aggregate.

See also:: Parser::add_parameters(Aggregate&)

~Aggregate ( )

Destroys an Aggregate by clearing the Parameter list.

Each Parameter in the list will be deleted.

Member Function Documentation

Aggregate* clone ( ) const [inline, virtual]

Clones the Aggregate by making a copy of itself.

Returns:: A pointer to a copy of this Aggregate.

See also:: Aggregate(Aggregate&)

Implements Parameter.

References Parameter::Aggregate.

bool is_Aggregate ( ) const [inline, virtual]

Test if this is an Aggregate.

Returns:: Always returns true.

Reimplemented from Parameter.

bool is_Group ( ) const [inline, virtual]

Test if this is a Group Aggregate.

Returns:: true if the Type specification is GROUP.

Reimplemented from Parameter.

References Parameter::GROUP.

bool is_Object ( ) const [inline, virtual]

Test if this is a Group Aggregate.

Returns:: true if the Type specification is OBJECT.

Reimplemented from Parameter.

References Parameter::OBJECT.

bool is ( const Type type ) const [inline, virtual]

Test if the Parameter is of some Type.

The test is the logical AND of the Parameter Subtype and the specified Type value. Thus, conceptually, the test is if the Parameter is any one of a possible combination of Types. For example, parameter.is (GROUP| OBJECT) will be true for any AGGREGATE parameter, which could just as easily be tested by parameter.is (AGGREGATE); and parameter.is (ASSIGNMENT | AGGREGATE) can be expected to always be true.

Parameters:

type	The Type specification code against which to test the Parameter.

Returns:: true if the implementing class is of the specified Type. an OBJECT Type specification; false otherwise.

Implements Parameter.

References Parameter::type().

Type type ( ) const [inline, virtual]

Gets the Type specification.

Returns:: This should be either the GROUP or OBJECT code.

Implements Parameter.

Aggregate& type ( const int type ) [virtual]

Sets the Type specification.

Parameters:

type	The Type specification for the Aggregate.

Returns:: This Aggregate.

Exceptions:

Invalid_Argument If the type value is not GROUP or OBJECT.

Implements Parameter.

std::string type_name ( ) const [inline, virtual]

Gets the name for this Aggregate's Type specification.

Returns:: The name string associated with the Aggregate's Type specification.

See also:: Parameter::type_name(Type)

Implements Parameter.

References Parameter::type_name().

static Type default_type ( ) [inline, static]

Gets the default Type specification to be used when constructing a new Aggregate without a Type specified.

Returns:: The current default Type specification.

static Type default_type ( const int type ) [static]

Sets the default Type specification to be used when constructing a new Aggregate without a Type specified.

Returns:: The previous default Type specification.

Exceptions:

Invalid_Argument If the type value is not GROUP or OBJECT.

Value& value ( ) const [virtual]

An Aggregate doesn't have a Value, so this always throws an Invalid_Argument exception.

Returns:: Never returns ...

Exceptions:

Invalid_Argument always.

Implements Parameter.

Parameter& operator[] ( unsigned int index ) [inline, virtual]

Gets the Parameter at an index of the Aggregate list.

This form of the operator is used with an assignable Parameter (lvalue) in an expression.

Parameters:

index The index of a Parameter in the Aggregate list.

Returns:: The Parameter reference at the index position.

Reimplemented from Parameter.

References Parameter::operator[]().

const Parameter& operator[] ( unsigned int index ) const [inline, virtual]

Gets the Parameter at an index of the Aggregate list.

This form of the operator produces an unassignable (read only) Parameter.

Parameters:

index The index of a Parameter in the Aggregate list.

Returns:: The Parameter reference at the index position.

Reimplemented from Parameter.

References Parameter::operator[]().

Aggregate& operator= ( const Parameter & parameter ) [virtual]

Assigns a Parameter to this Aggregate.

If the Parameter is an Aggregate its name, comment and Type specification are copied, but not its parent. The Parameter list from the other Aggregate is replicated (cloned) and replaces the current list. The replacement is overlap safe: an Aggregate from within this Aggregate can be assigned. The current Parameter list is set aside but not deleted until the list replacement has completed.

If the Parameter is an Assignment its clone is appended to the Parameter list.

Nothing is done when assigning a Parameter to itself.

Parameters:

parameter The Parameter to be assigned.

Returns:: This Aggregate.

Implements Parameter.

Aggregate& operator= ( const Aggregate & parameter ) [inline]

Assigns an Aggregate to this Aggregate.

Parameters:

parameter The Aggregate to be assigned.

Returns:: This Aggregate.

See also:: operator=(const Parameter&)

References Parameter::operator=().

Aggregate& operator= ( const Assignment & parameter ) [inline]

Assigns an Assignment to this Aggregate.

Parameters:

parameter The Assignment to be assigned.

Returns:: This Aggregate.

See also:: operator=(const Parameter&)

References Parameter::operator=().

Aggregate& operator= ( const Value & value ) [virtual]

An Aggregate doesn't have a Value, so this always throws an Invalid_Argument exception.

Returns:: Never returns ...

Exceptions:

Invalid_Argument always.

Implements Parameter.

int compare ( const Parameter & parameter ) const [virtual]

Compares this Aggregate with another Parameter.

A Parameter compared with itself is, of course, identical.

The Parameter names are compared and, if they are different, the result of this comparison is returned.

When the Parameter names are the same, an Aggregate is greater than an Assignment.

When comparing Aggregates with the same name, the greater is the one with the larger Parameter list (not including the size of Parameter lists in any Aggregates in the list). When the size of both lists is the same, then each Parameter in the list is compared in the order they occur in the list and the result of the first non-equal comparison is returned; thus for the best results sort both Aggregates first.

Parameters:

parameter The Parameter to compare against.

Returns:: An int that is less than, equal to, or greater than 0 if this Aggregate is logically less than, equal to, or greater than, respectively, the Parameter.

See also:: sort(depth_iterator, depth_iterator)

Implements Parameter.

Parameter* find	(	const std::string &	pathname,
		bool	case_sensitive = `false`,
		int	skip = `0`,
		idaeim::PVL::Parameter::Type	type = `(Type)(ASSIGNMENT\|AGGREGATE)`
	)		const

Find a named Parameter.

The Parameter to be found may be specified by a simple name, a relative pathname or an absolute pathname. A simple name is the name of a Parameter itself. A relative pathname is a simple name preceeded by the pathname of an Aggregate Parameter that must contain the Parameter with the simple name. An absolute pathname is a pathname that begins with a pathname delimiter ('/'); i.e. it is a fully qualified pathname beginning at the root of the Aggregate hierarchy, compared to a relative pathname that may begin at any Aggregate in the hierarchy.

Since it is not necessary that the pathname to each Parameter be unique, the number of matching pathnames to skip before selecting a Parameter may need to be specified to get the desired Parameter. Also, a specific type of Parameter - an Aggregate of Parameters or an Assignment of Values - may be specified. When skipping parameters, only the specified type, if any, are counted.

Parameters:

pathname	The pathname of the parameter to find.
case_sensitive	If true, the name search is case sensitive; case insensitive otherwise.
skip	The number of parameters that match the criteria to skip before selecting a matching parameter. A value less than or equal to zero selects the first match.
type	A Type code that specifies the type of Parameter that is to be selected. By default any Type (ASSIGNMENT or AGGREGATE) will be acceptable.

Returns:: A pointer to the matching parameter, or NULL if a match could not be found.

void read ( std::istream & in = std::cin ) [virtual]

Reads an input stream parsed as PVL syntax into this Aggregate.

A Parser is constructed from the input stream and passed to the read(Parser&) method.

Parameters:

in	The istream to be parsed for PVL syntax.

Implements Parameter.

void read ( Parser & parser ) [virtual]

Parameters read by a Parser are added to this Aggregate.

All available Parameters are obtained from the Parser will be added to the end of this Aggregate's Parameter list. If the Parser produces an Aggregate then each Parameter in its list is moved into this Aggregate list if the list is currently empty; if the list is not empty the entire Aggregate that was obtained, not just its list of Parameters, is appended to the list. If the Parameter the Parser produces in not an Aggregate Parameter then it is appended to this Aggregate's list. If the Parser does not produce a Parameter, nothing is done.

Parameters:

parser The Parser from which to obtain Parameters.

See also:: Parser::get_parameters()

Implements Parameter.

Aggregate& add ( const Parameter & parameter ) [inline]

Adds a clone of the Parameter to the end of the Aggregate's Parameter list.

Parameters:

parameter The Parameter to add.

Returns:: This Aggregate.

See also:: Vectal::push_back(reference); add(Parameter*)

Aggregate& add ( Parameter * parameter ) [inline]

Adds the Parameter to the end of the Aggregate's Parameter list.

Note: The Parameter is not cloned; The Parameter pointer is placed directly in the Parameter list backing store. The parent of the Parameter is changed to this Aggregate.

Parameters:

parameter The Parameter to add.

Returns:: This Aggregate.

See also:: Vectal::poke_back(pointer); add(const Parameter&)

Aggregate& copy_in ( const Aggregate & aggregate )

Copies the Parameter list in an Aggregate into this Aggregate's list.

Each Parameter in the source Aggregate Parameter list is added to the end of this Aggregate's Parameter list.

Parameters:

aggregate The source Aggregate.

Returns:: This Aggregate.

See also:: add(const Parameter&)

Aggregate& move_in ( Aggregate & aggregate )

Moves the Parameter list in an Aggregate into this Aggregate's list.

Each Parameter in the source Aggregate Parameter list is moved to the end of this Aggregate's Parameter list. As a result the source Aggregate will be emptied.

Parameters:

aggregate The source Aggregate.

Returns:: This Aggregate.

See also:: add(const Parameter*)

Parameter* remove ( iterator position )

Removes a Parameter at an iterator position from the Aggregate's Parameter list.

Parameters:

position A valid iterator for the Aggregate's Parameter list.

Returns:: A pointer to the Parameter that was removed.

See also:: pull_out(iterator)

Parameter* remove ( size_type index )

Removes a Parameter at an element index of the Aggregate's Parameter list.

Parameters:

index An index of the Aggregate's Parameter list.

Returns:: A pointer to the Parameter that was removed. This will be NULL if the index is not within the range of existing elements of the Aggregate's Parameter list.

See also:: pull_out(size_type)

Parameter* remove ( Parameter * parameter )

Removes a Parameter from the Aggregate's Parameter list.

Parameters:

parameter A pointer to the Parameter to be removed. If NULL nothing is done and NULL is returned.

Returns:: A pointer to the Parameter that was removed, or NULL if the Parameter was not found in the Aggregate's Parameter list.

Parameter* remove_depth ( Parameter * parameter )

Removes a Parameter from the Aggregate's Parameter list or any of its sub-lists.

Parameters:

parameter A pointer to the Parameter to be removed. If NULL nothing is done and NULL is returned.

Returns:: A pointer to the Parameter that was removed, or NULL if the Parameter was not found.

void entering ( Parameter * parameter )

Sets the parent of a Parameter to this Aggregate.

This method overrides the Vectal's method that is invoked whenever a Parameter is entered into the Parameter list. It is not intended for normal use since it affects the logical relationship of Parameters in an Aggregate hierarchy.

The uniquness of the Parameter in the path hierachy is ensured; loops are prevented.

Parameters:

parameter The Parameter whose parent is to be changed.

Exceptions:

Invalid_Argument If the parameter is in the Aggregate's path; i.e. the Parameter is already in the parent hierachy of the Aggregate, or is the Aggregate itself.

void removing ( Parameter * parameter )

Resets the parent of a Parameter to NULL.

This method overrides the Vectal's method that is invoked whenever a Parameter is removed from the Parameter list. It is not intended for normal use since it affects the logical relationship of Parameters in an Aggregate hierarchy.

Parameters:

parameter The Parameter whose parent is to be changed.

size_type total_size ( )

Counts the number of Parameters in the Aggregate's Parameter list and, recursively, the number of Parameters in the Parameter list of each Aggregate in the list.

Returns:: The accumulated total number of Parameters enclosed by this Aggregate.

Depth_Iterator begin_depth ( )

Gets a Depth_Iterator positioned at the beginning of this Aggregate.

Returns:: A Depth_Iterator.

Depth_Iterator end_depth ( )

Gets a Depth_Iterator positioned at the end of this Aggregate.

Returns:: A Depth_Iterator.

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

Parameter.hh

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation