NodeListArray

Description

The NodeListArray class is meant to allow you, in c++, to treat a list of nodes, usually with coupling data, just like a regular 0-based c++ array. In our object development we found that we were quite often writing code that looked much like the following:

NetworkNode* nn = &o(NetworkNode, ownerobject(tonode(get(rank(node_v_myNetNodes, i)))));

That's pretty weird looking code. So we thought why not create a class that encapsulates all that weird code and allows us to just use array-style syntax, so that you can just add the correct NodeListArray to your class, and just write myNetNodes[i] to get the right dereference.

Now, there are different ways that a list of coupling nodes may be set up, so there are also several different types of NodeListArrays to represent these different types of lists. For example, you may have a list of just one-way pointers directly to the objects themselves. Or you may have a list of coupling nodes where the other side of the coupling is created in the "stored" attribute of the associated object, and so on.

NodeListArray is a template class that requires three template input parameters, although usually you will only need to provide the first template parameter, i.e. the type of class that will be referenced. The three template parameters are as follows: a class type, an Adder() function, and a Getter() function. Its class prototype is as follows:

NodeListArray<class T, void (*Adder)(treenode x, T* obj), T* (*Getter)(treenode x)>

The NodeListArray class has needs to be initialized on a parent node. When a new object is added to the list, the NodeListArray creates a new coupling node in the parent node. The parent node should not be used to store any child nodes other than those created by NodeListArray; two NodeListArrays should probably not share the same parent, but it is possible. If the node list array is part of an SDT or an ODT, initialization usually occurs in the bind() or bindVariables() method.

Methods

MethodDescription
void init(treenode parent) Sets the parent node of the list to the given node.
int size(void) Returns the number of members in the list.
T* operator [](int index) Uses the Getter() function to return the object at the given index.
T* operator [](char* name) Uses the Getter() function to return the object with the given name.
T* back(void) Uses the Getter() function to return the last object in the list.
T* add(T* obj) Uses the Adder() function to add the given object to the list. The object is returned.
void remove(int index) Removes the node at the given index (0-based) from the list.
void clearContents(void) Empties the list, destroying all subnodes of the parent.
void swap(int index1, int index2) Swaps the objects at the two indices.
int find(T* x) Returns the index (0-based) of the given object. Returns -1 on failure.

Types

There are several pre-defined kinds of node list arrays, each handling the process of adding to and accessing the list in its own way.

Note: For each of these classes, the Adder() function always adds a new node to the parent node of the list. This new node is used as a link to the data added to the list. In the following section, the phrase "the new sub-node" refers to this node.

NodeListArray<TheClass>::ObjPtrType

This represents a list of direct one-way pointers to ODT or SDT objects. For example:

NodeListArray<NetworkNode>::ObjPtrType myNetNodes;

Derefrencing myNetNodes[i] will return a NetworkNode*.

Adder()Points the new sub-node to the holder of the object. The object should already be on a node.
Getter()Returns the node that holds the object.

NodeListArray<TheClass>::CouplingSdtPtrType

This class represents a list of two-way pointers to coupling sdt nodes. It is like the ObjPtrType in that each item in the list is a coupling node that points to a node, but with a coupling sdt type. When adding, it will join the nodes together with a two-way pointer instead of just a one-way pointer to the object.

Adder()Adds a sub-node to the given node, and joins both new sub-nodes with a two-way pointer.
Getter()Returns the joined coupling sdt node.

NodeListArray<TheClass>::ObjStoredAttCouplingType

This class represents a two way list to an object data type. The opposite coupling node is stored in the "stored" attribute node of the given object.

Adder()Creates a coupling node in the "stored" attribute of the object and joins it with the new sub-node.
Getter()Returns the node that holds the object.

NodeListArray<TheClass>::ObjCouplingType

This class is meant to behave very similarly to the ObjStoreAttCouplingType, but instead of storing the opposite coupling node in the "stored" attribute node, it stores the opposite node somewhere else in the object. Consequently, you must define the Adder() function. It will usually look something like the following:

		void myAdder(treenode x, SomeClass* y) {
			nodejoin(x, nodeadddata(nodeinsertinto(y->node_v_someNode), DATATYPE_COUPLING);
		}
		

Adder()Custom behavior.
Getter()Returns the node that holds the object.

NodeListArray<TheClass>::SdtSubNodeType

This class represents a direct list of simple data type objects. It takes the coupling node that would normally point somewhere and replaces the coupling data with the given simple data.

Adder()Adds the given simple data to the new sub-node.
Getter()Returns the object directly.

NodeListArray<TheClass>::SdtSubNodeBindingType

This class is identical to the SdtSubNodeType, except that it binds the simple data type objects when they are created.

NodeListArray<TheClass>::CouplingSdtSubNodeType

This class is identical to the SdtSubNodeType, except that it adds coupling data to the new subnode, rather than simple data.

NodeListArray<TheClass>::CouplingSdtSubNodeBindingType

This class is identical to the CouplingSdtSubNodType, except that it binds the coupling data type objects when they are created.

NodeListArray<TheClass>::ObjSubNodeType

This class represents a straight list of odt's. create

Adder()Adds a new odt sub-node to the array.
Getter()Returns the odt node.

NodeListArray<TheClass>::NodePtrType

This class represents a list of pointers to nodes in the tree.

Adder()Points the new sub-node to the given node.
Getter()Returns the referenced node.

NodeListArray<TheClass>::StoredAttCouplingType

This class represents a list of two-way couplings to objects. This is just like the ObjStoredAttCouplingType, except it returns a TreeNode*, i.e. the node itself instead of the odt/sdt. Like ObjListArray, the other side of the coupling will be stored in the "stored" attribute of the object.

Adder()Ensures the presence of the "stored" attribute node, adds a sub-node to that node, and creates a two-way link between both new sub-nodes.
Getter()Returns the node that holds the owner object of the "stored" node.

NodeListArray<TheClass>::SubNodeCouplingType

This class represents a list of two-way couplings to nodes. This will store the other side of the coupling as a sub-node of the node referenced, and when dereferenced, it will return the node that contains the coupling sub-node.

Adder()Adds a sub-node to the given node, and joins both new sub-nodes.
Getter()Returns the parent node of the referenced node.

NodeListArray<TheClass>::SdtSubNodeCouplingType

This class represents a list of two-way couplings to nodes. This will store the other side of the coupling as a sub-node of the object referenced, and when dereferenced, it will return the node that contains the coupling sub-node. It's just like SubNodeCouplingType, except it returns an object reference instead of a node reference.

Adder()Adds a sub-node to the given node, and joins both new sub-nodes.
Getter()Returns the parent node of the referenced node.

C++ Features

For those familiar with c++, NodeListArrays also follow the c++ stl container methodology. NodeListArrays have begin() and end() methods that return iterators, and the iterators have a ++ increment method. This allows you to use NodeListArrays with many of c++'s stl functionality, such as std::find(), std::sort(), range based for loops, etc., making your code much cleaner and more readable.