PVL: Parameter Value Language
|
|
PVL: Parameter Value Language
|
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...
#include <Value.hh>
Public Member Functions | |
| Array * | array () const |
| Gets the current Array context. | |
| Depth_Iterator (const Array &array) | |
| Constructs a Depth_Iterator for an Array. | |
| Depth_Iterator () | |
| Constructs a Depth_Iterator without a root Array. | |
| Depth_Iterator (const Array::iterator &list_iterator) | |
| Construct a Depth_Iterator from a normal Array 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 Array::iterator () | |
| Converts the Depth_Iterator to a Value_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 Array::iterator &list_iterator) const |
| Tests if the current position of this Depth_Iterator and an Array list iterator are not equivalent. | |
| Value & | operator* () const |
| Gets a reference to the Value 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 Value position. | |
| Depth_Iterator | operator++ (int) |
| Post-increments forward to the next Value position. | |
| Depth_Iterator & | operator+= (int distance) |
| Relocates the current position by the specified distance. | |
| int | operator- (const Array::iterator &list_iterator) const |
| Get the distance between this Depth_Iterator and an Array 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 Value position. | |
| Depth_Iterator & | operator-- () |
| Pre-decrements backward to the previous Value position. | |
| Depth_Iterator & | operator-= (int distance) |
| Relocates the current position by the specified distance. | |
| Value * | operator-> () const |
| Gets a pointer to the Value at the current position. | |
| bool | operator< (const Array::iterator &list_iterator) const |
| Tests if the current position of this Depth_Iterator is less than the position of an Array 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 Array::iterator &list_iterator) const |
| Tests if the position of this Depth_Iterator is less than or equal to the position of an Array 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 Array::iterator &list_iterator) |
| Assigns a Value list iterator to this Depth_Iterator. | |
| bool | operator== (const Array::iterator &list_iterator) const |
| Tests if the current position of this Depth_Iterator and an Array 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 Array::iterator &list_iterator) const |
| Tests if the position of this Depth_Iterator is greater than the position of an Array list iterator. | |
| bool | operator>= (const Array::iterator &list_iterator) const |
| Tests if the position of this Depth_Iterator is greater than or equal to the position of an Array 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. | |
| Value & | operator[] (int offset) const |
| Array-style access to the Value at an offset from the current position. | |
| Depth_Iterator & | previous_sibling () |
| Array * | root () const |
| Gets the root Array. | |
A Depth_Iterator is a bidirectional iterator over an Array's Value list and, depth-first, over the Value list of each Array encountered.
The Depth_Iterator operates like a normal breadth-only interator for a Value list until it encounters an Array in the list. When it is incremented from an Array position it decends into the Array, and only returns to the next Value in the current list when the end of the Value list of the Array has been reached. This process is recursive resulting in a depth-first traversal of the entire Array Value hierarchy. The mechanism operates similarly when decrementing by descending into each Array and reverse iterating its Value list, then returning to the current Value list when the beginning of the Array's list has been reached.
A Depth_Iterator is associated with a specific Array which it knows as its root Array. It will not ascend into the Value list of the root Array's parent. Like other container iterators, all positions are expected to be for valid Values except the final end position of the root Array; reverse iteration will not go beyond the initial begin position of the root Array.
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 Array.
This Depth_Iterator is invalid until it is assigned a valid iterator.
| Depth_Iterator | ( | const Array & | array | ) | [explicit] |
Constructs a Depth_Iterator for an Array.
The initial position of this Depth_Iterator is the beginning of the Array's Value list.
| array | The root Array. |
| Depth_Iterator | ( | const Array::iterator & | list_iterator | ) | [inline] |
Construct a Depth_Iterator from a normal Array iterator.
Warning: The iterator must be valid; i.e. it must refer to a Value. An end iterator is not valid. Use the end_depth method to get the iterator for the end of a Depth_Iterator.
| operator Array::iterator | ( | ) | [inline] |
Converts the Depth_Iterator to a Value_List iterator.
| Array* root | ( | ) | const |
Gets the root Array.
| Array* array | ( | ) | 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 Array.
| Error | If this Depth_Iterator is invalid (it doesn't have a root Array). |
| Depth_Iterator& operator= | ( | const Array::iterator & | list_iterator | ) |
Assigns a Value list iterator to this Depth_Iterator.
If the Depth_Iterator is currently positioned at the same Value as the list iterator nothing happens.
If the Depth_Iterator and list iterator are positioned in the Value list of the same Array, 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 Value list, and the list is not in the root Array, 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 Array, 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 Value_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 Array hierarchy, a non-root Array is encountered without a parent (this should not happen unless the Array hierachy was inappropriately modified during traversal). |
| Value& operator* | ( | ) | const [inline] |
| Value* operator-> | ( | ) | const [inline] |
| Depth_Iterator& operator++ | ( | ) |
Pre-increments forward to the next Value position.
If the Value at the current position is a non-empty Array, 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 Array's list.
If the Value at the current position is an Assignment or an empty Array, then the current position is moved forward to the next position in the Value list. If this position is the end of the Value list, and the list is not for the root Array, then the previous position in the parent's Value list is popped from the stack to the current position and it is moved forward again. Ascending up the Array hierarchy continues in this way until a non-end list position is found, or the end of the root Array 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 Array hierachy of the Depth_Iterator's current position is the primary issue. Each iterator, saved on the stack, to a previous position in the Array heirarchy must remain consistent; the location of its Array in the Value list must remain unchanged and the parent of the Array must remain unchanged. Changes to the current Value 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 Array. |
| Error | If the Depth_Iterator is invalid (doesn't have a root Array). An Error will also be thrown if, on attempting to ascend the Array hierarchy, a non-root Array is encountered without a parent (this should not happen unless the Array hierachy was inappropriately modified during traversal). |
| Depth_Iterator& next_sibling | ( | ) |
| Depth_Iterator operator++ | ( | int | ) |
Post-increments forward to the next Value position.
| Depth_Iterator& operator-- | ( | ) |
Pre-decrements backward to the previous Value position.
If the current position is not the beginning of a Value list, the current position moves to the previous Value in the list. If this Value is a non-empty Array, the current position is pushed onto a LIFO (last-in-first-out) stack and then the current position moves to the last entry (the Value immediately preceeding the end position) in the child Array's list. If this Value is a non-empty Array then the currrent positionis pushed onto the stack again and the current position becomes the last entry in this Array. This back-down cycle continues until an Assignment, or empty Array, Value is encountered.
If the current position is the beginning of a Value list, and it is not the root Array's Value list, then the previous position in the parent's Value list is popped from the stack to the current position.
| Out_of_Range | If the current position is the beginning of the root Array. |
| Error | If the Depth_Iterator is invalid (doesn't have a root Array). An Error will also be thrown if, on attempting to ascend the Array hierarchy, a non-root Array is encountered without a parent (this should not happen unless the Array hierachy was inappropriately modified during traversal). |
| Depth_Iterator& previous_sibling | ( | ) |
| Depth_Iterator operator-- | ( | int | ) |
Post-decrements backward to the previous Value position.
| Value& operator[] | ( | int | offset | ) | const |
Array-style access to the Value 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 Value 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 Array::iterator & | list_iterator | ) | const |
Get the distance between this Depth_Iterator and an Array 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 Array::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. |
| bool operator== | ( | const Array::iterator & | list_iterator | ) | const [inline] |
Tests if the current position of this Depth_Iterator and an Array list iterator are equivalent.
WARNING: This method may result in undefined behaviour if the list_iterator argument is not bound to the same Array 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 Array::iterator to compare against. |
| bool operator!= | ( | const Array::iterator & | list_iterator | ) | const [inline] |
Tests if the current position of this Depth_Iterator and an Array list iterator are not equivalent.
| list_iterator | The Array::iterator to compare against. |
| 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 Array::iterator & | list_iterator | ) | const |
Tests if the current position of this Depth_Iterator is less than the position of an Array 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 Array::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 Array::iterator & | list_iterator | ) | const [inline] |
Tests if the position of this Depth_Iterator is greater than the position of an Array list iterator.
| list_iterator | The Array::iterator to compare against. |
| bool operator<= | ( | const Array::iterator & | list_iterator | ) | const [inline] |
Tests if the position of this Depth_Iterator is less than or equal to the position of an Array list iterator.
| list_iterator | The Array::iterator to compare against. |
| bool operator>= | ( | const Array::iterator & | list_iterator | ) | const [inline] |
Tests if the position of this Depth_Iterator is greater than or equal to the position of an Array list iterator.
| list_iterator | The Array::iterator to compare against. |
1.7.4