In addition to the functionality presented in the section called “Creating Graphs and Graph Elements”, which covers simple graph element creation, class Graph also provides methods that offer more control in specific situations.

For example, in addition to the most frequently used simple edge creation, it is also possible to specify the exact place where a newly created edge should be inserted into both the sequence of outgoing edges at its source node and the sequence of incoming edges at its target node. Furthermore, an already existing edge can be completely remodeled, i.e., both its end nodes as well as the insertion places at either end node can be changed. Reversing an edge, as another variant of changing an edge, is also supported.

Example 4.1, “Exact edge insertion” shows the respective line of code for specifying the exact place of edge insertion.

// 'graph' is of type y.base.Graph. 
// 'source' and 'target' are of type y.base.Node. 

// Create a new edge at the second position of all incoming edges at the target 
// node. 
graph.createEdge(source, source.firstOutEdge(), 
                 target, target.firstInEdge(), graph.AFTER, graph.AFTER);

Figure 4.2, “Exact edge insertion” shows the resulting graph. The newly created edge is inserted after the first incoming edge at the target node. Observe how the sequence of incoming edges (indicated by the numbers near the arrowheads) changes with the insertion.

Figure 4.2. Exact edge insertion

(a) Graph before...	(b) ... and after edge insertion.

The analogous operation to graph element creation is their removal. Class Graph offers methods to remove all graph elements at once, or to remove only a single node or a single edge. When removing either an instance of type Node or an instance of type Edge their reference to the containing graph is cleared.

// 'graph' is of type y.base.Graph. 

// Remove single graph elements from the graph. 
// Note that all edges adjacent to the given node are removed prior to the node 
// itself. 
graph.removeNode(graph.firstNode());
graph.removeEdge(graph.lastEdge());

// Remove all graph elements from the graph at once. 
graph.clear();

An alternative to removing graph elements is to hide them. Hiding is a technique to only temporarily remove graph elements, i.e., taking them away from the graph structure to perform some task on the remaining graph, and thereafter putting them back into again, unhiding them. Note that both removing and hiding a graph element only takes them away from the graph, the objects themselves still exist.

// 'graph' is of type y.base.Graph. 

// Hide single graph elements from the graph. 
// Note that all edges adjacent to 'exampleNode' are hidden prior to the node 
// itself. 
Node exampleNode = graph.firstNode();
graph.hide(exampleNode);

// Unhide single graph elements from the graph. 
// Note that *only* 'exampleNode' is unhidden, while its formerly adjacent edges 
// are not. 
graph.unhide(exampleNode);

In order to be able to unhide previously hidden graph elements, it is necessary to retain them, for example, in a data structure. Hiding of graph elements can also be performed utilizing specialized classes which automatically keep track of all hidden elements. These classes are described in the section called “Advanced Topics”.

In addition to the number of nodes and the number of edges an instance of type Graph also knows whether a single graph element belongs to it or if there is an edge connecting two nodes. The latter feature is especially useful if there is no reference of an edge at hand, for instance.

If a graph element has been hidden it does not belong to any graph until it is unhidden again.

// 'graph' is of type y.base.Graph

// Get the number of nodes in the graph. 
// (Both methods are equivalent.) 
int nodeCount = graph.nodeCount();
int N = graph.N();

// Get the number of edges in the graph. 
// (Both methods are equivalent.) 
int edgeCount = graph.edgeCount();
int E = graph.E();

// Check if the graph is empty. 
boolean isEmpty = graph.isEmpty();

// Check if the first node belongs to the graph. 
boolean containsNode = graph.contains(graph.firstNode());

// Check if there is an edge between first and last node of the graph. 
boolean containsEdge = graph.containsEdge(graph.firstNode(), graph.lastNode());

Class Graph offers access to its graph elements in several different ways. It returns either cursors to iterate over the respective sets of graph elements, or creates arrays containing references to all nodes or all edges from the graph. As an additional convenience, there are methods to get the first, respectively last element of any of the two sets. While the returned cursors by definition have read-only behavior on the underlying container, the returned arrays actually are copies of the respective sets of elements from the graph at a certain point in time. In effect, this means that, for example, a returned node array can be modified in any way, i.e., nodes might be removed from the array or the sequence of nodes might be changed, without affecting the node set from the graph.

To change the sequence of any of the graph element sets class Graph has methods to move an element to the first or last position, respectively.

