e4_Node Methods and Constructors
Author: Jacob Levy

The e4_Node Class

The e4_Node class provides the abstraction of a persistent node in a graph. a node may be the root node and may be tha value of one or more vertices in other nodes. A node may be detached or attached: a node is attached if it is the value of one or more vertices in other nodes. That is, if a node does not have any parent nodes, it is detached. Otherwise it is attached.

The e4_Node class provides methods to retrieve vertices contained within it, and to retrieve 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:

>     e4_Storage s("mystorage", E4_METAKIT);
>     e4_Node n;
>     ...
>     if (!m.GetRootNode(n)) {
>         cerr << "Could not get root node\n";
>     }

If the GetRootNode method call succeeds, n is assigned to an e4_Node instance representing the current root node of the storage s. Any number of nodes can be referenced by a user program, limited only by the resources available to the program.

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 the node is not the root node, is not the value of any reachable vertex and is not referenced directly by the user program. An unreachable node and all its recursively unreachable vertices are automatically removed from the storage.

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:

>     e4_Node n1, n2;
>     ...
>     n2 = n1;
>     ...
>     if (n1 == n2) {
>         cout << "They are one and the same.\n";
>     }

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 variable of type e4_Node to discard the reference it contains to a node, as shown in the following example:

>     e4_Node n;
>     ...
>     n = invalidNode;
>     if (n.IsValid()) {
>         cerr << "Something fishy here!\n";
>     }

In the above example, the assignment of invalidNode to n causes the reference count for the node previously referenced by the variable n to drop to zero, and if it is unreachable, its memory is freed. Note that modifications to this node are written to persistent storage only when the storage containing this node is committed. For some C++ compilers it may be necessary to assign invalidNode to fields of type e4_Node embedded within heap allocated structures before these structures are freed, to ensure that the reference count of nodes referenced by the embedded field is correct.

When the storage containing a node is closed, any variables of type e4_Node referring to that node become invalid. The only other way to make a variable of type e4_Node invalid is to assign invalidNode to it.

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:

>     e4_Node n;
>     int rank;
>     double dd;
>     ...
>     if (!n.AddVertex("barney", E4_IOFIRST, rank, 42)) {
>         cerr << "Couldn't add a vertex named \"barney\".\n";
>     }
>     ...
>     if (!n.GetVertex("joe", 3, dd)) {
>         cerr << "Couldn't retrieve third \"joe\" vertex.\n";
>     }

Vertices can also be addressed, added, modified, retrieved and deleted by rank:

>     e4_Node n;
>     int rank = 7;
>     int vi;
>     ...
>     if (!n.AddVertex("bobby", E4_IOAT, rank, 42)) {
>         cerr << "Couldn't add a vertex at rank " << rank << "\n";
>     }
>     ...
>     if (!n.GetVertexByRank(7, vi)) {
>         cerr << "Couldn't retrieve value of vertex ranked 7.\n";
>     }
>     if (vi != 42) {
>         cerr << "Oops, got " << vi << " instead of 42!\n";
>     }
>     ...
>     if (!n.SetVertexByRank(7, (double) 3.14)) {
>         cerr << "Couldn't set value of vertex ranked 7.\n";
>     }
>     ..
>     if (!n.DeleteVertexByRank(7)) {
>         cerr << "Couldn't delete vertex ranked 7.\n";
>     }

You can set value to a NULL string by passing a NULL as the value to be assigned. Most C++ compilers require you to explicitly cast the NULL as a const char * in order to disambiguate the method call. 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;
>     ...
>     if (!n.SetVertex("bob", (const char *) NULL)) {
>         ...
>     }
>     if (!n.SetVertex("joey", (const void *) NULL, 0)) {
>         ...
>     }

Each node instance referenced by the user program maintains a cache mapping from vertex names and vertex ranks to vertex IDs, to speed up vertex lookups. Looking up a vertex by name when the vertex's name is not in the cache has an overhead relative to the location of the desired vertex within that node. When the name is in the cache, the cost of looking up that vertex is constant. The cache is invalidated by various changes to the node, such as changing the name or location within the node of a vertex, adding new vertices or removing vertices, and so forth. e4Graph can be instructed to pre-cache all information about a node's vertices by calling e4_Node::PreCache(). This caches all information needed to look up any of this node's vertices by name or rank, until the cache is invalidated.

It is also possible to request that the cache be maintained up to date at all times, by setting advisory cache policy hints that advise e4Graph on the behavior desired by the user program. Calling e4_Node::GetAdvisoryCachingPolicy() lets a user program see what the current advisory policy hints are, and e4_Node::SetAdvisoryCachingPolicy() sets or clears individual advisory behavior hints.

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. The IsRoot method returns true when invoked on the node that is currently the root node of its containing storage. A method is provided to retreive an instance of e4_Storage for the storage containing this node.

