Array Class Reference

An Array implements a Value that is a list of Values. More...

#include <Value.hh>

Inheritance diagram for Array:

Collaboration diagram for Array:

List of all members.

Classes
class	Depth_Iterator
	A Depth_Iterator is a bidirectional iterator over an Array's Value list and, depth-first, over the Value list of each Array encountered. More...
Public Types
typedef Value_List::const_iterator	const_iterator
	Identify the iterator for compilers that need help.
typedef Depth_Iterator	depth_iterator
	A specialized iterator that descends into Arrays in the Value list.
typedef Value_List::iterator	iterator
	Identify the iterator for compilers that need help.
typedef Vectal< Value >	Value_List
	Array as a Vectal (vector) of Values.
Public Member Functions
Array &	add (const Value &value)
	Adds a clone of a Value to the end of the Array's Value list.
Array &	add (Value *value)
	Adds a Value to the end of the Array's Value list.
	Array (const Array &array)
	Constructs an Array as a copy of another Array.
	Array (Parser &parser, const Type type=Default_Subtype)
	Construct an Array from a Parser.
	Array (const Type type=Default_Subtype)
	Constructs an empty Array.
	Array (const Value &value)
	Constructs an Array from another Value.
Array &	base (const int)
	Prevents the base from being changed.
Depth_Iterator	begin_depth ()
	Gets a Depth_Iterator positioned at the beginning of this Array.
Array *	clone () const
	Constructs a clone of this Array.
int	compare (const Value &value) const
	This Array is compared to another Value.
Array &	copy_in (const Array &array)
	Copies the Value list in an Array into this Array's list.
Depth_Iterator	end_depth ()
	Gets a Depth_Iterator positioned at the end of this Array.
void	entering (Value *value)
	Sets the parent of a Value to this Array.
bool	is_Array () const
	Asserts that the Array is an ARRAY Type.
bool	is_Sequence () const
	Tests if the Array is a SEQUENCE Type.
bool	is_Set () const
	Tests if the Array is a SET Type.
Array &	move_in (Array &array)
	Moves the Value list in an Array into this Array's list.
	operator int () const
	operator Integer_type () const
	operator Real_type () const
	operator String_type () const
Array	operator+ (const Value &value) const
	Adds this Array and a Value.
Array &	operator+= (const Value &value)
	Adds a Value to this Array.
Array &	operator= (const unsigned int value)
Array &	operator= (const Real_type value)
Array &	operator= (const Integer_type value)
Array &	operator= (const int value)
Array &	operator= (const Value &value)
	Assigns a Value to this Array.
Array &	operator= (const Unsigned_Integer_type value)
Array &	operator= (const char *value)
Array &	operator= (const String_type &value)
Value &	operator[] (unsigned int index)
	Gets the Value at an index of the Array list.
const Value &	operator[] (unsigned int index) const
	Gets the Value at an index of the Array list.
Value *	remove (Value *value)
	Removes a Value from the Array's Value list.
Value *	remove (size_type index)
	Removes a Value at an element index of the Array's Value list.
Value *	remove (iterator position)
	Removes a Value at an iterator position from the Array's Value list.
Value *	remove_depth (Value *value)
	Removes a Value from the Array's Value list or any of its sub-Array ists.
void	removing (Value *value)
	Resets the parent of a Value to NULL.
size_type	total_size ()
	Counts the number of Values in the Array's Value list and, recursively, the number of Values in the Value list of each Array in the list.
Array &	type (const Type type_code)
	Sets the specific Array Type.
Type	type () const
	Gets the specific Array Type.
std::string	type_name () const
	Gets the name string for the Array Type.
Static Public Member Functions
static Type	default_type ()
	Gets the default Type for an Array.
static Type	default_type (const int type_code)
	Sets the default Type to use when constructing an Array.

---

Detailed Description

An Array implements a Value that is a list of Values.

An Array provides for the hierarchical structuring of Values.

The list is provided by subclassing a Vectal of Values. 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 Array ensures that, normally, whenever a Value is entered into its list the parent of the Value is set to the Array. Thus the hierarchical relationships are automatically maintained. Provision is also made for pulling a Value from an Array'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 Array hierarchy.

In addition to the normal vector interators for traversing an Array's Value list, specialized Depth_Iterators are provided that descend into Arrays encountered in a Value list. They continue iterating the parent list where they left off after completing the interation of a child Array. They also remember the root Array 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<Value> Value_List

Array as a Vectal (vector) of Values.

typedef Value_List::iterator iterator

Identify the iterator for compilers that need help.

Reimplemented from Vectal< Value >.

typedef Value_List::const_iterator const_iterator

Identify the iterator for compilers that need help.

Reimplemented from Vectal< Value >.

typedef Depth_Iterator depth_iterator

A specialized iterator that descends into Arrays in the Value list.

---

Constructor & Destructor Documentation

