PVL: Parameter Value Language
|
|
PVL: Parameter Value Language
|
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...
#include <Parameter.hh>
Public Member Functions | |
| Aggregate * | aggregate () const |
| Gets the current Aggregate context. | |
| Depth_Iterator (const Aggregate &aggregate) | |
| Constructs a Depth_Iterator for an Aggregate. | |
| Depth_Iterator () | |
| Constructs a Depth_Iterator without a root Aggregate. | |
| Depth_Iterator (const Aggregate::iterator &list_iterator) | |
| Constructs a Depth_Iterator from a normal Parameter_List iterator. | |
| Depth_Iterator | end_depth () const |
| Gets a Depth_Iterator positioned at the end of the traversal for this Depth_Iterator. | |
| Depth_Iterator & | next_sibling () |
| operator Aggregate::iterator () | |
| Converts the Depth_Iterator to a Parameter_List iterator. | |
| bool | operator!= (const Depth_Iterator &depth_iterator) const |
| Tests if the current positions of this Depth_Iterator and another Depth_Iterator are not equivalent. | |
| bool | operator!= (const Aggregate::iterator &list_iterator) const |
| Tests if the current position of this Depth_Iterator and an Aggregate list iterator are not equivalent. | |
| Parameter & | operator* () const |
| Gets a reference to the Parameter at the current position. | |
| Depth_Iterator | operator+ (int distance) const |
| Gets a Depth_Iterator for a position at some distance from the current position. | |
| Depth_Iterator & | operator++ () |
| Pre-increments forward to the next Parameter position. | |
| Depth_Iterator | operator++ (int) |
| Post-increments forward to the next Parameter position. | |
| Depth_Iterator & | operator+= (int distance) |
| Relocates the current position by the specified distance. | |
| int | operator- (const Aggregate::iterator &list_iterator) const |
| Get the distance between this Depth_Iterator and an Aggregate list iterator. | |
| Depth_Iterator | operator- (int distance) const |
| Gets a Depth_Iterator for a position at some distance from the current position. | |
| int | operator- (const Depth_Iterator &depth_iterator) const |
| Gets the distance between this and another Depth_Iterator. | |
| Depth_Iterator | operator-- (int) |
| Post-decrements backward to the previous Parameter position. | |
| Depth_Iterator & | operator-- () |
| Pre-decrements backward to the previous Parameter position. | |
| Depth_Iterator & | operator-= (int distance) |
| Relocates the current position by the specified distance. | |
| Parameter * | operator-> () const |
| Gets a pointer to the Parameter at the current position. | |
| bool | operator< (const Aggregate::iterator &list_iterator) const |
| Tests if the current position of this Depth_Iterator is less than the position of an Aggregate list iterator. | |
| bool | operator< (const Depth_Iterator &depth_iterator) const |
| Tests if the position of this Depth_Iterator is less than the position of another Depth_Iterator. | |
| bool | operator<= (const Aggregate::iterator &list_iterator) const |
| Tests if the position of this Depth_Iterator is less than or equal to the position of an Aggregate list iterator. | |
| bool | operator<= (const Depth_Iterator &depth_iterator) const |
| Tests if the position of this Depth_Iterator is less than or equal to the position of another Depth_Iterator. | |
| Depth_Iterator & | operator= (const Aggregate::iterator &list_iterator) |
| Assigns a Parameter list iterator to this Depth_Iterator. | |
| bool | operator== (const Aggregate::iterator &list_iterator) const |
| Tests if the current position of this Depth_Iterator and an Aggregate list iterator are equivalent. | |
| bool | operator== (const Depth_Iterator &depth_iterator) const |
| Tests if the current positions of this Depth_Iterator and another Depth_Iterator are equivalent. | |
| bool | operator> (const Depth_Iterator &depth_iterator) const |
| Tests if the position of this Depth_Iterator is greater than the position of another Depth_Iterator. | |
| bool | operator> (const Aggregate::iterator &list_iterator) const |
| Tests if the position of this Depth_Iterator is greater than the position of an Aggregate list iterator. | |
| bool | operator>= (const Aggregate::iterator &list_iterator) const |
| Tests if the position of this Depth_Iterator is greater than or equal to the position of an Aggregate list iterator. | |
| bool | operator>= (const Depth_Iterator &depth_iterator) const |
| Tests if the position of this Depth_Iterator is greater than or equal to the position of another Depth_Iterator. | |
| Parameter & | operator[] (int offset) const |
| Array-style access to the Parameter at an offset from the current position. | |
| Depth_Iterator & | previous_sibling () |
| Aggregate * | root () const |
| Gets the root Aggregate. | |
A Depth_Iterator is a bidirectional iterator over an Aggregate's Parameter list and, depth-first, over the Parameter list of each Aggregate encountered.
The Depth_Iterator operates like a normal breadth-only interator for a Parameter list until it encounters an Aggregate in the list. When it is incremented from an Aggregate position it decends into the Aggregate, and only returns to the next Parameter in the current list when the end of the Parameter list of the Aggregate has been reached. This process is recursive resulting in a depth-first traversal of the entire Aggregate Parameter hierarchy. The mechanism operates similarly when decrementing by descending into each Aggregate and reverse iterating its Parameter list, then returning to the current Parameter list when the beginning of the Aggregate's list has been reached.
A Depth_Iterator is associated with a specific Aggregate which it knows as its root Aggregate. It will not ascend into the Parameter list of the root Aggregate's parent. Like other container iterators, all positions are expected to be for valid Parameters except the final end position of the root Aggregate; reverse iteration will not go beyond the initial begin position of the root Aggregate.
Random-access operators are also provided. But because they are not truely random access, and do not operate in constant time, the Depth_Iterator is tagged as only bidirectional.
| Depth_Iterator | ( | ) | [inline] |
Constructs a Depth_Iterator without a root Aggregate.
This Depth_Iterator is invalid until it is assigned a valid iterator.
| Depth_Iterator | ( | const Aggregate & | aggregate | ) | [explicit] |
Constructs a Depth_Iterator for an Aggregate.
The initial position of this Depth_Iterator is the beginning of the Aggregate's Parameter list.
| aggregate | The root Aggregate. |
| Depth_Iterator | ( | const Aggregate::iterator & | list_iterator | ) |
Constructs a Depth_Iterator from a normal Parameter_List iterator.
Warning: The iterator must be valid; i.e. it must refer to a Parameter. An end iterator is not valid; use end_depth to get the iterator for the end of a Depth_Iterator.
| list_iterator | A Parameter_List iterator. |
| operator Aggregate::iterator | ( | ) | [inline] |
Converts the Depth_Iterator to a Parameter_List iterator.
| Aggregate* root | ( | ) | const |
Gets the root Aggregate.
| Aggregate* aggregate | ( | ) | const [inline] |
| Depth_Iterator end_depth | ( | ) | const |
Gets a Depth_Iterator positioned at the end of the traversal for this Depth_Iterator.
This is the same as the end iterator for the root Aggregate.
| Error | If this Depth_Iterator is invalid (it doesn't have a root Aggregate). |
| Depth_Iterator& operator= | ( | const Aggregate::iterator & | list_iterator | ) |
Assigns a Parameter list iterator to this Depth_Iterator.
If the Depth_Iterator is currently positioned at the same Parameter as the list iterator nothing happens.
If the Depth_Iterator and list iterator are positioned in the Parameter list of the same Aggregate, then the current position of the Depth_Iterator is simply moved to the list iterator position. However, if the list iterator position is the end of the current Parameter list, and the list is not in the root Aggregate, then the current position is moved to the position preceeding the end; unless the list has become empty (due to some other user action on the list) in which case the Depth_Iterator is incremented forward to the next valid position.
When the Depth_Iterator and list iterator are not positioned in the same Aggregate, then a search is made for the list iterator position within the scope of the Depth_Iterator. First a search is made from the current Depth_Iterator position towards the beginning of its scope. If this fails a search is made from the current Depth_Iterator position towards the end of its scope. The current position of the Depth_Iterator becomes list iterator position if it is found.
| list_iterator | The Parameter_List iterator position to be assigned to this Depth_Iterator. |
| Invalid_Argument | If the list iterator is not in the scope of this Depth_Iterator. |
| Error | If on attempting to ascend from an Aggregate hierarchy, a non-root Aggregate is encountered without a parent (this should not happen unless the Aggregate hierachy was inappropriately modified during traversal). |
| Parameter& operator* | ( | ) | const [inline] |
| Parameter* operator-> | ( | ) | const [inline] |
| Depth_Iterator& operator++ | ( | ) |
Pre-increments forward to the next Parameter position.
If the Parameter at the current position is a non-empty Aggregate, the current position is pushed onto a LIFO (last-in-first-out) stack and then the current position moves to the first entry in the child Aggregate's list.
If the Parameter at the current position is an Assignment or an empty Aggregate, then the current position is moved forward to the next position in the Parameter list. If this position is the end of the Parameter list, and the list is not for the root Aggregate, then the previous position in the parent's Parameter list is popped from the stack to the current position and it is moved forward again. Ascending up the Aggregate hierarchy continues in this way until a non-end list position is found, or the end of the root Aggregate is encountered.
Caution: Like any iterator, care must be taken not to inappropriately modify the container structure being traversed or the integrity of the Depth_Iterator will be lost. The Aggregate hierachy of the Depth_Iterator's current position is the primary issue. Each iterator, saved on the stack, to a previous position in the Aggregate heirarchy must remain consistent; the location of its Aggregate in the Parameter list must remain unchanged and the parent of the Aggregate must remain unchanged. Changes to the current Parameter list may be made as long as the current position of the Depth_Iterator remains valid; e.g. assigning back to the Depth_Iterator the iterator returned from an insert (or poke) or erase (or pull) using the current Depth_Iterator. Modfications anywhere in the Depth_Iterator scope beyond any current hierachy path position is safe; e.g. push_back or poke_back is always OK. But modifications at or before any current hierachy path position is almost always going to disrupt a Depth_Iterator.
| Out_of_Range | If the current position is the end of the root Aggregate. |
| Error | If the Depth_Iterator is invalid (doesn't have a root Aggregate). An Error will also be thrown if, on attempting to ascend the Aggregate hierarchy, a non-root Aggregate is encountered without a parent (this should not happen unless the Aggregate hierachy was inappropriately modified during traversal). |
| Depth_Iterator& next_sibling | ( | ) |
| Depth_Iterator operator++ | ( | int | ) |
Post-increments forward to the next Parameter position.
| Depth_Iterator& operator-- | ( | ) |
Pre-decrements backward to the previous Parameter position.
If the current position is not the beginning of a Parameter list, the current position moves to the previous Parameter in the list. If this Parameter is a non-empty Aggregate, the current position is pushed onto a LIFO (last-in-first-out) stack and then the current position moves to the last entry (the Parameter immediately preceeding the end position) in the child Aggregate's list. If this Parameter is a non-empty Aggregate then the currrent positionis pushed onto the stack again and the current position becomes the last entry in this Aggregate. This back-down cycle continues until an Assignment, or empty Aggregate, Parameter is encountered.
If the current position is the beginning of a Parameter list, and it is not the root Aggregate's Parameter list, then the previous position in the parent's Parameter list is popped from the stack to the current position.
| Out_of_Range | If the current position is the beginning of the root Aggregate. |
| Error | If the Depth_Iterator is invalid (doesn't have a root Aggregate). An Error will also be thrown if, on attempting to ascend the Aggregate hierarchy, a non-root Aggregate is encountered without a parent (this should not happen unless the Aggregate hierachy was inappropriately modified during traversal). |
| Depth_Iterator& previous_sibling | ( | ) |
| Depth_Iterator operator-- | ( | int | ) |
Post-decrements backward to the previous Parameter position.
| Parameter& operator[] | ( | int | offset | ) | const |
Array-style access to the Parameter at an offset from the current position.
The Depth_Iterator is copied and offset to the new position, and then dereferenced.
| offset | The position of the Parameter relative (positive or negative) to the current position. |
| Depth_Iterator& operator+= | ( | int | distance | ) |
Relocates the current position by the specified distance.
The Depth_Iterator is incremented for a positive distance, or decremented for a negative distance, repeatedly the absolute amount of the distance.
Note: This is a random-access iterator operator that does not occur in constant time.
| distance | The number of increment (positive) or decrement (negative) operations to apply. |
| Depth_Iterator operator+ | ( | int | distance | ) | const |
Gets a Depth_Iterator for a position at some distance from the current position.
A copy of this Depth_Iterator is offset the distance.
| distance | The offset of the new Depth_Iterator. |
| Depth_Iterator& operator-= | ( | int | distance | ) |
Relocates the current position by the specified distance.
| distance | The number of increment (negative) or decrement (positive) operations to apply. |
| Depth_Iterator operator- | ( | int | distance | ) | const |
Gets a Depth_Iterator for a position at some distance from the current position.
| distance | The offset of the new Depth_Iterator. |
| int operator- | ( | const Depth_Iterator & | depth_iterator | ) | const |
Gets the distance between this and another Depth_Iterator.
| depth_iterator | A Depth_Iterator position to find. |
| Out_of_Range | If the depth_iterator is not within the scope of this Depth_Iterator. |
| int operator- | ( | const Aggregate::iterator & | list_iterator | ) | const |
Get the distance between this Depth_Iterator and an Aggregate list iterator.
A search is made for the list iterator position in the scope of this Depth_Iterator; first backwards (positive distance), and then forwards (negative distance).
Note: This is a random-access iterator operator that does not occur in constant time.
| list_iterator | An Aggregate::iterator position to find. |
| Out_of_Range | If the list_iterator is not within the scope of this Depth_Iterator. |
| bool operator== | ( | const Depth_Iterator & | depth_iterator | ) | const [inline] |
Tests if the current positions of this Depth_Iterator and another Depth_Iterator are equivalent.
| depth_iterator | The Depth_Iterator to compare against. |
| bool operator!= | ( | const Depth_Iterator & | depth_iterator | ) | const [inline] |
Tests if the current positions of this Depth_Iterator and another Depth_Iterator are not equivalent.
| depth_iterator | The Depth_Iterator to compare against. |
References Parameter::operator==().
| bool operator== | ( | const Aggregate::iterator & | list_iterator | ) | const [inline] |
Tests if the current position of this Depth_Iterator and an Aggregate list iterator are equivalent.
WARNING: This method may result in undefined behaviour if the list_iterator argument is not bound to the same Aggregate vector that the Depth_Iterator current position iterator is bound to. If this is possible a Depth_Iterator should first be constructed from the list_iterator before the equality test is made.
| list_iterator | The Aggregate::iterator to compare against. |
| bool operator!= | ( | const Aggregate::iterator & | list_iterator | ) | const [inline] |
Tests if the current position of this Depth_Iterator and an Aggregate list iterator are not equivalent.
| list_iterator | The Aggregate::iterator to compare against. |
References Parameter::operator==().
| bool operator< | ( | const Depth_Iterator & | depth_iterator | ) | const |
Tests if the position of this Depth_Iterator is less than the position of another Depth_Iterator.
| depth_iterator | The Depth_Iterator to compare against. |
| bool operator< | ( | const Aggregate::iterator & | list_iterator | ) | const |
Tests if the current position of this Depth_Iterator is less than the position of an Aggregate list iterator.
A copy of this Depth_Iterator is incremented forward searching for the list iterator position.
Note: This is a random-access iterator operator that does not occur in constant time. This is always more, often much more, expensive that the == (or !=) test. The latter should be used whenever possible (e.g. in loop conditions).
| list_iterator | The Aggregate::iterator to compare against. |
| bool operator> | ( | const Depth_Iterator & | depth_iterator | ) | const [inline] |
Tests if the position of this Depth_Iterator is greater than the position of another Depth_Iterator.
| depth_iterator | The Depth_Iterator to compare against. |
| bool operator<= | ( | const Depth_Iterator & | depth_iterator | ) | const [inline] |
Tests if the position of this Depth_Iterator is less than or equal to the position of another Depth_Iterator.
| depth_iterator | The Depth_Iterator to compare against. |
| bool operator>= | ( | const Depth_Iterator & | depth_iterator | ) | const [inline] |
Tests if the position of this Depth_Iterator is greater than or equal to the position of another Depth_Iterator.
| depth_iterator | The Depth_Iterator to compare against. |
| bool operator> | ( | const Aggregate::iterator & | list_iterator | ) | const [inline] |
Tests if the position of this Depth_Iterator is greater than the position of an Aggregate list iterator.
| list_iterator | The Aggregate::iterator to compare against. |
| bool operator<= | ( | const Aggregate::iterator & | list_iterator | ) | const [inline] |
Tests if the position of this Depth_Iterator is less than or equal to the position of an Aggregate list iterator.
| list_iterator | The Aggregate::iterator to compare against. |
| bool operator>= | ( | const Aggregate::iterator & | list_iterator | ) | const [inline] |
Tests if the position of this Depth_Iterator is greater than or equal to the position of an Aggregate list iterator.
| list_iterator | The Aggregate::iterator to compare against. |
1.7.4