e4_Node Methods and Constructors
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.
int VertexCountWithName(const char *nm) const | Returns the number of vertices in this node that have the name nm
int VertexCountWithType(e4_VertexType typeID) const | Returns the number of vertices with the type typeID
int VertexCountWithValue(e4_Value &v) const | Returns the number of vertices with the value v
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 SetVertex(const char *name, e4_Value &v) const | Set the first vertex, in rank order, with name name to the value represented by v. The operation succeeds if a vertex with the given name already exists.
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 SetNthVertex(const char *name, int nth, e4_Value &v) const | Sets the nth vertex, in rank order, with name name to the value represented by v.
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 SetVertexByRank(int rank, e4_Value &v) const | Sets the vertex whose rank is rank to the value represented by v.
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 value represented by v.
bool AddVertex(const char *name, e4_InsertOrder o, int &rank, e4_Value &v) 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 AddVertexRef(const char *name, e4_InsertOrder o, int &rank, e4_Value &val, e4_Vertex &v) const | As above, except that the newly added vertex is set to the value represented by val 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 | Retrieves 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 value.
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 DetachVertex(const char *name) const | Detaches the first vertex, in rank order, named name from this node. Succeeds if the node contains a vertex by that name. The vertex count for this node is decremented by one.
bool DetachNthVertex(const char *name, int nth) const | Detaches the nth vertex, in rank order, named name from this node. Succeeds if the vertex exists. The vertex count for this node is decremented by one.
bool DetachVertexByRank(int rank) const | Detaches the vertex ranked rank in this node. Succeeds if the node contains at least rank vertices. The vertex count for this node is decremented by one.
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 is the current root node of its containing storage.
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.
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_VERTEXNOTFOUND.
int GetRankInParent(int nth, int ith) const | Returns the rank of the ith vertex in the nth parent node whose value is this node. If the current node does not have that many parents or the nth parent does not have that many vertices whose value is this node, returns E4_VERTEXNOTFOUND.
int GetRankInParent(e4_Node p, int ith) const | Returns the rank of the ith vertex in the parent node p of this node, whose value is this node. If p is not a parent node of this node, or if it does not contain that many vertices whose value is this node, returns E4_VERTEXNOTFOUND.
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 vertex in the nth parent node whose value is this node. If the current node does not have that many parents, returns NULL.
const char *GetNameInParent(int nth, int ith) const | Returns the name of the ith vertex in the nth parent node whose value is this node. If the current node does not have that many parent, or if the nth parent node does not have that many vertices whose value is this node, returns NULL.
const char *GetNameInParent(e4_Node p, int ith) const | Returns the name of the ith vertex in the parent node p of this node, whose value is this node. If p is not a parent of this node, or if it does not contain that many vertices whose value is this node, 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 Detach() const | Detaches this node by detaching all vertices that contain this node as their value. See the detach method for vertices for a complete description.
bool IsDetached() const | Returns true if this node is detached. A node is detached if it is not the value of any vertices contained within a node.
bool IsValid() const | Returns true if this refers to a valid node. The result is true if the storage containing this node has not been closed and the program variable on which the method is invoked has not been assigned invalidNode.
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.
bool GetVertexUserData(const char *nm, int &userData) const | Retrieve, in userData, the value of the user data associated with the named vertex. If not previously set by application programs, the value is zero.
bool GetVertexUserData(const char *nm, int nth, int &userData) const | Retrieve, in userData, the value of the user data assocaited with the named vertex. If not previously set by application programs, the value is zero.
bool SetVertexUserData(const char *nm, int userData) const | Persistently associates the value of userData with the named vertex. This user data is for use by application programs incorporating e4Graph, and is not used by e4Graph itself. The default value, before it is set by application programs, is zero.
bool SetVertexUserData(const char *nm, int nth, int userData) const | Persistently associates the value of userData with the named vertex. This user data is for use by application programs incorporating e4Graph, and is not used by e4Graph itself. The default value, before it is set by application programs, is zero.
bool GetVertexUserDataByRank(int rank, int &userData) const | Retrieve, in userData, the user data associated with the vertex with the given rank in this node. If not previously set by user programs, the value is zero.
bool SetVertexUserDataByRank(int rank, int userData) const | Persistently associates the value of userData with the vertex with the specified rank in this node. This user data is for use by application programs incorporating e4Graph, and is not used by e4Graph itself. The default value, before it is set by application programs, is zero.
void PreCache() const | Pre-cache vertex IDs for all vertices in this node, for faster lookup. You can use this method when your program will access many vertices in this node repeatedly, and the node is not updated in a manner that invalidates the cache. The cache is invalidated when a vertex's name is changed, when vertices are moved, and when a new vertex is added to the node not as the last vertex.
int GetAdvisoryCachingPolicy() const | Returns the current setting of the advisory caching policy for this node. This advisory policy provides e4Graph with a hint as to what behavior is desired by the user program. The various flags are explained here. Note that the behavior is a-priori controlled by whether the storage wide state E4_NOVERTEXCACHE is set.
int SetAdvisoryCachingPolicy(bool set, int mask) const | Sets or clears individual flags for the advisory caching policy for this node. This advisory policy provides e4Graph with a hint as to what behavior is desired by the user program. The various flags are explained here. Note that the behavior is a-priori controlled by whether the storage wide state E4_NOVERTEXCACHE is set. If set is true, the flags in mask are added to the advisory caching policy. Otherwise they are cleared. This method returns the previous combination of flags in effect.
e4_RefKind Kind() const | Returns E4_RKNODE, the e4_RefKind identifier for e4_Node.