Struct portgraph::PortGraph

pub struct PortGraph { /* private fields */ }

An unlabelled port graph.

A port graph consists of a collection of nodes identified by a NodeIndex. Each node has an ordered sequence of input and output ports, identified by a PortIndex that is unique within the graph. To optimize for the most common use case, the number of input and output ports of a node must be specified when the node is created.

When a node and its associated ports are removed their indices will be reused on a best effort basis when a new node is added. The indices of unaffected nodes and ports remain stable. PortGraph::compact_nodes and PortGraph::compact_ports to eliminate fragmentation in the index space.

Implementations

impl PortGraph

pub fn new() -> Self

Create a new empty PortGraph.

pub fn with_capacity(nodes: usize, ports: usize) -> Self

Create a new empty PortGraph with preallocated capacity.

pub fn add_node(&mut self, incoming: usize, outgoing: usize) -> NodeIndex

Adds a node to the portgraph with a given number of input and output ports.

Panics

Panics if the total number of ports exceeds u16::MAX.

Example

let mut g = PortGraph::new();
let node = g.add_node(4, 3);
assert_eq!(g.inputs(node).count(), 4);
assert_eq!(g.outputs(node).count(), 3);
assert!(g.contains_node(node));

pub fn remove_node(&mut self, node: NodeIndex)

Remove a node from the port graph. All ports of the node will be unlinked and removed as well. Does nothing if the node does not exist.

Example

let mut g = PortGraph::new();
let node0 = g.add_node(1, 1);
let node1 = g.add_node(1, 1);
g.link_ports(g.outputs(node0).nth(0).unwrap(), g.inputs(node1).nth(0).unwrap());
g.link_ports(g.outputs(node1).nth(0).unwrap(), g.inputs(node0).nth(0).unwrap());
g.remove_node(node0);
assert!(!g.contains_node(node0));
assert!(g.port_link(g.outputs(node1).nth(0).unwrap()).is_none());
assert!(g.port_link(g.inputs(node1).nth(0).unwrap()).is_none());

pub fn link_ports( &mut self, port_a: PortIndex, port_b: PortIndex ) -> Result<(), LinkError>

Link an output and an input port.

Example

let mut g = PortGraph::new();
let node0 = g.add_node(0, 1);
let node1 = g.add_node(1, 0);
let node0_output = g.output(node0, 0).unwrap();
let node1_input = g.input(node1, 0).unwrap();
g.link_ports(node0_output, node1_input).unwrap();
assert_eq!(g.port_link(node0_output), Some(node1_input));
assert_eq!(g.port_link(node1_input), Some(node0_output));

Errors

• If port_a or port_b does not exist.
• If port_a and port_b have the same direction.
• If port_a or port_b is already linked.

pub fn unlink_port(&mut self, port: PortIndex) -> Option<PortIndex>

Unlinks the port and returns the port it was linked to. Returns None when the port was not linked.

pub fn get_connections( &self, from: NodeIndex, to: NodeIndex ) -> NodeConnections<'_>

Returns an iterator over every pair of matching ports connecting from with to.

Example

let mut g = PortGraph::new();
let a = g.add_node(0, 2);
let b = g.add_node(2, 0);

g.link_nodes(a, 0, b, 0).unwrap();
g.link_nodes(a, 1, b, 1).unwrap();

let mut connections = g.get_connections(a, b);
assert_eq!(connections.next(), Some((g.output(a,0).unwrap(), g.input(b,0).unwrap())));
assert_eq!(connections.next(), Some((g.output(a,1).unwrap(), g.input(b,1).unwrap())));
assert_eq!(connections.next(), None);

pub fn get_connection( &self, from: NodeIndex, to: NodeIndex ) -> Option<(PortIndex, PortIndex)>

Checks whether there is a directed link between the two nodes and returns the first matching pair of ports.

Example

let mut g = PortGraph::new();
let a = g.add_node(0, 2);
let b = g.add_node(2, 0);

g.link_nodes(a, 0, b, 0).unwrap();
g.link_nodes(a, 1, b, 1).unwrap();

assert_eq!(g.get_connection(a, b), Some((g.output(a,0).unwrap(), g.input(b,0).unwrap())));

pub fn connected(&self, from: NodeIndex, to: NodeIndex) -> bool

Checks whether there is a directed link between the two nodes.

Example

let mut g = PortGraph::new();
let a = g.add_node(0, 2);
let b = g.add_node(2, 0);

g.link_nodes(a, 0, b, 0).unwrap();

assert!(g.connected(a, b));

pub fn link_nodes( &mut self, from: NodeIndex, from_output: usize, to: NodeIndex, to_input: usize ) -> Result<(PortIndex, PortIndex), LinkError>

Links two nodes at an input and output port offsets.

Errors

• If the ports and nodes do not exist.
• If the ports are already linked.

