Class ANode

DescriptionHierarchyFieldsMethodsProperties

Unit

Declaration

type ANode = class(APrintingObject, CanStream)

Description

This class represents a single object in a hierarchical linked list. Each node is capable of linking and unlinking with others and each node can have children which are, themselves, nodes capable of linking to others and having children.

As presented here, this class provides the basic functionality for more sophisticated lists. The class does not define a storage mechanism for data besides that which is necessary to maintain a list of node; that is the purview of descendant classes.

Hierarchy

Overview

Fields

Protected MyParent: ANode;
Protected MyPrevious: ANode;
Protected MyNext: ANode;
Protected MyChild: ANode;
Protected myChildCount: TCensus;

Methods

Public constructor before(const Other: ANode); virtual;
Public constructor after(const Other: ANode); virtual;
Public constructor asChildOf(const Other: ANode); virtual;
Public function init: boolean; override;
Public destructor destroy; override;
Public procedure attach(const Other: ANode); virtual;
Public procedure attachTo(const Other: ANode); virtual;
Public procedure insertBefore(const Other: ANode); virtual;
Public procedure insertAfter(const Other: ANode); virtual;
Public procedure append(const Sibling: ANode); virtual;
Public procedure prepend(const Sibling: ANode); virtual;
Public procedure swapWith(const Other: ANode); virtual;
Public function SiblingAtRelativePosition(relativePosition: TIndexRelative): ANode; virtual;
Public function SiblingAtAbsolutePosition(absolutePosition: TIndexAbsolute): ANode; virtual;
Public procedure detach; virtual;
Public procedure detachFromParent; virtual;
Public procedure adoptChildrenOf(const Other: ANode); virtual;
Public procedure freeChildren; virtual;
Public function selfStreamingLength: TStreamIOSize; virtual;
Public function writeSelfTo(const Dest: AStream): TStreamIOSize; virtual;
Public function printSelfTo(const Dest: ATextOutputStream; prefix: AnsiString = ''; suffix: AnsiString = ''): TStreamIOSize; virtual;
Public function streamingLength: TStreamIOSize; virtual;
Public function writeTo(const Dest: AStream): TStreamIOSize; virtual;
Public function readFrom(const Source: AStream): TStreamIOSize; virtual;
Public function toString: AnsiString; override;
Public function printTo(const Dest: ATextOutputStream; prefix: AnsiString = ''; suffix: AnsiString = ''): TStreamIOSize; override;
Public function hasChildren: boolean; virtual;
Public function Parent: ANode; virtual;
Public function Previous: ANode; virtual;
Public function Next: ANode; virtual;
Public function Child: ANode; virtual;
Public function census: TCensus; virtual;

Description

Fields

Protected MyParent: ANode;

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

Protected MyPrevious: ANode;

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

Protected MyNext: ANode;

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

Protected MyChild: ANode;

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

Protected myChildCount: TCensus;

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

Methods

Public constructor before(const Other: ANode); virtual;

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

Public constructor after(const Other: ANode); virtual;

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

Public constructor asChildOf(const Other: ANode); virtual;

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

Public function init: boolean; override;

Initializer

Public destructor destroy; override;

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.

Public procedure attach(const Other: ANode); virtual;

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

Public procedure attachTo(const Other: ANode); virtual;

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

Public procedure insertBefore(const Other: ANode); virtual;

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.

Public procedure insertAfter(const Other: ANode); virtual;

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.

Public procedure append(const Sibling: ANode); virtual;

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

Public procedure prepend(const Sibling: ANode); virtual;

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

Public procedure swapWith(const Other: ANode); virtual;

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

Public function SiblingAtRelativePosition(relativePosition: TIndexRelative): ANode; virtual;

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.

Public function SiblingAtAbsolutePosition(absolutePosition: TIndexAbsolute): ANode; virtual;

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.

Public procedure detach; virtual;

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.

Public procedure detachFromParent; virtual;

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.

Public procedure adoptChildrenOf(const Other: ANode); virtual;

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.

Public procedure freeChildren; virtual;

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

Public function selfStreamingLength: TStreamIOSize; virtual;

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.

Public function writeSelfTo(const Dest: AStream): TStreamIOSize; virtual;

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.

Public function printSelfTo(const Dest: ATextOutputStream; prefix: AnsiString = ''; suffix: AnsiString = ''): TStreamIOSize; virtual;

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.

Public function streamingLength: TStreamIOSize; virtual;

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.

Public function writeTo(const Dest: AStream): TStreamIOSize; virtual;

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.

Public function readFrom(const Source: AStream): TStreamIOSize; virtual;

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.

Public function toString: AnsiString; override;

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.

Public function printTo(const Dest: ATextOutputStream; prefix: AnsiString = ''; suffix: AnsiString = ''): TStreamIOSize; override;

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.

Public function hasChildren: boolean; virtual;

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.

Public function Parent: ANode; virtual;

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.

Public function Previous: ANode; virtual;

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.

Public function Next: ANode; virtual;

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.

Public function Child: ANode; virtual;

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.

Public function census: TCensus; virtual;

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


Generated by PasDoc 0.13.0 on 2015-06-23 19:40:11