7.4.5. Class NodeSet¶
A notice about memory management: The set objects are automatically destroyed when they are not used anymore.
7.4.5.1. Obtaining a NodeSet¶
You can create a new, empty node set by using the constructor of class NodeSet with empty parameter list. Passing an existing NodeSet object to the constructor creates an independent copy of the set. You can pass any iterable yielding Node objects to the constructor to populate the new set from it.
All methods of the RFG interface that return sets of nodes return values of class NodeSet.
Caution
You can insert nodes from different graphs into the same NodeSet instance. Be careful to distinguish the types and attribute descriptors when querying the nodes from a mixed graph node set. The best idea is not to use such mixed graph node sets at all.
7.4.5.2. Iterating the Nodes Contained in a Node Set¶
__iter__()
Instance method __iter__ returns an iterator object for all nodes contained in the node set. It is of type NodeSetIter or EdgeSetIter, respectively. See the example code in Listing Iterating a set of nodes.
from bauhaus import rfg
#...fill some_node_set
for n in some_node_set:
#...perform your actions on the nodes
Caution
You should pay attention not to modify the set you are currently iterating as this may result in unpredicted behavior. If you need to modify a set while iterating over it, make a copy of it and modify the copy while iterating over the original.
7.4.5.3. General Operations¶
__len__()
The instance method __len__ returns the size of the set. Ordinarily, it is used by calling the len function on the set.
__str__()
Instance method __str__ returns a textual representation of the node set (only for debugging purposes). For user output, use iteration and the attribute handling methods for individual nodes.
The two instance methods __eq__ and __ne__ check for equality respectively inequality of two node sets. The equality is defined by the contents of the sets. If two sets contain the same elements, the two sets are equal. Equality does not mean that inserting into the one set also alters the other.
Ordinarily, both functions are called by way of the == and != operators.
Note
The instance methods check if other_set is a subset or superset of the instance. We delivered both names with and without underscores because the names without underscores are Python naming convention whereas the names with underscores are following the naming conventions of the RFG interface.
clear()
Clears all elements from the set.
7.4.5.4. Membership in the View¶
Instance method __contains__ checks whether the node passed as parameter is contained in the set. It is usable as in operator as well.
The instance method remove either removes a node from the set (if the parameter is a Node) or it removes the set from a view (if parameter view is a View).
Caution
If nodes are removed from a view, all edges attached to these nodes are also removed implicitly.
Caution
If you remove an element from the last view it has been contained in, the element is automatically garbage collected immediately. So make sure you first add an element to a target view before removing it from a source view if you intend to transfer the element between two views.
The instance methods insert and add either insert a node into the set (if the parameter is a Node) or insert the set into a view (if parameter view is a View).
7.4.5.5. Set Operations¶
These operations return new sets that contain the intersection, union, difference, or symmetric difference of two sets.
These operator versions are also available:
operator |
function |
operation |
|---|---|---|
s1 & s2 |
__and__ |
s1.intersection(s2) |
s1 | s2 |
__or__, __add__ |
s1.union(s2) |
s1 - s2 |
__sub__ |
s1.difference(s2) |
s1 ^ s2 |
__xor__ |
s1.symmetric_difference(s2) |
copy()
The copy instance method returns a copy of the instance it is called for.
7.4.5.6. Querying the Neighborhood of Nodes in the Set¶
These instance methods are performing the operations described in section Section Querying the Neighborhood of Nodes and Edges.
The instance methods incomings, outgoings, attached, and connectings return edge sets.
The instance methods successors, predecessors, and neighbors return node sets.
Note
Because edges can be contained in a view and not contained in another view, the argument view is crucial for the neighborhood relations.
7.4.5.7. Filtering a Node Set¶
filter(node_matcher)
Instance method filter applies the predicate node_matcher to each node in the set and inserts all nodes matching the predicate into a new set that is passed back as result.