pub fn link_offsets( &mut self, node_a: NodeIndex, offset_a: PortOffset, node_b: NodeIndex, offset_b: PortOffset ) -> Result<(PortIndex, PortIndex), LinkError>

Links two nodes at an input and output port offsets.

Errors

• If the ports and nodes do not exist.
• If the ports have the same direction.
• If the ports are already linked.

pub fn port_direction(&self, port: PortIndex) -> Option<Direction>

Returns the direction of the port.

pub fn port_node(&self, port: PortIndex) -> Option<NodeIndex>

Returns the node that the port belongs to.

pub fn port_offset(&self, port: PortIndex) -> Option<PortOffset>

Returns the index of a port within its node’s port list.

pub fn port_index( &self, node: NodeIndex, offset: PortOffset ) -> Option<PortIndex>

Returns the port index for a given node, direction, and offset.

pub fn port_link(&self, port: PortIndex) -> Option<PortIndex>

Returns the port that the given port is linked to.

pub fn ports(&self, node: NodeIndex, direction: Direction) -> NodePorts

Iterates over all the ports of the node in the given direction.

pub fn all_ports(&self, node: NodeIndex) -> NodePorts

Iterates over the input and output ports of the node in sequence.

pub fn input(&self, node: NodeIndex, offset: usize) -> Option<PortIndex>

Returns the input port at the given offset in the node.

Shorthand for PortGraph::port_index.

pub fn output(&self, node: NodeIndex, offset: usize) -> Option<PortIndex>

Returns the output port at the given offset in the node.

Shorthand for PortGraph::ports.

pub fn inputs(&self, node: NodeIndex) -> NodePorts

Iterates over all the input ports of the node.

Shorthand for PortGraph::ports.

pub fn outputs(&self, node: NodeIndex) -> NodePorts

Iterates over all the output ports of the node.

Shorthand for PortGraph::ports.

pub fn num_inputs(&self, node: NodeIndex) -> usize

Returns the number of input ports of the node.

Shorthand for PortGraph::num_ports.

pub fn num_outputs(&self, node: NodeIndex) -> usize

Returns the number of output ports of the node.

Shorthand for PortGraph::num_ports.

pub fn num_ports(&self, node: NodeIndex, direction: Direction) -> usize

Returns the number of ports of the node in the given direction.

pub fn port_offsets( &self, node: NodeIndex, direction: Direction ) -> NodePortOffsets

Iterates over all the port offsets of the node in the given direction.

Example

let mut graph = PortGraph::new();
let node = graph.add_node(0, 2);

assert!(graph.links(node, Direction::Incoming).eq([]));
assert!(graph.port_offsets(node, Direction::Outgoing).eq([PortOffset::new_outgoing(0), PortOffset::new_outgoing(1)]));

pub fn input_offsets(&self, node: NodeIndex) -> NodePortOffsets

Iterates over all the input port offsets of the node.

Shorthand for PortGraph::port_offsets.

pub fn output_offsets(&self, node: NodeIndex) -> NodePortOffsets

Iterates over all the output port offsets of the node.

Shorthand for PortGraph::port_offsets.

pub fn all_port_offsets(&self, node: NodeIndex) -> NodePortOffsets

Iterates over the input and output port offsets of the node in sequence.

pub fn links(&self, node: NodeIndex, direction: Direction) -> NodeLinks<'_>

Iterates over the links of the node in the given direction. When the corresponding node port is linked to another one, the Option contains the index of the other port.

Examples

let mut graph = PortGraph::new();

let node_a = graph.add_node(0, 2);
let node_b = graph.add_node(1, 0);

let port_a = graph.outputs(node_a).next().unwrap();
let port_b = graph.inputs(node_b).next().unwrap();

graph.link_ports(port_a, port_b).unwrap();

assert!(graph.links(node_a, Direction::Outgoing).eq([Some(port_b), None]));
assert!(graph.links(node_b, Direction::Incoming).eq([Some(port_a)]));

pub fn input_links(&self, node: NodeIndex) -> NodeLinks<'_>

Iterates over the input links of the node. Shorthand for PortGraph::links.

pub fn output_links(&self, node: NodeIndex) -> NodeLinks<'_>

Iterates over the output links of the node. Shorthand for PortGraph::links.

pub fn all_links(&self, node: NodeIndex) -> NodeLinks<'_>

Iterates over the input and output links of the node in sequence.

pub fn neighbours( &self, node: NodeIndex, direction: Direction ) -> Neighbours<'_>

Iterates over neighbour nodes in the given direction. May contain duplicates if the graph has multiple links between nodes.

Examples

let mut graph = PortGraph::new();

let a = graph.add_node(0, 1);
let b = graph.add_node(2, 1);

graph.link_nodes(a, 0, b, 0).unwrap();
graph.link_nodes(b, 0, b, 1).unwrap();

assert!(graph.neighbours(a, Direction::Outgoing).eq([b]));
assert!(graph.neighbours(b, Direction::Incoming).eq([a,b]));