Array

(

const Type

type = Default_Subtype

)

[explicit]

Constructs an empty Array.

Parameters:

type	The Type specification for an Array. This must be either SET or SEQUENCE.

See also:

type(Type)

Array

(

const Array &

array

)

Constructs an Array as a copy of another Array.

The list of the Array being copied is replicated (cloned).

Parameters:

array

The Array to copy.

Array

(

const Value &

value

)

Constructs an Array from another Value.

If the Value being copied is an Array, it is assigned to the new Array. Otherwise the Value is copied as the first element in the new Array's Value list.

Parameters:

value

The Value to copy.

Array	(	Parser &	parser,
		const Type	type = Default_Subtype
	)

Construct an Array from a Parser.

The next Value obtained from the Parser is used as the contents of the new Array. If the Parser Value is an Array, then all of its elements are moved into the new Array which is set to the same Type, and the original Array is deleted. Otherwise the Value becomes the only element of the new Array which is set to the specified Type.

Parameters:

parser	The Parser from which to construct the Value.
type	The default Type of the Array to construct if the Parser does not provide an Array.

See also:

Parser::get_value()

---

Member Function Documentation

Array* clone

(

)

const [inline, virtual]

Constructs a clone of this Array.

A clone is a copy constructed on the heap.

Returns:

A pointer to the new Array clone.

Implements Value.

References Value::Array.

operator Integer_type

(

)

const [virtual]

Exceptions:

Invalid_Argument

An Array can not be cast to a primitive type.

Implements Value.

operator int

(

)

const [virtual]

Exceptions:

Invalid_Argument

An Array can not be cast to a primitive type.

Implements Value.

operator Real_type

(

)

const [virtual]

Exceptions:

Invalid_Argument

An Array can not be cast to a primitive type.

Implements Value.

operator String_type

(

)

const [virtual]

Exceptions:

Invalid_Argument

An Array can not be cast to a primitive type.

Implements Value.

Array& base

(

const int

)

[inline, virtual]

Prevents the base from being changed.

An Array does not have a numeric base.

Returns:

This Array.

Reimplemented from Value.

bool is_Array

(

)

const [inline, virtual]

Asserts that the Array is an ARRAY Type.

Returns:

Always returns true.

Reimplemented from Value.

bool is_Set

(

)

const [inline, virtual]

Tests if the Array is a SET Type.

Returns:

true if the Type of this String is SET.

Reimplemented from Value.

References Value::SET.

bool is_Sequence

(

)

const [inline, virtual]

Tests if the Array is a SEQUENCE Type.

Returns:

true if the Type of this String is SEQUENCE.

Reimplemented from Value.

References Value::SEQUENCE.

Type type

(

)

const [inline, virtual]

Gets the specific Array Type.

Returns:

The Type code of this Array.

Implements Value.

Array& type

(

const Type

type_code

)

Sets the specific Array Type.

Parameters:

type_code

An Array Type code, which must be one of SET or SEQUENCE.

Exceptions:

Invalid_Argument

if the type_code is not one of the ARRAY Type values.

std::string type_name

(

)

const [inline, virtual]

Gets the name string for the Array Type.

Returns:

The type_name of the Array Type.

Implements Value.

References Value::type_name().

static Type default_type

(

)

[inline, static]

Gets the default Type for an Array.

Returns:

The default ARRAY Type.

static Type default_type

(

const int

type_code

)

[static]

Sets the default Type to use when constructing an Array.

Parameters:

type_code

An Array Type code, which must be one of SET or SEQUENCE.

Returns:

The type_code.

Exceptions:

Invalid_Argument

if the type_code is not one of the ARRAY Type values.

Value& operator[]

(

unsigned int

index

)

[inline, virtual]

Gets the Value at an index of the Array list.

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

Parameters:

index

The index of a Value in the Array list.

Returns:

The Value reference at the index position.

Reimplemented from Value.

References Value::operator[]().

const Value& operator[]

(

unsigned int

index

)

const [inline, virtual]

Gets the Value at an index of the Array list.

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

Parameters:

index

The index of a Value in the Array list.

Returns:

The Value reference at the index position.

Reimplemented from Value.

References Value::operator[]().

Array& operator=

(

const Value &

value

)

[virtual]

Assigns a Value to this Array.

The Value being assigned must be an Array. Use the add (or push_back) method to add a Value to the Array list.

The existing Value list is set aside without deleting it in case the Value being assigned is contained with this Array. The Value list from the assigned Value is copied into this Array's now empty Value list. The copied Values are cloned in depth. Finally the original Value list is deleted.

Parameters:

value

The Value to be assigned.

Returns:

This Array.

Exceptions:

Invalid_Argument

If the assigned Value is not an Array.

Implements Value.

Array& operator=

(

const Integer_type

value

)

[virtual]

Exceptions:

Invalid_Argument

