The e4_VertexVisitor Class

The e4_VertexVisitor class enables a program to iterate over a collection of vertices selected from a storage. The class provides methods to retrieve the currently visited vertex and to advance to the next vertex to be visited, and to determine whether there are more vertices to be visited. The e4_VertexVisitor class provides a variety of flexible methods to select and filter the vertices to visit, according to user defined criteria. The order in which vertices that match the selection criteria are visited is implementation dependent.

The following code snippet demonstrates a typical use of the e4_VertexVisitor class:

e4_Storage s("mystorage", E4_METAKIT);
e4_Node n;
e4_Vertex v;
...
if (!s.GetRootNode(n)) {...}
if (!n.GetVertexRef("foo", 1, v)) {...}
...
e4_Vertex cv;
e4_VertexVisitor vv(v);
while (vv.CurrentVertexAndAdvance(cv)) {
    if (!cv.IsValid()) {...}
    if (cv == v) {
        cerr << "Found our vertex, "
             << v.GetName() << ", "
             << cv.GetName() << ".\n";
    }
}

The vertex visitor vv is initialized to visit all the vertices in the node containing the vertex v. We iterate over all the vertices in turn, and when we reach the vertex v that was used to initialize vv, we print a message to stderr.

Each instance of e4_VertexVisitor has a specific visit method, defined here, that determines its behavior. The value currently in effect is returned by the method VisitMethod().

The e4_VertexVisitor class provides the following methods:

e4_VertexVisitor Methods and Constructors

e4_VertexVisitor() Default constructor. Creates an instance of e4_VertexVisitor that is initially invalid, because it is not associated with any storage and does not have a current vertex being visited.

e4_VertexVisitor(const e4_VertexVisitor &referrer) Copying constructor. Creates an instance of e4_VertexVisitor that will visit the same vertices as referrer, and in the same order.

e4_VertexVisitor(const e4_Storage &s) Constructor that creates an instance of e4_VertexVisitor that will visit all attached vertices in the storage s. The visit method is E4_VMSTORAGE.

e4_VertexVisitor(const e4_Storage &s, e4_DetachChoice dc) Constructor that creates an instance of e4_VertexVisitor that will visit all vertices selected according to dc in the storage s. The visit method is E4_VMSTORAGE.

e4_VertexVisitor(const e4_Storage &s, const char *nm, e4_VertexType vt) Constructor that creates an instance of e4_VertexVisitor that will visit all attached vertices in the storage s that have the name nm and vertex type vt. If nm is NULL then vertices with any name are visited, and if vt is E4_VTUNKNOWN then vertices with a value of any type are visited. Either way, the visit method is E4_VMSTORAGE.

e4_VertexVisitor(const e4_Storage &s, e4_DetachChoice dc, const char *nm, e4_VertexType vt) Constructor that creates an instance of e4_VertexVisitor that will visit all vertices selected according to dc in the storage s that have the name nm and vertex type vt. If nm is NULL then vertices with any name are visited, and if vt is E4_VTUNKNOWN then vertices with a value of any type are visited. Either way, the visit method is E4_VMSTORAGE.

e4_VertexVisitor(const e4_Node &n) Constructor that creates an instance of e4_VertexVisitor that will visit all vertices in the node n in increasing rank order. The visit method is E4_VMNODE. Because all vertices visited must be contained within n, this visitor only visits attached vertices.

e4_VertexVisitor(const e4_Node &n, const char *nm, e4_VertexType vt) Constructor that creates an instance of e4_VertexVisitor that will visit all vertices in the node n that have the name nm and vertex type vt in increasing rank order. If nm is NULL the vertices with any name are visited, and if vt is E4_VTUNKNOWN then vertices with a value of any type are visited. Either way, the visit method is E4_VMNODE.

e4_VertexVisitor(const e4_Node &child, const e4_Node &parent, e4_DetachChoice dc) Constructor that creates an instance of e4_VertexVisitor that will visit vertices that have the child node as their value. If parent is a valid node then the visitor will visit only vertices in parent that have child as their value. If parent is invalidNode then the visitor will visit all vertices that are selected by dc and that have child as their value.

