Aggregate Class Reference

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

#include <Parameter.hh>

Inheritance diagram for Aggregate:

Collaboration diagram for Aggregate:

List of all members.

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

typedef Depth_Iterator depth_iterator

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

typedef Vectal< Parameter > Parameter_List

Aggregate as a Vectal (vector) of Parameters.

Public Member Functions

Aggregate & add (Parameter *parameter)

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

Aggregate & add (const Parameter &parameter)

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

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

Constructs an Aggregate using a Parser to provide its contents.

Aggregate (const Parameter &parameter)

Copy constructor from a Parameter.

Aggregate (const Aggregate &aggregate)

Copy constructor.

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

Constructs an empty Aggregate.

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.

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 Value &value)

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

Aggregate & operator= (const Assignment &parameter)

Assigns an Assignment to this Aggregate.

Aggregate & operator= (const Aggregate &parameter)

Assigns an Aggregate to this Aggregate.

Aggregate & operator= (const Parameter &parameter)

Assigns a Parameter to this Aggregate.

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 (Parser &parser)

Parameters read by a Parser are added to this Aggregate.

void read (std::istream &in=std::cin)

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

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.

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 (const int type)

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

static Type default_type ()

Gets 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 Depth_Iterator depth_iterator

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

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)

References Vectal< T >::begin(), and Vectal< T >::end().

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.

References Parameter::is_Aggregate().

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&)

References Parser::add_parameters().

~Aggregate ( )

Destroys an Aggregate by clearing the Parameter list.

Each Parameter in the list will be deleted.

References Vectal< Parameter >::clear().

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]

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.

Type type ( ) const [inline, virtual]

Gets the Type specification.

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

Implements Parameter.

Referenced by Parser::ingest_parameters().

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.

References Parameter::GROUP, Parameter::ID, Parameter::OBJECT, and Parameter::type_name().

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().

Referenced by Parser::ingest_parameters(), Aggregate::value(), and Lister::write().

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.

Parameter::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.

References Parameter::GROUP, Parameter::ID, Parameter::OBJECT, and Parameter::type_name().

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.

References Parameter::ID, and Aggregate::type_name().

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.

References Parameter::Comment, Parameter::is_Aggregate(), Parameter::mode_state(), Parameter::Name, and Parameter::type().

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.

References Parameter::ID.

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.

References Vectal< T >::begin(), Parameter::is_Assignment(), and Parameter::name().

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.

References Parser::get_parameters(), and Parameter::is_Aggregate().

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&)

References Vectal< T >::begin(), and Vectal< T >::end().

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*)

References Vectal< T >::vector_base(), and Vectal< T >::wipe().

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.

Parameter * remove ( Parameter * parameter )

Removes a Parameter from the Aggregate's Parameter list.

Parameters:

parameter

A pointer to the Parameter to be removed.

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

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.

References Parameter::ID, Parameter::Parent, and Parameter::pathname().

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.

References Parameter::Parent.

Aggregate::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.

References Vectal< Parameter >::begin(), and Vectal< Parameter >::end().

Aggregate::Depth_Iterator begin_depth ( )

Gets a Depth_Iterator positioned at the beginning of this Aggregate.

Returns:: A Depth_Iterator.

Referenced by Aggregate::end_depth().

Aggregate::Depth_Iterator end_depth ( )

Gets a Depth_Iterator positioned at the end of this Aggregate.

Returns:: A Depth_Iterator.

References Aggregate::begin_depth(), and Aggregate::Depth_Iterator::end_depth().

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


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
typedef Depth_Iterator	depth_iterator
	A specialized iterator that descends into Aggregates in the Parameter list.
typedef Vectal< Parameter >	Parameter_List
	Aggregate as a Vectal (vector) of Parameters.
Public Member Functions
Aggregate &	add (Parameter *parameter)
	Adds the Parameter to the end of the Aggregate's Parameter list.
Aggregate &	add (const Parameter &parameter)
	Adds a clone of the Parameter to the end of the Aggregate's Parameter list.
	Aggregate (Parser &parser, const std::string name="")
	Constructs an Aggregate using a Parser to provide its contents.
	Aggregate (const Parameter &parameter)
	Copy constructor from a Parameter.
	Aggregate (const Aggregate &aggregate)
	Copy constructor.
	Aggregate (const std::string name="", const idaeim::PVL::Parameter::Type type_code=Default_Subtype)
	Constructs an empty Aggregate.
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.
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 Value &value)
	An Aggregate doesn't have a Value, so this always throws an Invalid_Argument exception.
Aggregate &	operator= (const Assignment &parameter)
	Assigns an Assignment to this Aggregate.
Aggregate &	operator= (const Aggregate &parameter)
	Assigns an Aggregate to this Aggregate.
Aggregate &	operator= (const Parameter &parameter)
	Assigns a Parameter to this Aggregate.
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 (Parser &parser)
	Parameters read by a Parser are added to this Aggregate.
void	read (std::istream &in=std::cin)
	Reads an input stream parsed as PVL syntax into this Aggregate.
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.
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 (const int type)
	Sets the default Type specification to be used when constructing a new Aggregate without a Type specified.
static Type	default_type ()
	Gets the default Type specification to be used when constructing a new Aggregate without a Type specified.