Class ANode

Refers to the parent node of this node; Nil if the node is top-level

Refers to the previous sibling of this node; Nil if the node is the first node in its associated list.

Refers to the next sibling of this node; Nil if the node is the last node in its associated list.

Refers to the youngest child of this node; Nil if the node has no children.

Store the number of immediate children associated with this node. This count does not include grandchildren.

Construct a new node that will become the older sibling of the node specified by Other.

Construct a new node that will become the younger sibling of the node specified by Other.

Construct a new node that will become the youngest child of the node specified by Other.

Initializer

Destroy the node, its children, and its older siblings.

This method is called automatically when TObject.free is called on the node and so need not be called directly.

Note that this method destroys all children of the node AS WELL AS the older siblings of the node (by recursively traversing ANode.Previous and freeing each node encountered until a Nil result is found). If this is not the desired behavior, the node should be detached from its siblings by calling ANode.detach, and its children reassigned by calling ANode.adoptChildrenOf on another node, before this node is freed.

Otherwise, TObject.free can be called on the youngest node in a list of nodes and it will cause the entire list to be freed.

Attaches the node specified by Other as a child of this node. Other becomes the youngest child of the node.

Attaches this node to the one specified by Other as a child of that node. This node becomes the youngest child of Other.

Inserts this node before the node specified by Other. This node becomes the immediate older sibling of Other. All other older siblings of Other are "promoted" first.

Inserts this node after the node specified by Other. This node becomes the immediate younger sibling of Other. All other younger siblings of Other are "demoted" first.

Appends the node specified by Sibling as the immediate younger sibling of this node. All other younger siblings of this node are "demoted" first.

Prepends the node specified by Sibling as the immediate older sibling of this node. All other older siblings of this node are "promoted" first.

Swaps the position of the current node for that of Other. Children of each node remain with their parents.

Retrieve a reference to the sibling of the current node which is at the specified position relative to the current node.

relativePosition may be a positive or negative value. If a positive value greater than zero (0), then this method will recursively step through the chain of nodes attached to Self.Next until it reaches the node which is relativePosition steps down the chain. If relativePosition is a negative value, then this method will recursively step through the chain of nodes attached to Self.Previous until it reaches the node which is relativePosition steps up the chain. In either case, if the end of the chain is reached before the number of steps specified by relativePosition, then this method will return Nil.

If relativePosition is zero (0), this method returns a reference to the current node (Self).

It may be helpful to remember that the node specified by Self.Previous will always be at position -1 relative to Self, while the node specified by Self.Next will always be at position 1 relative to Self.

Retrieve a reference to the sibling of the current node which is at the specified absolute position relative to the current node.

This method follows the chain of nodes attached to ANode.Previous Self.Previous until it reaches the first node in the chain; it then steps back down through the chain until it reaches the node at the specified position. If the end of the chain is reached before the number of steps specified by absolutePosition, then this method will return Nil.

This method operates on the assumption that node indices are zero-based; therefore, if absolutePosition is zero (0), this method will return a reference to the first node in the chain.

This method can be used to find the node at a specified index within a list of nodes; however, it is worth noting that the index of a node within a linked list can be changed by adding or removing nodes in front of the node in question. Furthermore, for large lists of nodes, this method can be inefficient as it must traverse the chain backwards and then forward again.

Detaches this node and its children from any siblings. This effectively removes the node from its associated list, but it does not free the node or its children.

Detaches this node from its parent. This effectively removes the node from the list of nodes managed by the parent, but it does not free the node or its children.

If the node has no parent, this routine does nothing.

Adopts all children associated with the node specified by Other, effectively transferring those children to the control of this node. Other will no longer have children after this method is called.

Although the children adopted become the youngest children of this node, the relationships between the adoptees remain the same; in other words, the youngest child of Other will still be the youngest child.

Frees all children associated with the node. Calling this method will recursively free the children of the node, and their children, and so forth.

Calculate the number of bytes that will be read from or written to a stream when the node, and just the node, is read or written.

Descendant classes should first call this method, then add to the value returned.

Write the node, and just the node, to the specified stream.

This method is called automatically by ANode.writeTo. It is designed to allow descendant classes to specify the data that each node should write to the given the stream without the need to worry about recursing through child nodes or siblings (ANode.writeTo takes care of that).