e4_VertexVisitor(const e4_Node &child, const e4_Node &parent, e4_DetachChoice dc, const char *nm) Constructor that creates an instance of e4_VertexVisitor that will visit vertices with name nm that have the child node as their value. If parent is a valid node then the visitor will visit only vertices in parent that have child as their value. If parent is invalidNode then the visitor will visit all vertices that are selected by dc and that have child as their value.

e4_VertexVisitor(const e4_Vertex &v) Constructor that creates an instance of e4_VertexVisitor that will visit vertices starting with v in the node containing v, in increasing rank order. The visit method is E4_VMNODE.

e4_VertexVisitor(const e4_Vertex &v, const char *nm, e4_VertexType vt) Constructor that creates an instance of e4_VertexVisitor that will visit vertices starting with v in the node containing v that have the name nm and vertex type vt in increasing rank order. If nm is NULL then vertices with any name are visited, and if vt is E4_VTUNKNOWN then vertices with a value of any type are visited. Either way, the visit method is E4_VMNODE.

e4_VertexVisitor(const e4_Vertex &v, const char *nm, e4_VertexType vt, e4_VisitMethod vm) Constructor that creates an instance of e4_VertexVisitor that will visit vertices starting with v that have the name nm and vertex type vt, according to the visit method vm. If vm is E4_VMUNKNOWN or E4_VMSTORAGE, v and all vertices that are contained within the storage containing vthat occur after v in the implementation dependent visit order are visited. If vm is VM_NODE, v and vertices with rank higher than v are visited. If vm is VM_NODERANDOM, v and vertices occurring after v in the implementation dependent visit order are visited. If nm is NULL, vertices with any name are visited, and if vt is E4_VTUNKNOWN then vertices with a value of any type are visited. Practically, E4_VMNODE is probably the most useful visit method. If the visit method is E4_VMUNKNOWN or E4_VMSTORAGE and v is detached, the visitor will visit only detached vertices. If the visit method is E4_VMUNKNOWN or E4_VMSTORAGE and v is attached, the visitor visits only attached vertices.

~e4_VertexVisitor() Destructor.

e4_VertexVisitor &operator=(const e4_VertexVisitor &referrer) Assignment operator. Makes this instance visit the same vertices as referrer and in the same order.

bool operator==(const e4_VertexVisitor &comp) Returns true if this and comp are equal e4_VertexVisitor instances. Instances are considered equal if they visit the same set of vertices and are at the same position in their itinerary. All invalid instances are equal.

bool operator!=(const e4_VertexVisitor &comp) Returns true if this and comp are not equal. All invalid instances are equal.

bool IsDone() Returns true if this instance of e4_VertexVisitor has no more vertices to visit or if the current vertex being visited is invalid.

bool IsValid() Returns true if this instance of e4_VertexVisitor is valid. An instance is valid if it has a current vertex being visited and that vertex is valid.

bool CurrentVertex(e4_Vertex &v) Returns true if the vertex currently being visited is successfully retrieved in v and the vertex is valid. This method will return true and retrieve the currently visited valid vertex even after IsDone() returns true.

bool NextVertex(e4_Vertex &v) Returns true if the visitor is successfully advanced to the next vertex to be visited and that vertex is valid and is successfully retrieved in v.

bool CurrentVertexAndAdvance(e4_Vertex &v) Returns true if the vertex currently being visited is successfully retrieved in v the vertex is valid. An attempt is made to advance the visitor to the next vertex to be visited; if that fails, subsequent calls to IsDone() return true.

bool SetStorage(const e4_Storage &s) Returns true if the visitor is successfully reset to visit all attached vertices defined in the storage s.

bool SetStorage(const e4_Storage &s, e4_DetachChoice dc) Returns true if the visitor is successfully reset to visit all vertices selected according to dc that are defined in the storage s.

bool SetStorage(const e4_Storage &s, const char *nm, e4_VertexType vt) Returns true if the visitor is successfully reset to visit all attached vertices that have the same name and vertex type as the supplied arguments, within the storage s.

