function CanPasteNode: Boolean;
function CanPasteNode(var Name :String): Boolean;

Returns True if there is a qubtree on the clipboard. Optionally retrieve the name of its root.

INode

A class to work with QUB Trees in Delphi pascal.

TNode.Create( name :String )

name      the new node's name.

Creates an unconnected node.

TNode.CreateNull

Creates an INode that refers to no node.

TNode.CreateUsing( node :TQUB_QFS_PNodeMem )

node      a pointer to a node's c structure

Creates a convenient INode from a pointer that is typically passed from a C dll or stored in a list of untyped pointers.

TNode.CreateFromText( path :String )

path      the path to a textfile containing a tree. (see saveAsText)

Reads in a tree from a plain-text file. Does not leave the file open.

TNode.CreateFromString( treeString :String )

treeString      a string containing a plain-text tree

Reads in a tree from the string.

TNode.Paste()

Pastes a qubtree from the clipboard. You should check if it's possible first using CanPasteNode(). If it fails the node is null.

TNode.Open( path :String )

path      the path to a qubtree binary file

Opens a qubtree binary file and returns the root node. Leaves the file open for modifications. If root.IsNull, the file could not be opened.

TNode.OpenReadOnly( path :String )

path      the path to a qubtree binary file

Opens a qubtree binary file and returns the root node. Leaves the file open for [un]loading data. If root.IsNull, the file could not be opened.

IsNull

true if this INode refers to no node

NodeType

Normally this is QUB_NODETYPE_TNODE, for nodes of type TNode.
If another library is handling storage but providing an INode interface, e.g. TQUB_QFS_Node, this will be different. Some methods work only with TNode; e.g. AppendChild.

Name

string: read/write: the node's name

IsInFile

true if this node is in an open file

Path

the path of this node's file, if IsInFile

Child

INode: this node's first child

Sibling

INode: this node's next sibling (parent's next child)

Parent

INode: the node which has this node as a child, possibly null

LineComment

string: read/write: the comment appearing with the node in the text representation.

Preload

Boolean: read/write: whether the data should be loaded into RAM when this node is read from disk.

Changed

Boolean: read/write: Set this to True if you have modified the data, or your changes might not be saved.

DataType

TQUB_QFS_Node_DataType: The type of the node's data. See QUB_QFS for the list.

DataCount

LongWord: how many elements of data -- (Rows * Cols) or string length as appropriate.

Data[ index ]

Variant: read/write: access the data as an array. index must be within LoadBounds.

Rows

Integer: the number of data rows (for strings: number of chars)

Cols

Integer: the number of data columns (for strings: 1)

MatrixData[ row, col ]

Variant: read/write: access the data as a matrix. row must be within LoadRowBounds.

RowSize

LongWord: how many bytes one row of data takes up. Useful if you're copying (RowSize * Rows) bytes to/from DataPtr.

DataAsString

String: A string representing the data, no matter what DataType it actually is.

DataPtr

Pointer: the location of the loaded data in RAM.

LoadBounds

TQUB_FirstLast: The range of data which is available in memory. See LoadRows.

LoadRowBounds

TQUB_FirstLast: The range of data rows available in memory. See LoadRows.

Save()

If IsInFile, writes changes to disk.

SaveAs( path :String )

path      where on disk to save it
returns      true if successful

Saves the node as a binary file, and leaves the file open for further modifications.
This node will be the root of that file's tree. If it has a parent, it will be removed first.

SaveAsText( path :String )

path      file name

Saves the node in plain text.

Close()

If IsInFile, closes the file without saving. The file's contents remain available in memory.

To avoid copying a large file into memory when you're done with it, make sure you hold no references except the root node (set all INode variables pointing into the tree to nil), then set rootNode to nil. The file is closed automatically when there are no references to its root node.

GetNodeMem: TQUB_QFS_PNodeMem

Returns a pointer to the underlying C node struct. Useful for passing nodes to C++. If you're planning on keeping this pointer around, please Node_INCREF( nodemem ), then when you're done, Node_DECREF( nodemem ).

equals( anotherNode :INode )

anotherNode      INode
returns      true if this node and anotherNode refer to the same underlying node.

