The e4_Node class provides the abstraction of a persistent node in a graph. A node may be marked by one or more markers, and may be the value of one or more vertices in other nodes. the e4_Node class provides methods to retrieve any marks that mark this node, and to retrieve any nodes that contain vertices with this node as their value. Nodes that contain a vertex with this node as its value are parents of this node. Each node is identified by an integer that is unique within the storage containing this node. The underlying node representation is reference counted and its memory is freed automatically when the last reference to it is discarded.
Instances of e4_Node are not constructed directly by a user program. Instead, they are obtained as the output value of various operations on other elements. For example:
If the GetMarkedNode method call succeeds, n is assigned to an e4_Node instance representing the node marked by the marker mymarker. Any number of nodes can be held by a user program, limited only by the resources available to the program.e4_Storage s("mystorage", E4_METAKIT); ... e4_Marker m; ... if (!s.GetMarker("mymarker", m)) { printf("Couldn't get mymarker!\n"); } ... e4_Node n; ... if (!m.GetMarkedNode(n)) { printf("Couldn't get marked node of marker \"mymarker\"!\n"); }
A node can be marked by one or more markers (instances of e4_Marker). The e4Graph package provides APIs for obtaining markers marking a node, for adding new markers to a node and for removing markers from the set that is marking a node.
A node can be the value of one or more vertices, in one or more nodes. The nodes containing the vertices whose value is a given node are the parents of that node. The e4Graph package provides APIs for obtaining the parent nodes of a node, for adding new parents to a node and for removing a node from the set of parents of a node. Circular graphs are allowed, and a node can be a parent of itself. Managing this circularity is the responsibility of the programmer using the e4_Graph package.
A node is said to be unreachable if no markers mark it and the node is not the value of any vertex. An unreachable node and all its recursively unreachable vertices are automatically removed from the storage. Instances of e4_Node and e4_Vertex that refer to unreachable nodes and vertices are invalid.
The e4_Node class provides assignment and comparison operators. When one instance of e4_node is assigned to another, they now refer to the same node. The comparison operators allow a user program to determine whether two instances of e4_Node refer to the same node:
The global variable invalidNode refers to a constant instance of e4_Node that is guaranteed to be invalid. You can assign this instance to a local e4_Node variable to discard the reference it contains to another node, as shown in the following example:e4_Node n1, n2; ... if (!m.GetMarkedNode(n1)) { ... } n2 = n1; ... if (n1 == n2) { printf("They are one and the same.\n"); }
The assignment of invalidNode to n causes the reference count for the node marked by the marker stored in m to drop to zero, and its memory is freed. Note that modifications to this node are written to persistent storage only when the storage containing this node is committed. Remember to assign invalidNode to instances of e4_Node embedded within heap allocated structures before these structures are freed, to ensure that the reference count of nodes referenced by the embedded instances is correct.e4_Node n; ... if (!m.GetMarkedNode(n)) { ... } ... n = invalidNode; if (n.IsValid()) { printf("Something fishy here!\n"); }
When the storage containing a node is closed, any e4_Node instances referring to that node become invalid. Instances may also become invalid if they are deleted from the storage or become unreachable from any other node or marker in the storage.
A node can contain any number of vertices; the node is said to be the originating node for these vertices. Vertices are named and ranked in order of occurrence, and each vertex has a type and value. More than one vertex with the same name can occur in a given node, and vertex are identified either by rank or by name and occurrence index. Rank is one-based, that is, the first vertex in a node has rank 1. The e4_Node class provides a wide range of methods to create, retrieve, delete and modify vertices. In the following example, a new vertex named barney is added with an integer value of 42 as the first vertex in a node, and then the 64-bit floating point value of the third vertex named joe is retrieved:
Vertices can also be addressed, added, modified, retrieved and deleted by rank:e4_Node n; int rank; double dd; ... if (!n.AddVertex("barney", E4_IOFIRST, rank, 42)) { printf("Couldn't add a vertex named \"barney\".\n"); } ... if (!n.GetVertex("joe", 3, dd)) { printf("Couldn't retrieve third \"joe\" vertex.\n"); }
When setting a vertex to a NULL terminated string value, you can set the value to NULL by passing a NULL as the value to be assigned. Similarly, you can pass NULL to assign a binary uninterpreted value of NULL; in that case you must also supply a length of zero for the value being assigned. For example, the following code assigns the string value NULL to a vertex named bob and a zero length binary value to the vertex named joey:e4_Node n; int rank = 7; int vi; ... if (!n.AddVertex("bobby", E4_IOAT, rank, 42)) { printf("Couldn't add a vertex at rank %d.\n", rank); } ... if (!n.GetVertexByRank(7, vi)) { printf("Couldn't retrieve value of vertex ranked 7.\n"); } if (vi != 42) { printf("Oops, got %d instead of 42!\n", vi); } ... if (!n.SetVertexByRank(7, (double) 3.14)) { printf("Couldn't set value of vertex ranked 7.\n"); } .. if (!n.DeleteVertexByRank(7)) { printf("Couldn't delete vertex ranked 7.\n"); }
The e4_Node class provides methods to obtain the parents of a node and the number of references a specific parent has to this node. If the current node has no parents, the IsRoot method returns true. Methods are also provided to retrieve instances of e4_Marker representing the markers marking this node, and an instance of e4_Storage for the storage containing this node.e4_Node n; int rank; ... if (!n.SetVertex("bob", (const char *) NULL)) { ... } if (!n.SetVertex("joey", (const void *) NULL, 0)) { ... }
e4_Node() | Default constructor. Returns an invalid node. |
e4_Node(const e4_Node &ref) | Copying constructor. Returns an instance of e4_Node whose state is the same as ref. |
~e4_Node() | Destructor. Decrements the reference count for the underlying node representation and if this is the last reference, its memory is automatically freed. |
e4_Node & operator=(const e4_Node ref) | Assignment operator. Makes the state of this the same as ref and returns this. |
bool operator==(const e4_Node &comp) const | Returns true if comp and this refer to the same node or if both are invalid, false otherwise. |
bool operator!=(const e4_Node &comp) const | Returns false if comp and this refer to the same node, false otherwise. |
int VertexCount() const | Returns the number of vertices in this node. |
bool SetVertex(const char *name, int v) const | Sets the first vertex, in rank order, with name name to the integer value v. The operation returns true and succeeds if a vertex with the given name already exists, false otherwise. |
bool SetVertex(const char *name, double v) const | Sets the first vertex, in rank order, with name name to the 64-bit floating point value v. The operation returns true and succeeds if a vertex with the given name already exists, false otherwise. |
bool SetVertex(const char *name, const char *v) const | Sets the first vertex, in rank order, with name name to the NULL terminated string value v. The operation returns true and succeeds if a vertex with the given name already exists, false otherwise. |
bool SetVertex(const char *name, const void *bytes, int nbytes) const | Sets the first vertex, in rank order, with name name to the binary value bytes of length nbytes bytes. The operation returns true and succeeds if a vertex with the given name already exists, false otherwise. |
bool SetVertex(const char *name, e4_Node n) const | Set the first vertex, in rank order, with name name to the node n. This operation makes the current node a parent of n. The operation succeeds if n is valid and in the same storage as this node, and if a vertex with the given name already exists, false otherwise. |
bool SetNode(const char *name, e4_Node &n) const | Sets the first vertex, in rank order, with name name to a new node. The node is also returned in n if the operation succeeds, when the vertex already exists. Otherwise n is not modified and the operation returns false. |
bool SetNthVertex(const char *name, int nth, int v) const | Sets the nth vertex, in rank order, with name name to the integer value v. |
bool SetNthVertex(const char *name, int nth, double v) const | Sets the nth vertex, in rank order, with name name to the 64-bit floating point value v. |
bool SetNthVertex(const char *name, int nth, const char *v) const | Sets the nth vertex, in rank order, with name name to the NULL terminated string value v. |
bool SetNthVertex(const char *name, int nth, const void *bytes, int nbytes) const | Sets the nth vertex, in rank order, with name name to the binary value bytes of length nbytes bytes. |
bool SetNthVertex(const char *name, int nth, e4_Node n) const | Sets the nth vertex, in rank order, with name name to the node n. The current node becomes a parent of n. |
bool SetNthNode(const char *name, int nth, e4_Node &n) const | Sets the nth vertex, in rank order, with name name to a new node. The new node is also returned in n. |
bool SetVertexByRank(int rank, int v) const | Sets the vertex whose rank is rank to the integer value v. Succeeds and returns true if the node contains at least rank vertices. |
bool SetVertexByRank(int rank, double v) const | Sets the vertex whose rank is rank to the 64-bit floating point value v. Succeeds and returns true if the node contains at least rank vertics. |
bool SetVertexByRank(int rank, const char *v) const | Sets the vertex whose rank is rank to the NULL terminated string value v. Succeeds and returns true if the node contains at least rank vertices. |
bool SetVertexByRank(int rank, const void *bytes, int nbytes) const | Sets the vertex whose rank is rank to the binary value bytes of length nbytes bytes. Succeeds and returns true if the node contains at least rank vertices. |
bool SetVertexByRank(int rank, e4_Node n) const | Sets the vertex whose rank is rank to the node n. The current node becomes a parent of n. Succeeds and returns true if the current node contains at least rank vertices and n is valid and in the same storage as this node. |
bool SetNodeByRank(int rank, e4_Node &n) const | Sets the vertex whose rank is rank to a new node which is also returned in n. Succeeds and returns true if the node contains at least rank vertices. |
bool AddVertex(const char *name, e4_InsertOrder o, int &rank, int v) const | Adds a vertex with name name according to the supplied insert order o and rank rank. If o is E4_IOFIRST or E4_IOLAST, the new vertex is inserted as the first or last vertex in the node. If o is E4_IOAT or E4_IOBEFORE, the new vertex is inserted so that its rank is rank. If o is E4_IOAFTER, the new vertex is inserted so that it has rank rank + 1. The value of the new vertex is set to the integer value v. If the operation succeeds it returns true and rank is set to the rank of the newly added vertex. |
bool AddVertex(const char *name, e4_InsertOrder o, int &rank, double v) const | As above, except that the newly added vertex is set to the 64-bit floating point value v. |
bool AddVertex(const char *name, e4_InsertOrder o, int &rank, const char *v) const | As above, except that the newly added vertex is set to the NULL terminated string value v. |
bool AddVertex(const char *name, e4_InsertOrder o, int &rank, const void *bytes, int nbytes) const | As above, except that the newly added vertex is set to the binary value bytes of length nbytes bytes. |
bool AddVertex(const char *name, e4_InsertOrder o, int &rank, e4_Node n) const | As above except that the newly added vertex is set to the supplied noden. |
bool AddNode(const char *name, e4_InsertOrder o, int &rank, e4_Node &n) const | As above, except that the newly added vertex is set to a new node. The new node is also returned in n. |
bool AddVertexRef(const char *name, e4_InsertOrder o, int &rank, int v, e4_Vertex &v) const | As above, except that the newly added vertex is set to the integer value v, and an e4_Vertex instance representing the new vertex is returned in v. Note that it is much more efficient to use AddVertexRef instead of AddVertex followed by GetVertexRef. |
bool AddVertexRef(const char *name, e4_InsertOrder o, int &rank, double d, e4_Vertex &v) const | As above, except that the newly added field is set to the 64-bit floating point value d, and an e4_Vertex instance representing the new vertex is returned in v. |
bool AddVertexRef(const char *name, e4_InsertOrder o, int &rank, const char *s, e4_Vertex &v) const | As above, except that the newly added field is set to the NULL terminated string value s, and an e4_Vertex instance representing the new vertex is returned in v. |
bool AddVertexRef(const char *name, e4_InsertOrder o, int &rank, const void *bytes, int nbytes, e4_Vertex &v) const | As above, except that the newly added vertex is set to the binary value bytes of length nbytes bytes, and an e4_Vertex instance representing the new vertex is returned in v. |
bool AddVertexRef(const char *name, e4_InsertOrder o, int &rank, e4_Node n, e4_Vertex &v) const | As above, except that the newly added vertex is set to the supplied node n and an e4_Vertex instance representing the new vertex is returned in v. |
bool AddNodeRef(const char *name, e4_InsertOrder o, int &rank, e4_Node &n, e4_Vertex &v) const | As above, except that the newly added vertex is set to a new node which is also returned in n, and an e4_Vertex instance representing the new vertex is returned in v. |
bool MoveVertex(e4_Vertex &v, e4_InsertOrder o, int rank) | Move the given vertex from this or another node and insert it in this node at the position indicated by o and rank. If o is E4_IOFIRST or E4_IOLAST, the moved vertex becomes the first or last vertex in this node. If o is E4_IOAT or E4_IOBEFORE, the moved vertex becomes the vertex with rank rank in this node. If o is E4_IOAFTER, the moved vertex becomes the vertex with rank rank + 1 in this node. v and this must be contained within the same storage, or the operation fails. |
bool GetVertex(const char *name, e4_Node &n) const | Retrieves in n an e4_Node instance representing the node value of the first vertex, in rank order, named name. Succeeds and returns true if the vertex exists and contains a node value. |
bool GetVertex(const char *name, int &v) const | Retrieves in v the integer value of the first vertex, in rank order, named name. Succeeds and returns true if the vertex exists and contains an integer value. |
bool GetVertex(const char *name, double &v) const | Retrieves in v the 64-bit floating point value of the first vertex, in rank order, named name. Succeeds and returns true if the vertex exists and contains a 64-bit floating point value. |
bool GetVertex(const char *name, const char *&v) const | Retrieves in v the NULL terminated string value of the first vertex, in rank order, named name. Succeeds and returns true if the vertex exists and contains a NULL terminated string value. Note that the memory occupied by the value returned in v belongs to the e4Graph package and may be reused by the next e4Graph operation. |
bool GetVertex(const char *name, const void *&bytes, int &nbytes) const | Retrieves in bytes the binary value of the first vertex, in rank order, named name. The length of the value is returned in nbytes. Succeeds and returns true if the vertex exists and contains a binary value. Note that the memory occupied by the value returned in bytes belongs to the e4Graph package and may be reused by the next e4Graph operation. |
bool GetVertex(const char *name, e4_Value &v) const | Retrieves in v the value of the first vertex, in rank order, named name. Use this method when you do not know the type of the value stored in the vertex; the type and value are stored into v. Note that a value of type binary or NULL terminated string is stored in memory owned by the e4Graph package that may be reused by the next e4Graph operation. |
bool GetNthVertex(const char *name, int nth, e4_Node &n) const | Retrieves in n an instance of e4_Node representing the node value of the nth vertex, in rank order, named name. Succeeds and returns true if the vertex exists and contains a node value. |
bool GetNthVertex(const char *name, int nth, int &v) const | Retrieves in v the integer value of the nth vertex, in rank order, named name. Succeeds and returns true if the vertex exists and contains an integer value. |
bool GetNthVertex(const char *name, int nth, double &v) const | Retrieves in v the 64-bit floating point value of the nth vertex, in rank order, named name. Succeeds and returns true if the vertex exists and contains a 64-bit floating point value. |
bool GetNthVertex(const char *name, int nth, const char *&v) const | Retrieves in v the NULL terminated string value of the nth vertex, in rank order, named name. Succeeds and returns true if the vertex exists and contains a NULL terminated string value. Note that the memory occupied by the value returned in v belongs to the e4Graph package and may be reused by the next e4Graph operation. |
bool GetNthVertex(const char *name, int nth, const void *&bytes, int &nbytes) const | Retrieves in bytes the binary value of the nth vertex, in rank order, named name. The length of the value is returned in nbytes. Succeeds and returns true if the vertex exists and contains a binary value. Note that the memory occupied by the value returned in bytes belongs to the e4Graph package and may be reused by the next e4Graph operation. |
bool GetNthVertex(const char *name, int nth, e4_Value &v) const | Retireves in v the value of the nth vertex, in rank order, named name. Use this method when you do not know the type of the value stored in the vertex; the type and value are stored in v. Note that a value of type binary or NULL terminated string is stored in memory owned by the e4Graph package which may be reused by the next e4Graph operation. |
bool GetVertexByRank(int rank, int &v) const | Retrieves in v the integer value of the vertex ranked rank. Succeeds if the vertex exists and has an integer value. |
bool GetVertexByRank(int rank, double &v) const | Retrieves in v the 64-bit floating point value of the vertex ranked rank. Succeeds if the vertex exists and has a 64-bit floating point vaue. |
bool GetVertexByRank(int rank, const char *&v) const | Retrieves in v the NULL terminated string value of the vertex ranked rank. Succeeds if the vertex exists and has a NULL terminated string value. Note that the memory occupied by the value returned in v belongs to the e4Graph package and may be reused by the next e4Graph operation. |
bool GetVertexByRank(int rank, const void *&bytes, int &nbytes) const | Retrieves in v the binary value of the vertex ranked rank. The length of the value is returned in nbytes. Succeeds if the vertex exists and has a binary value. Note that the memory occupied by the value returned in v belongs to the e4Graph package and may be reused by the next e4Graph operation. |
bool GetVertexRef(const char *name, e4_Vertex &f) const | Retrieves in f an instance of e4_Vertex that represents the first vertex, in rank order, in this node named name. Succeeds if the vertex exists. |
bool GetVertexRef(const char *name, int nth, e4_Vertex &f) const | Retrieves in f an instance of e4_Vertex that represents the nth vertex, in rank order, in this node named name. Succeeds if the node contains at least nth vertices named name. |
bool GetVertexRefByRank(int rank, e4_Vertex &f) const | Retrieves in f an instance of e4_Vertex that represents the vertex ranked rank in this node. Succeeds if the node contains at least rank vertices. |
bool DeleteVertex(const char *name) const | Deletes the first vertex, in rank order, named name from this node. Succeeds if the node contains a vertex by that name. |
bool DeleteNthVertex(const char *name, int nth) const | Deletes the nth vertex, in rank order, named name from this node. Succeeds if the vertex exists. |
bool DeleteVertexByRank(int rank) const | Deletes the vertex ranked rank in this node. Succeeds if the node contains at least rank vertices. |
e4_VertexType VertexType(const char *name) const | Returns the type of the first vertex, in rank order, named name. If the vertex does not exist returns E4_VTUNKNOWN. |
e4_VertexType VertexType(const char *name, int nth) const | Returns the type of the nth vertex, in rank order, named name. If the vertex does not exist returns E4_VTUNKNOWN. |
e4_VertexType VertexTypeByRank(int rank) const | Returns the type of the vertex ranked rank in this node. If the vertex does not exist returns E4_VTUNKNOWN. |
const char *VertexName(int rank) const | Returns the name of the vertex ranked rank in this node as a NULL terminated string. If the vertex does not exist returns NULL. Note that the memory occupied by the returned string belongs to the e4Graph package and may be reused by the next e4Graph operation. |
bool RenameVertex(int rank, const char *newname) const | Renames the vertex ranked rank in this node to newname, which must not be NULL. |
int VertexRank(const char *name) const | Computes the rank of the first vertex, in rank order, in this node named name. Returns E4_VERTEXNOTFOUND if the vertex does not exist. |
int VertexRank(const char *name, int nth) const | Computes the rank of the nth vertex, in rank order, in this node named name. Returned E4_VERTEXNOTFOUND if the node does not contain at least nth vertices named name. |
bool Exists(const char *name) const | Returns true if there is at least one vertex in this node named name. |
bool Exists(const char *name, int nth) const | Returns true if there are at least nth vertices in this node named name. |
bool GetParent(e4_Node &p) const | Retrieves in p an instance of e4_Node representing the first parent node of this node. Returns true if this node has at least one parent. |
bool GetParent(int nth, e4_Node &p) const | Retrieves in p an instance of e4_Node representing the nth parent node of this node. Returns true if this node has at least that many parents. If nth is negative, returns the last parent node of this node. |
int ParentCount() const | Returns the number of parents of this node. |
bool IsRoot() const | Returns true if this node has no parents. |
int OccurrenceCount() const | Returns the number of vertices that contain this node as their value. |
int OccurrenceCount(e4_Node parent) const | Returns the number of vertices originating in the node parent that have this node as their value. |
int ParentRank(e4_Node parent) const | Returns the rank of the node parent in the parents of this node. If parent is not a parent of this node, returns E4_NODENOTFOUND. |
bool IsMarked() const | Returns true if there is at least one marker (instance of e4_Marker) that is marking this node. |
bool GetMarker(e4_Marker &t) const | Retrieves in t an instance of e4_Marker representing the first marker marking this node. Succeeds if this node is marked with at least one marker. |
bool GetMarker(int nth, e4_Marker &t) const | Retrieves in t an instance of e4_Marker representing the nth marker marking this node. Succeeds if this node is marked with at least nth markers. If nth is negative, retrieves the last marker for this node. |
bool AddMarker(const char *name, e4_Marker &t) const | Adds a new marker named name to this storage and make it mark this node. The new marker can be addressed by name or by rank -- if there were n-1 markers marking this node before this operation, the new marker has the rank n. |
bool MarkWith(e4_Marker m) const | Make the marker m mark this node instead of the node it is currently marking. If the node that was previously marked by m becomes unreachable, it is removed from this storage. The marker m and this node must reside within the same storage. |
bool Unmark(e4_Marker m) const | Make the marker m not mark this node. After this operation m is invalid and has been removed from this storage. The operation succeeds and returns true if m is currently marking this node. |
bool Unmark(int nth) const | Make the nth marker marking this node no longer mark this node. After this operation the marker is invalid and has been removed from this storage. The operation succeeds and returns true if this node is marked with at least nth markers. |
int MarkerCount() const | Returns the number of markers marking this node. |
int GetRankInParent() const | Returns the rank of the first vertex in the first parent node whose value is this node. If the node does not have parents, returns E4_FIELDNOTFOUND. |
int GetRankInParent(int nth) const | Returns the rank of the first vertex in the nth parent node whose value is this node. If the current node does not have that many parents, returns E4_FIELDNOTFOUND. |
const char *GetNameInParent() const | Returns the name of the first vertex in the first parent node whose value is this node. If the node does not have parents, returns NULL. Note that the memory occupied by the returned NULL terminated string value belongs to the e4Graph package and may be reused by the next e4Graph operation. |
const char *GetNameInParent(int nth) const | Returns the name of the first field in the nth parent node whose value is this node. If the current node does not have that many parents, returns NULL. |
bool GetStorage(e4_Storage &s) const | Retrieves in s an instance of e4_Storage representing the storage containing this node. |
bool GetUniqueID(e4_NodeUniqueID &nuid) const | Retrieves, in nuid, a type-safe unique identifier that identifies this node uniquely within its storage. Upon success, returns true. If the node is invalid returns false Type-safe unique identifiers are described here. |
bool Delete() const | Deletes the node represented by this e4_Node instance and all its contained vertices, recursively. After this operation, this and any instances of e4_Vertex and e4_Node that refer to deleted vertices and nodes become invalid. |
bool IsValid() const | Returns true if this refers to a valid node. A node is valid if it has not been deleted from its containing storage. |
bool SetUserData(int userData) const | Persistently associates the value of userData with this node. This user data is for use by application programs incorporating e4Graph, and is unused by e4Graph itself. The default value, before it is set by application programs, is zero. |
bool GetUSerData(int &userData) const | Retrieve, in userData, the value of the user data associated with this node. If not previously set by application programs, the value is zero. |
e4_RefKind Kind() const | Returns E4_RKNODE, the e4_RefKind identifier for e4_Node. |