The base implementation of this method simply writes the value of ANode.census. It is likely that descendant classes will override this method so that custom data associated with the node is also written to the stream.

Note that it is important that any custom data associated with the node is written BEFORE the value of ANode.census. What this means is that you can override this method to write the custom data associated with your node class, then call the inherited routine to write the value of ANode.census. This will make it possible to recover the node and its children from the stream at a later point in time. See ANode.readFrom for more details.

Returns

The total number of bytes written to Dest.

Print the node, and just the node, to the specified stream.

This method is called automatically by ANode.printTo. It is designed to allow descendant classes to specify the data that each node should print ot the given stream without the need to worry about recursing through child nodes or siblings (ANode.printTo takes care of that).

In the base implementation, this method simply prints the value of a call to ANode.toString.

If prefix and suffix are provided, they are printed before and after the representation of the node.

Returns

The total number of bytes printed to Dest.

Calculate the total number of bytes that will be read or written when either ANode.readFrom or ANode.writeTo is called.

This method will first call itself on the immediate older sibling of the node, which will do the same until the first node is encountered. That node will calculate the value for itself and its children, and then the recursion will proceed back down the list to the current node, ensuring that each node and its children are included in the final calculation.

This method does not actually calculate the size of the the node itself; instead, it calls ANode.selfStreamingLength, which is responsible for calculating the streaming size of the current node.

This method can be called on the youngest node in a list of nodes and it will return with the total number of bytes required to stream the entire list.

Write the node, its children, and its older siblings to the specified stream.

This method will first call itself on the immediate older sibling of the node, which will do the same until the first node is encountered. That node will write itself and its children, and then the recursion will proceed back down the list to the current node, ensuring that each node and its children are written to Dest.

This method does not actually write the node data itself; instead, it calls ANode.writeSelfTo, which is responsible for writing the data retained by this node.

This method can be called on the youngest node in a list of nodes and it will cause the entire list to be written to Dest.

Returns

The total number of bytes written to Dest.

Read the node and its children from the specified stream.

This method will likely be overridden by descendant classes. In its base implementation within ANode, it simply reads the value of ANode.census from Source, constructs a new instance of ANode, and then recursively calls itself on that instance.

Note that the new instance of ANode created will actually be an instance of that descendant of ANode upon which this method is called; the base implementation of this method obtains the current class by calling TObject.classType on itself and then calls on that class implementation to construct a new node. What this means is that you can override the implementation of this method to read any custom data that is stored in Dest, then call the inherited routine to ensure that all children of the node are likewise read, so long as any custom data related to the given node was written BEFORE the value of ANode.census.

Returns

The total number of bytes read from Dest.

Obtain a string representation of the node, suitable for printing to a console or text-based device.

The base implementation of this method within ANode simply returns the class name of the node and a count of the node's children. The format of this string is specified by nodeStringRepresentationPlural or nodeStringRepresentationSingular, respectively.

Print a string representation of the node, its children, and its older siblings to the specified stream.

This method will first call itself on the immediate older sibling of the node, which will do the same until the first node is encountered. That node will print itself and its children, and then the recursion will proceed back down the list to the current node, ensuring that each node and its children are printed to Dest.

This method does not actually print the node data itself; instead, it calls ANode.printSelfTo, which is responsible for writing the data retained by this node.

prefix and suffix are not used directly by this method, but they are passed to ANode.printSelfTo.

This method can be called on the youngest node in a list of nodes and it will cause the entire list to be printed to Dest.

Returns

The total number of bytes printed to Dest.

Determine whether or not the node has children.

This method tests to see whether ANode.Child is not Nil and whether ANode.census is greater than zero. If neither condition is true, then the routine returns False to indicate that the node has no children; if both conditions are true, then the routine returns True.

Retrieves a pointer to the parent of the node. If the node is a top-level node, the value returned by this routine will be Nil.

Retrieves a pointer to the immediate older sibling of this node. If this node is the first node in its associated list, then the value returned by this routine will be Nil.

Retrieves a pointer to the immediate younger sibling of this node. If this node is the last node in its associated list, then the value returned by this routine will be Nil.

Retrieves a pointer to the youngest immediate child of this node. If the node has no children, then the value returned by this routine will be Nil.

Retrieves the number of immediate children associated with this node. This count does not include grandchildren.