The tgraph vertex Object

The tgraph vertex Object

The getvertex operation on a tgraph node object returns a tgraph vertex object. This page describes the operations supported by these Tcl objects. An object oriented style of programming is supported where the object returned from $node getvertex is used as the command name and the specific operation being invoked is the first argument.

The following operations are supported on tgraph vertex objects:

$vertex kind Returns "vertex". This operation can be used to determine what kind of tgraph object is stored in a Tcl variable.

$vertex get Returns the value associated with the given vertex as an appropriate Tcl object. Depending on the type of the value, either a tgraph node object is returned or a Tcl object of a primitive type such as int or double is returned.

$vertex set newval ?typesel? Sets the value associated with this vertex. If the optional type selector typesel is present, an attempt is made to convert the new value newval to the requested type before assigning it to the vertex. If the new value is a tgraph node object, the node containing this vertex is added to the parents of the node denoted by newval. If the previous value associated with this vertex becomes unreachable, it is deleted from the storage and its memory is reclaimed.
The allowable values for typesel are -integer, to convert the given value to an integer, -double, to convert to a 64-bit floating point number, -string for a string value, -node for a named node value, and -binary for a binary value.

$vertex setnode A new e4Graph node is created and added to the storage, and made the value of the vertex. The tgraph node object representing the new node is returned.

$vertex rank An integer representing the rank of this vertex in its containing node is returned.

$vertex detach The vertex is detached from its containing node. If it was already detached, this does nothing. If the value of $vertex is a node, and after this call the node is not the value of any attached vertices, then that node also becomes detached as a result of this call.

$vertex isdetached Returns 1 if $vertex is a detached vertex, 0 if it is contained within some node.

$vertex dispose DEPRECATED. This API will be removed before the final version of e4Graph 1.0 is released. This API is a no-op.

$vertex type Returns a string representing the type of the value associated with this vertex. One of the following strings is returned: "node", "int", "double", "string" or "binary".

$vertex name Returns a string denoting the name of this vertex.

$vertex rename newname Sets the name of the vertex to the string newname.

$vertex node Returns the tgraph node object for the node containing this vertex.

$vertex root Returns the tgraph node object for the root node of the storage containing this vertex.

$vertex storage Returns the tgraph storage object for the storage containing this vertex.

$vertex move othervertex insertorder offset Moves the tgraph vertex object othervertex to a position relative to this vertex in the node containing this vertex. The relative position is determined by insertorder and offset. The legal values for insertorder are described in the tgraph node page. Offset is used if the insertorder is "at", "before" or "after", and ignored (but still required) otherwise.

$vertex next Returns the tgraph vertex object representing the next vertex, in rank order, in the node containing this vertex.

$vertex prev Returns the tgraph vertex object representing the preceding vertex, in rank order, in the node containing this vertex.

$vertex call ?arg ...? Calls the value of this vertex, a two element list, as a Tcl procedure, passing it the arguments given. The first element of the value is a list of formal parameters to be assigned the given arguments; the second element of the list is the body of the procedure to invoke. The formal parameter list is prepended by a Tcl variable named this, and the body is invoked with the list of given arguments prepended with the tgraph node object containing this vertex. This has the effect of making the variable this contain the tgraph node object containing this vertex for the duration of the invocation of the body.

$vertex id Returns an identifier that is unique within the storage containing vertex. Subsequently you can give this identifier as an argument to $storage get vertex $id to retrieve this vertex.

$vertex userdata ?newvalue? Sets or retrieves the user data (an integer) that is persistently associated with this vertex. The Tcl binding will in the future use this field to store additional type information for tgraph objects; the existence of this method is documented here for completeness only.

Here's an example showing how to use tgraph vertex objects:

set mystorage [tgraph::open foo.db]
set n [$mystorage root]
...
set v [$n getvertex frob]
puts "v's name is [$v name], and its value is [$v get]"
set vprev [$v prev]
set vnext [$v next]
$v set {{a b} {puts "$a $b $this}}
$v call 33 44
==> 33 44 tgraph::storage12::nodes::node12
...


$vertex kind	Returns "vertex". This operation can be used to determine what kind of tgraph object is stored in a Tcl variable.
$vertex get	Returns the value associated with the given vertex as an appropriate Tcl object. Depending on the type of the value, either a tgraph node object is returned or a Tcl object of a primitive type such as int or double is returned.
$vertex set newval ?typesel?	Sets the value associated with this vertex. If the optional type selector typesel is present, an attempt is made to convert the new value newval to the requested type before assigning it to the vertex. If the new value is a tgraph node object, the node containing this vertex is added to the parents of the node denoted by newval. If the previous value associated with this vertex becomes unreachable, it is deleted from the storage and its memory is reclaimed. The allowable values for typesel are -integer, to convert the given value to an integer, -double, to convert to a 64-bit floating point number, -string for a string value, -node for a named node value, and -binary for a binary value.
$vertex setnode	A new e4Graph node is created and added to the storage, and made the value of the vertex. The tgraph node object representing the new node is returned.
$vertex rank	An integer representing the rank of this vertex in its containing node is returned.
$vertex detach	The vertex is detached from its containing node. If it was already detached, this does nothing. If the value of $vertex is a node, and after this call the node is not the value of any attached vertices, then that node also becomes detached as a result of this call.
$vertex isdetached	Returns 1 if $vertex is a detached vertex, 0 if it is contained within some node.
$vertex dispose	DEPRECATED. This API will be removed before the final version of e4Graph 1.0 is released. This API is a no-op.
$vertex type	Returns a string representing the type of the value associated with this vertex. One of the following strings is returned: "node", "int", "double", "string" or "binary".
$vertex name	Returns a string denoting the name of this vertex.
$vertex rename newname	Sets the name of the vertex to the string newname.
$vertex node	Returns the tgraph node object for the node containing this vertex.
$vertex root	Returns the tgraph node object for the root node of the storage containing this vertex.
$vertex storage	Returns the tgraph storage object for the storage containing this vertex.
$vertex move othervertex insertorder offset	Moves the tgraph vertex object othervertex to a position relative to this vertex in the node containing this vertex. The relative position is determined by insertorder and offset. The legal values for insertorder are described in the tgraph node page. Offset is used if the insertorder is "at", "before" or "after", and ignored (but still required) otherwise.
$vertex next	Returns the tgraph vertex object representing the next vertex, in rank order, in the node containing this vertex.
$vertex prev	Returns the tgraph vertex object representing the preceding vertex, in rank order, in the node containing this vertex.
$vertex call ?arg ...?	Calls the value of this vertex, a two element list, as a Tcl procedure, passing it the arguments given. The first element of the value is a list of formal parameters to be assigned the given arguments; the second element of the list is the body of the procedure to invoke. The formal parameter list is prepended by a Tcl variable named this, and the body is invoked with the list of given arguments prepended with the tgraph node object containing this vertex. This has the effect of making the variable this contain the tgraph node object containing this vertex for the duration of the invocation of the body.
$vertex id	Returns an identifier that is unique within the storage containing vertex. Subsequently you can give this identifier as an argument to $storage get vertex $id to retrieve this vertex.
$vertex userdata ?newvalue?	Sets or retrieves the user data (an integer) that is persistently associated with this vertex. The Tcl binding will in the future use this field to store additional type information for tgraph objects; the existence of this method is documented here for completeness only.