bool SetStorage(const e4_Storage &s, const char *nm, e4_VertexType vt, e4_DetachChoice dc) Returns true if the visitor is successfully reset to visit all vertices selected according to dc in the storage s that have the given name and vertex type.

bool SetNode(const e4_Node &n) Returns true if the visitor is successfully reset to visit all the vertices in the node n. Because visited vertices must be contained within the node n, the visitor only visits attached vertices.

bool SetNode(const e4_Node &n, const char *nm, e4_VertexType vt) Returns true if the visitor is successfully reset to visit all the vertices in the node n that have the given name and vertex type.

bool SetVertex(const e4_Vertex &v) Returns true if the visitor is successfully reset to visit all vertices of the same kind as v within the storage containing the vertex v. If v is detached, the visitor visits only detached vertices. Otherwise it will visit only attached vertices.

bool SetVertex(const e4_Vertex &v, bool usevertexname, bool usevertextype) Returns true if the visitor is successfully reset to visit all vertices of the same kind as v within the storage containing the vertex v. If v is detached, the visitor visits only detached vertices. Otherwise it will visit only attached vertices. If usevertexname is true, only vertices with the same name as v are visited. If usevertextype is true, only vertices with the same vertex type as v are visited.

bool SetVertex(const e4_Vertex &v, bool usevertexname, bool usevertextype, e4_VisitMethod vm) Returns true if the visitor is successfully reset to visit vertices within the storage containing v. If vm is E4_VMUNKNOWN or E4_VMSTORAGE, v and all vertices that are contained within the storage containing v that occur after v in the implementation dependent visit order are visited. If vm is VM_NODE, v and vertices with rank higher than v in the node containing v are visited. If vm is VM_NODERANDOM, v and vertices occurring after v in the implementation dependent visit order which also occur in the node containing v are visited. If usevertexname is false, vertices with any name are visited, and if usevertextype is false then vertices with a value of any type are visited. Otherwise only vertices with vertex name or vertex type identical to v are visited. Practically, E4_VMNODE is probably the most useful visit method. If the visit method is E4_VMUNKNOWN or E4_VMSTORAGE and v is detached, the visitor will visit only detached vertices. If the visit method is E4_VMUNKNOWN or E4_VMSTORAGE and v is attached, the visitor visits only attached vertices.

bool SetParentVertex(const e4_Node &child, const e4_Node &parent, e4_DetachChoice dc, const char *nm) Returns true if the visitor is successfully reset to visit vertices that have the child node as their value. If parent is a valid node, the visitor will visit only vertices within the parent node that have child as their value. If parent is invalidNode, the visitor will visit all vertices that have child as their value that are selected by dc. The set of vertices is further constrained by the nm argument, which, if non-NULL, will cause the visitor to only visit vertices with that name.