pub fn input_neighbours(&self, node: NodeIndex) -> Neighbours<'_>

Iterates over the input neighbours of the node. Shorthand for PortGraph::neighbours.

pub fn output_neighbours(&self, node: NodeIndex) -> Neighbours<'_>

Iterates over the output neighbours of the node. Shorthand for PortGraph::neighbours.

pub fn all_neighbours(&self, node: NodeIndex) -> Neighbours<'_>

Iterates over the input and output neighbours of the node in sequence.

pub fn contains_node(&self, node: NodeIndex) -> bool

Returns whether the port graph contains the node.

pub fn contains_port(&self, port: PortIndex) -> bool

Returns whether the port graph contains the port.

pub fn is_empty(&self) -> bool

Returns whether the port graph has no nodes nor ports.

pub fn node_count(&self) -> usize

Returns the number of nodes in the port graph.

pub fn port_count(&self) -> usize

Returns the number of ports in the port graph.

pub fn link_count(&self) -> usize

Returns the number of links between ports.

pub fn nodes_iter(&self) -> Nodes<'_>

Iterates over the nodes in the port graph.

pub fn ports_iter(&self) -> Ports<'_>

Iterates over the ports in the port graph.

pub fn clear(&mut self)

Removes all nodes and ports from the port graph.

pub fn node_capacity(&self) -> usize

Returns the capacity of the underlying buffer for nodes.

pub fn port_capacity(&self) -> usize

Returns the capacity of the underlying buffer for ports.

pub fn node_port_capacity(&self, node: NodeIndex) -> usize

Returns the allocated port capacity for a specific node.

Changes to the number of ports of the node will not reallocate until the number of ports exceeds this capacity.

pub fn reserve(&mut self, nodes: usize, ports: usize)

Reserves enough capacity to insert at least the given number of additional nodes and ports.

This method does not take into account the length of the free list and might overallocate speculatively.

pub fn set_num_ports<F>( &mut self, node: NodeIndex, incoming: usize, outgoing: usize, rekey: F )where F: FnMut(PortIndex, PortOperation),

Changes the number of ports of the node to the given incoming and outgoing counts.

Invalidates the indices of the node’s ports. If the number of incoming or outgoing ports is reduced, the ports are removed from the end of the port list.

Every time a port is moved, the rekey function will be called with its old and new index. If the port is removed, the new index will be None.

This operation is O(n) where n is the number of ports of the node.

pub fn compact_nodes<F>(&mut self, rekey: F)where F: FnMut(NodeIndex, NodeIndex),

Compacts the storage of nodes in the portgraph so that all nodes are stored consecutively.

Every time a node is moved, the rekey function will be called with its old and new index.

pub fn compact_ports<F>(&mut self, rekey: F)where F: FnMut(PortIndex, PortIndex),

Compacts the storage of ports in the portgraph so that all ports are stored consecutively.

Shrinks the port capacity of every node to match the number of ports it contains.

Every time a port is moved, the rekey function will be called with is old and new index.

pub fn shrink_to_fit(&mut self)

Shrinks the underlying buffers to the fit the data.

This does not move nodes or ports, which might prevent freeing up more capacity. To shrink the buffers as much as possible, call PortGraph::compact_nodes and PortGraph::compact_ports first.

impl PortGraph

pub fn apply_rewrite(&mut self, rewrite: Rewrite) -> Result<(), RewriteError>

Applies a rewrite to the graph.

pub fn apply_weighted_rewrite<N: Clone, P: Clone>( &mut self, rewrite: WeightedRewrite<N, P>, weights: &mut Weights<N, P> ) -> Result<(), RewriteError>

Applies a rewrite to the graph and associated weights.

pub fn apply_rewrite_with_callbacks( &mut self, rewrite: Rewrite, node_removed: impl FnMut(NodeIndex), port_removed: impl FnMut(PortIndex), node_inserted: impl FnMut(NodeIndex, NodeIndex), port_inserted: impl FnMut(PortIndex, PortIndex), ports_connected: impl FnMut(PortIndex, PortIndex) ) -> Result<(), RewriteError>

Applies a rewrite to the graph, calling the provided callbacks as the rewrite is applied.

Parameters

• rewrite: The rewrite to apply.
• node_removed: A callback that is called with the index of each node that is removed.
• port_removed: A callback that is called with the index of each port that is removed.
• node_inserted: A callback that is called with the old node index in the rewrite’s OpenGraph, and the new node index in the graph.
• port_inserted: A callback that is called with the old port index in the rewrite’s OpenGraph, and the new port index in the graph.
• ports_connected: A callback that is called when two ports are connected.

Trait Implementations

impl Clone for PortGraph

fn clone(&self) -> PortGraph

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PortGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PortGraph

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq<PortGraph> for PortGraph

fn eq(&self, other: &PortGraph) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for PortGraph