Clone( deep :Boolean )

deep      true: copy the subtree rooted here. false: copy just this node and its data.
default: true
returns      INode

Makes a copy of this node.

Copy()

Copies this node (and its children) to the clipboard.

INode[ childName :String ]

childName      name of a child node
returns      INode

Gets the first child node named childName. If none exist, one will be created. If you'd rather not have one created, use Find instead.

Find( name :String )

name      the name of a child node
returns      INode, possibly null

Finds the first child node with that name. If none, returns a null node. If you'd rather the missing child be automatically created, use [] (dictionary-style) instead.

Sibling( name :String )

name      the name of a sibling
returns      INode, possibly null

Finds the next sibling with that name. If none, returns a null node.

AppendChild( newChildName :String )

AppendChild( newChild :INode )

newChildName      the name of a node to create and append
newChild      a node to append

Adds a child to this node's children.
If newChild already has a parent, it will be removed first.

AppendClone( Template :INode; Deep :Boolean )

Template      a node
Deep      whether to copy Template's children, or just its data

Copies Template into a newly created child node.

InsertChild( afterChild :INode; newChildName :String )

InsertChild( afterChild :INode; newChild :INode )

afterChild      a child of this node
newChildName      the name of a new child to create and insert
newChild      a node

Adds a child to the list of children, after afterChild. If afterChild.IsNull, inserts as the first child.

InsertClone( AfterChild :INode; Template :INode; Deep :Boolean )

AfterChild      a child of this node
Template      a node
Deep      whether to copy Template's children, or just its data

Copies Template into a newly created child node, inserted after AfterNode.

RemoveChild( child :INode )

RemoveChild( child :INode; prevChild :INode )

child      a child of this node
child      the child before the one you want to remove (prevNode.Sibling.Equals(child))

Removes a child node. It's more efficient if you already know which node is just before it.

RemoveLast( childName :String )

childName      the name of a child node

Removes the last child by that name.

Lock( timeoutMS :Integer )

timeoutMS      how long to wait for the mutex before giving up
returns      true if we got the mutex

The mutex controls all access to the node; most importantly its reference count. Don't hold it for too long.

Unlock

Releases the mutex.

SetupData( type :TQUB_QFS_Node_DataType; size, count :LongWord )

type      e.g. NODE_DATATYPE_LONGINT or NODE_DATATYPE_FLOAT
size      how many bytes one row takes up
count      how many rows
returns      True if successful

Sets up the data but does not initialize it.

SetupNumData( type :TQUB_QFS_Node_DataType; rows, cols :LongWord )

type      e.g. NODE_DATATYPE_LONGINT or NODE_DATATYPE_FLOAT
rows      how many rows
count      how many columns
returns      True if successful

Sets up the data as a matrix of numbers but does not initialize it.

SetData( data :Variant )

data      a number, an array of numbers, or a string
returns      True if successful

Automagically sets up the data and copies the Variant's contents.

ResizeData( rowcount :LongWord )

rowcount      how many rows you want the data to have
returns      True if successful

You can only resize if Rows is nonzero.

ClearData()

Removes any data.

LoadRows( bounds :TQUB_FirstLast; doRead :Boolean )

bounds      the range of data rows to make available in RAM
doRead      true: load the data from disk false: just allocate memory
returns      True if successful

Nodes on disk can keep the data on disk and load portions into RAM as needed. See also: Preload

UnloadRows( doWrite :Boolean )

doWrite      true: write the loaded region to disk false: just free its RAM.
returns      true if successful

Free up some RAM by paging data out to disk. If you know it hasn't changed, use doWrite = false.

ReadRows(Buf :Pointer; Bounds :TQUB_FirstLast): LongWord

Buf      some memory to fill with the requested data
Bounds      the range of rows you're requesting
returns      the number of rows read

Reads a portion of the data into your buffer, whether or not that data is already loaded in RAM.

WriteRows(Buf :Pointer; Bounds :TQUB_FirstLast): LongWord

Buf      some memory containing the data you wish to write
Bounds      the range of rows you're overwriting
returns      the number of rows written

Overwrites a portion of the data with the contents of your buffer, regardless of LoadBounds.