e4_VertexVisitor()	Default constructor. Creates an instance of e4_VertexVisitor that is initially invalid, because it is not associated with any storage and does not have a current vertex being visited.
e4_VertexVisitor(const e4_VertexVisitor &referrer)	Copying constructor. Creates an instance of e4_VertexVisitor that will visit the same vertices as referrer, and in the same order.
e4_VertexVisitor(const e4_Storage &s)	Constructor that creates an instance of e4_VertexVisitor that will visit all attached vertices in the storage s. The visit method is E4_VMSTORAGE.
e4_VertexVisitor(const e4_Storage &s, e4_DetachChoice dc)	Constructor that creates an instance of e4_VertexVisitor that will visit all vertices selected according to dc in the storage s. The visit method is E4_VMSTORAGE.
e4_VertexVisitor(const e4_Storage &s, const char *nm, e4_VertexType vt)	Constructor that creates an instance of e4_VertexVisitor that will visit all attached vertices in the storage s that have the name nm and vertex type vt. If nm is NULL then vertices with any name are visited, and if vt is E4_VTUNKNOWN then vertices with a value of any type are visited. Either way, the visit method is E4_VMSTORAGE.
e4_VertexVisitor(const e4_Storage &s, e4_DetachChoice dc, const char *nm, e4_VertexType vt)	Constructor that creates an instance of e4_VertexVisitor that will visit all vertices selected according to dc in the storage s that have the name nm and vertex type vt. If nm is NULL then vertices with any name are visited, and if vt is E4_VTUNKNOWN then vertices with a value of any type are visited. Either way, the visit method is E4_VMSTORAGE.
e4_VertexVisitor(const e4_Node &n)	Constructor that creates an instance of e4_VertexVisitor that will visit all vertices in the node n in increasing rank order. The visit method is E4_VMNODE. Because all vertices visited must be contained within n, this visitor only visits attached vertices.
e4_VertexVisitor(const e4_Node &n, const char *nm, e4_VertexType vt)	Constructor that creates an instance of e4_VertexVisitor that will visit all vertices in the node n that have the name nm and vertex type vt in increasing rank order. If nm is NULL the vertices with any name are visited, and if vt is E4_VTUNKNOWN then vertices with a value of any type are visited. Either way, the visit method is E4_VMNODE.
e4_VertexVisitor(const e4_Node &child, const e4_Node &parent, e4_DetachChoice dc)	Constructor that creates an instance of e4_VertexVisitor that will visit vertices that have the child node as their value. If parent is a valid node then the visitor will visit only vertices in parent that have child as their value. If parent is invalidNode then the visitor will visit all vertices that are selected by dc and that have child as their value.
e4_VertexVisitor(const e4_Node &child, const e4_Node &parent, e4_DetachChoice dc, const char *nm)	Constructor that creates an instance of e4_VertexVisitor that will visit vertices with name nm that have the child node as their value. If parent is a valid node then the visitor will visit only vertices in parent that have child as their value. If parent is invalidNode then the visitor will visit all vertices that are selected by dc and that have child as their value.
e4_VertexVisitor(const e4_Vertex &v)	Constructor that creates an instance of e4_VertexVisitor that will visit vertices starting with v in the node containing v, in increasing rank order. The visit method is E4_VMNODE.
e4_VertexVisitor(const e4_Vertex &v, const char *nm, e4_VertexType vt)	Constructor that creates an instance of e4_VertexVisitor that will visit vertices starting with v in the node containing v that have the name nm and vertex type vt in increasing rank order. If nm is NULL then vertices with any name are visited, and if vt is E4_VTUNKNOWN then vertices with a value of any type are visited. Either way, the visit method is E4_VMNODE.
e4_VertexVisitor(const e4_Vertex &v, const char *nm, e4_VertexType vt, e4_VisitMethod vm)	Constructor that creates an instance of e4_VertexVisitor that will visit vertices starting with v that have the name nm and vertex type vt, according to the visit method vm. If vm is E4_VMUNKNOWN or E4_VMSTORAGE, v and all vertices that are contained within the storage containing vthat occur after v in the implementation dependent visit order are visited. If vm is VM_NODE, v and vertices with rank higher than v are visited. If vm is VM_NODERANDOM, v and vertices occurring after v in the implementation dependent visit order are visited. If nm is NULL, vertices with any name are visited, and if vt is E4_VTUNKNOWN then vertices with a value of any type are visited. Practically, E4_VMNODE is probably the most useful visit method. If the visit method is E4_VMUNKNOWN or E4_VMSTORAGE and v is detached, the visitor will visit only detached vertices. If the visit method is E4_VMUNKNOWN or E4_VMSTORAGE and v is attached, the visitor visits only attached vertices.
~e4_VertexVisitor()	Destructor.
e4_VertexVisitor &operator=(const e4_VertexVisitor &referrer)	Assignment operator. Makes this instance visit the same vertices as referrer and in the same order.
bool operator==(const e4_VertexVisitor &comp)	Returns true if this and comp are equal e4_VertexVisitor instances. Instances are considered equal if they visit the same set of vertices and are at the same position in their itinerary. All invalid instances are equal.
bool operator!=(const e4_VertexVisitor &comp)	Returns true if this and comp are not equal. All invalid instances are equal.