An Array can not be assigned a primitive type.

Implements Value.

Array& operator=

(

const Unsigned_Integer_type

value

)

Exceptions:

Invalid_Argument

An Array can not be assigned a primitive type.

Array& operator=

(

const int

value

)

[inline, virtual]

Exceptions:

Invalid_Argument

An Array can not be assigned a primitive type.

Implements Value.

References Value::operator=().

Array& operator=

(

const unsigned int

value

)

[inline, virtual]

Exceptions:

Invalid_Argument

An Array can not be assigned a primitive type.

Implements Value.

References Value::operator=().

Array& operator=

(

const Real_type

value

)

[virtual]

Exceptions:

Invalid_Argument

An Array can not be assigned a primitive type.

Implements Value.

Array& operator=

(

const String_type &

value

)

[virtual]

Exceptions:

Invalid_Argument

An Array can not be assigned a primitive type.

Implements Value.

Array& operator=

(

const char *

value

)

[virtual]

Exceptions:

Invalid_Argument

An Array can not be assigned a primitive type.

Implements Value.

Array& operator+=

(

const Value &

value

)

[virtual]

Adds a Value to this Array.

If the value is an Array each Value in its list is added to this Array's Value list. Otherwise the value itself is added to this Array's Value list.

Parameters:

value

The Value to be added to this Array.

Returns:

This Array.

See also:

add(const Value&)

Implements Value.

Array operator+

(

const Value &

value

)

const

Adds this Array and a Value.

Adds the Value to a copy of this Array.

Parameters:

value

The Value to be added to this Array.

Returns:

A copy of this Array with the Value added.

See also:

operator+=(const Value&)

int compare

(

const Value &

value

)

const [virtual]

This Array is compared to another Value.

An Array always compares greater than other types of Values.

When the other Value is an Array the Value list sizes are compared. If the list sizes are the same then each Value in the list is compared and the first non-equal Values determine the comparison.

Parameters:

value

The Value to be compared against.

Returns:

An int that is less than, equal to, or greater than 0 if this String is logically less than, equal to, or greater than, respectively, the other Value.

Implements Value.

Array& add

(

const Value &

value

)

[inline]

Adds a clone of a Value to the end of the Array's Value list.

Note: If the Value being added is an Array the Array itself, not its Value list, is added. This is different than operator+=().

Parameters:

value

The Value to add.

Returns:

This Array.

See also:

Vectal::push_back(reference)

Array& add

(

Value *

value

)

[inline]

Adds a Value to the end of the Array's Value list.

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

Parameters:

value

The Value to add.

Returns:

This Array.

See also:

Vectal::poke_back(pointer)

Array& copy_in

(

const Array &

array

)

Copies the Value list in an Array into this Array's list.

Each Value in the source Array Value list is added to the end of this Array's Value list.

Parameters:

array

The source Array.

Returns:

This Array.

See also:

add(const Value&)

Array& move_in

(

Array &

array

)

Moves the Value list in an Array into this Array's list.

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

Parameters:

array

The source Array.

Returns:

This Array.

See also:

add(const Value*)

Value* remove

(

iterator

position

)

Removes a Value at an iterator position from the Array's Value list.

Parameters:

position

A valid iterator for the Array's Value list.

Returns:

A pointer to the Value that was removed.

Value* remove

(

size_type

index

)

Removes a Value at an element index of the Array's Value list.

Parameters:

index

An index of the Array's Value list.

Returns:

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

See also:

pull_out(size_type)

Value* remove

(

Value *

value

)

Removes a Value from the Array's Value list.

Parameters:

value

A pointer to the Value to be removed.

Returns:

A pointer to the Value that was removed, or NULL if the Value was not found in the Array's Value list.

Value* remove_depth

(

Value *

value

)

Removes a Value from the Array's Value list or any of its sub-Array ists.

Parameters:

value

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

Returns:

A pointer to the Value that was removed, or NULL if the Value was not found.

void entering

(

Value *

value

)

Sets the parent of a Value to this Array.

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

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

Parameters:

value

The Value whose parent is to be changed.

Exceptions:

Invalid_Argument

If the value is in the Array's path; i.e. the Value is already in the parent hierachy of the Array, or is the Array itself.

void removing

(

Value *

value

)

Resets the parent of a Value to NULL.

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

Parameters:

value

The Value whose parent is to be changed.

size_type total_size

(

)

Counts the number of Values in the Array's Value list and, recursively, the number of Values in the Value list of each Array in the list.

Returns:

The accumulated total number of Values enclosed by this Array.

Depth_Iterator begin_depth

(

)

Gets a Depth_Iterator positioned at the beginning of this Array.

Returns:

A Depth_Iterator.

Depth_Iterator end_depth

(

)

Gets a Depth_Iterator positioned at the end of this Array.

Returns:

A Depth_Iterator.

---

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

• Value.hh