// 'graph' is of type y.base.Graph. 

// Get the first and last node of the node set from the graph. 
Node firstNode = graph.getFirstNode();
Node lastNode = graph.getLastNode();

// Exchange first and last node of the node set. 
graph.moveToLast(firstNode);
graph.moveToFirst(lastNode);

// Get the first and last edge of the edge set from the graph. 
Edge firstEdge = graph.getFirstEdge();
Edge lastEdge = graph.getLastEdge();

// Exchange first and last edge of the edge set. 
graph.moveToLast(firstEdge);
graph.moveToFirst(lastEdge);

// Get a cursor of all nodes from the graph. 
NodeCursor nc = graph.nodes();

// Get a cursor of all edges from the graph. 
EdgeCursor ec = graph.edges();

// Get an array of all nodes from the graph. 
Node nodes[] = graph.getNodeArray();

// Get an array of all edges from the graph. 
Edge edges[] = graph.getEdgeArray();

Every instance of a graph element, i.e., every instance of type Node and type Edge holds a reference to the instance of type Graph it belongs to. This reference is cleared when the graph element has been removed or hidden from its graph.

// 'node' is of type y.base.Node.

// Get the graph the node belongs to.
Graph graph = node.getGraph();

Furthermore, every graph element knows the position it has in the respective set of elements within its graph. More precisely, when an instance of type Graph is asked for an array of its nodes, for example, this array reflects the node iteration sequence exactly, i.e., a node at position 6 in the array will return the value 6 when asked for its position.

// 'graph' is of type y.base.Graph. 
// 'node' is of type y.base.Node. 

// Get the node's position. 
int index = node.index();

// Get an array of all nodes from the graph. 
Node nodes[] = graph.getNodeArray();
// Check the positions of all nodes. 
for (int i = 0; i < graph.N(); i++)
{
  if (nodes[i].index() != i)
    throw new RuntimeException("Mismatch at position " + i + ".");
  else
    System.out.println("All is well at position " + i + ".");
}

// 'node' is of type y.base.Node.

// Get the number of edges at a node. 
int degree = node.degree();

// Get the number of incoming edges at a node. 
int inDegree = node.inDegree();

// Get the number of outgoing edges at a node. 
int outDegree = node.outDegree();

// 'graph' is of type y.base.Graph. 

Node firstNode = graph.firstNode();
Node lastNode = graph.lastNode();

// Check whether there is an edge between first and last node of the graph. 
// First check if there is a connecting edge outgoing to 'lastNode'. 
Edge e = firstNode.getEdgeTo(lastNode);
// If not, then check if there is a connecting edge incoming from 'lastNode'. 
if (e == null)
  e = firstNode.getEdgeFrom(lastNode);

// 'node' is of type y.base.Node. 

// Get a cursor to iterate over all edges at a node. 
EdgeCursor edges = node.edges();

// Get a cursor to iterate over all incoming edges at a node. 
EdgeCursor inEdges = node.inEdges();

// Get a cursor to iterate over all outgoing edges at a node. 
EdgeCursor outEdges = node.outEdges();

// 'node' is of type y.base.Node.

// Get a cursor to iterate over all neighbor nodes. 
NodeCursor neighbors = node.neighbors();

// Get a cursor to iterate over the source nodes of all incoming edges. 
// These nodes are called predecessors.
NodeCursor predecessors = node.predecessors();

// Get a cursor to iterate over the target nodes of all outgoing edges. 
// These nodes are called successors.
NodeCursor successors = node.successors();

// 'edge' is of type y.base.Edge. 

// Get the two end nodes of an edge. 
Node source = edge.source();
Node target = edge.target();

// Getting the opposite when holding one of either source or target node. 
Node opposite = edge.opposite(source);

// 'edge' is of type y.base.Edge. 

// Ask the edge whether it is a self-loop. 
boolean isSelfLoop = edge.isSelfLoop();

Table 4.1, “Time complexities in package y.base” shows time complexities for several of the most frequent tasks when working with the yFiles graph structure implementation.

Creation of graph elements takes constant time as does the removal of an edge. Removing a node, though, implies the removal of all its connecting edges first, so this task takes linear time, i.e., time proportional to the number of connecting edges. Also, all iteration is done in linear time. Checking whether a given node or edge belong to a graph is done in constant time, while testing if there is an edge connecting two nodes takes linear time.