bool IsDone()	Returns true if this instance of e4_VertexVisitor has no more vertices to visit or if the current vertex being visited is invalid.
bool IsValid()	Returns true if this instance of e4_VertexVisitor is valid. An instance is valid if it has a current vertex being visited and that vertex is valid.
bool CurrentVertex(e4_Vertex &v)	Returns true if the vertex currently being visited is successfully retrieved in v and the vertex is valid. This method will return true and retrieve the currently visited valid vertex even after IsDone() returns true.
bool NextVertex(e4_Vertex &v)	Returns true if the visitor is successfully advanced to the next vertex to be visited and that vertex is valid and is successfully retrieved in v.
bool CurrentVertexAndAdvance(e4_Vertex &v)	Returns true if the vertex currently being visited is successfully retrieved in v the vertex is valid. An attempt is made to advance the visitor to the next vertex to be visited; if that fails, subsequent calls to IsDone() return true.
bool SetStorage(const e4_Storage &s)	Returns true if the visitor is successfully reset to visit all attached vertices defined in the storage s.
bool SetStorage(const e4_Storage &s, e4_DetachChoice dc)	Returns true if the visitor is successfully reset to visit all vertices selected according to dc that are defined in the storage s.
bool SetStorage(const e4_Storage &s, const char *nm, e4_VertexType vt)	Returns true if the visitor is successfully reset to visit all attached vertices that have the same name and vertex type as the supplied arguments, within the storage s.
bool SetStorage(const e4_Storage &s, const char *nm, e4_VertexType vt, e4_DetachChoice dc)	Returns true if the visitor is successfully reset to visit all vertices selected according to dc in the storage s that have the given name and vertex type.
bool SetNode(const e4_Node &n)	Returns true if the visitor is successfully reset to visit all the vertices in the node n. Because visited vertices must be contained within the node n, the visitor only visits attached vertices.
bool SetNode(const e4_Node &n, const char *nm, e4_VertexType vt)	Returns true if the visitor is successfully reset to visit all the vertices in the node n that have the given name and vertex type.
bool SetVertex(const e4_Vertex &v)	Returns true if the visitor is successfully reset to visit all vertices of the same kind as v within the storage containing the vertex v. If v is detached, the visitor visits only detached vertices. Otherwise it will visit only attached vertices.
bool SetVertex(const e4_Vertex &v, bool usevertexname, bool usevertextype)	Returns true if the visitor is successfully reset to visit all vertices of the same kind as v within the storage containing the vertex v. If v is detached, the visitor visits only detached vertices. Otherwise it will visit only attached vertices. If usevertexname is true, only vertices with the same name as v are visited. If usevertextype is true, only vertices with the same vertex type as v are visited.
bool SetVertex(const e4_Vertex &v, bool usevertexname, bool usevertextype, e4_VisitMethod vm)	Returns true if the visitor is successfully reset to visit vertices within the storage containing v. If vm is E4_VMUNKNOWN or E4_VMSTORAGE, v and all vertices that are contained within the storage containing v that occur after v in the implementation dependent visit order are visited. If vm is VM_NODE, v and vertices with rank higher than v in the node containing v are visited. If vm is VM_NODERANDOM, v and vertices occurring after v in the implementation dependent visit order which also occur in the node containing v are visited. If usevertexname is false, vertices with any name are visited, and if usevertextype is false then vertices with a value of any type are visited. Otherwise only vertices with vertex name or vertex type identical to v are visited. Practically, E4_VMNODE is probably the most useful visit method. If the visit method is E4_VMUNKNOWN or E4_VMSTORAGE and v is detached, the visitor will visit only detached vertices. If the visit method is E4_VMUNKNOWN or E4_VMSTORAGE and v is attached, the visitor visits only attached vertices.
bool SetParentVertex(const e4_Node &child, const e4_Node &parent, e4_DetachChoice dc, const char *nm)	Returns true if the visitor is successfully reset to visit vertices that have the child node as their value. If parent is a valid node, the visitor will visit only vertices within the parent node that have child as their value. If parent is invalidNode, the visitor will visit all vertices that have child as their value that are selected by dc. The set of vertices is further constrained by the nm argument, which, if non-NULL, will cause the visitor to only visit vertices with that name.