Forest Class

An immutable forest of ForestNode. Enforces single parenting, and allows querying the parent.

Signature

export declare class Forest

Static Methods

Method	Return Type	Description
create(expensiveValidation)	Forest	Creates a new Forest.

Properties

Property	Type	Description
size	number	Returns the number of nodes in the forest.

Methods

Method	Return Type	Description
add(nodes)	Forest	Adds the supplied nodes to the forest. The nodes' IDs must be unique in the forest.
assertConsistent()	void	Checks that the metadata is correct, and the items form a forest. This is an expensive O(map size) operation.
attachRangeOfChildren(parentId, label, index, childIds)	Forest	Parents a set of nodes already in the forest at a specified location within a trait.
delete(ids, deleteChildren)	Forest	Deletes every node in ids (each of which must be unparented)
delta(forest)	Delta<NodeId>	Calculate the difference between two forests.
detachRangeOfChildren(parentId, label, startIndex, endIndex)	{ forest: Forest; detached: readonly NodeId[]; }	Detaches a range of nodes from their parent. The detached nodes remain in the Forest.
equals(forest)	boolean	Compares two forests for equality.
get(id)	ForestNode
getParent(id)	ParentData
has(id)	boolean
setValue(nodeId, value)	Forest	Replaces a node's value. The node must exist in this Forest.
tryGet(id)	ForestNode | undefined
tryGetParent(id)	ParentData | undefined

Property Details

size

Returns the number of nodes in the forest.

Signature

get size(): number;

Type: number

Method Details

add

Adds the supplied nodes to the forest. The nodes' IDs must be unique in the forest.

Signature

add(nodes: Iterable<ForestNode>): Forest;

Parameters

Parameter	Type	Description
nodes	Iterable<ForestNode>	the sequence of nodes to add to the forest. If any of them have children which exist in the forest already, those children will be parented. Any trait arrays present in a node must be non-empty. The nodes may be provided in any order.

Returns

Return type: Forest

assertConsistent

Checks that the metadata is correct, and the items form a forest. This is an expensive O(map size) operation.

Signature

assertConsistent(): void;

attachRangeOfChildren

Parents a set of nodes already in the forest at a specified location within a trait.

Signature

attachRangeOfChildren(parentId: NodeId, label: TraitLabel, index: number, childIds: readonly NodeId[]): Forest;

Parameters

Parameter	Type	Description
parentId	NodeId	the id of the parent under which to insert the new nodes
label	TraitLabel	the label of the trait under which to insert the new nodes
index	number	the index in the trait after which to insert the new nodes
childIds	readonly NodeId[]	the ids of the nodes to insert

Returns

Return type: Forest

create

Creates a new Forest.

Signature

static create(expensiveValidation?: boolean): Forest;

Parameters

Parameter	Modifiers	Type	Description
expensiveValidation	optional	boolean

Returns

Return type: Forest

delete

Deletes every node in ids (each of which must be unparented)

Signature

delete(ids: Iterable<NodeId>, deleteChildren: boolean): Forest;

Parameters

Parameter	Type	Description
ids	Iterable<NodeId>	The IDs of the nodes to delete.
deleteChildren	boolean	If true, recursively deletes descendants. Otherwise, leaves children unparented.

Returns

Return type: Forest

delta

Calculate the difference between two forests.

Signature

delta(forest: Forest): Delta<NodeId>;

Parameters

Parameter	Type	Description
forest	Forest	the other forest to compare to this one

Returns

A Delta listing which nodes must be changed, added, and removed to get from this to forest.

Return type: Delta<NodeId>

detachRangeOfChildren

Detaches a range of nodes from their parent. The detached nodes remain in the Forest.

Signature

detachRangeOfChildren(parentId: NodeId, label: TraitLabel, startIndex: number, endIndex: number): {
        forest: Forest;
        detached: readonly NodeId[];
    };

Parameters

Parameter	Type	Description
parentId	NodeId	the id of the parent from which to detach the nodes
label	TraitLabel	the label of the trait from which to detach the nodes
startIndex	number	the index of the first node in the range to detach
endIndex	number	the index after the last node in the range to detach

Returns

a new Forest with the nodes detached, and a list of the ids of the nodes that were detached

Return type: { forest: Forest; detached: readonly NodeId[]; }

equals

Compares two forests for equality.

Signature

equals(forest: Forest): boolean;

Parameters

Parameter	Type	Description
forest	Forest	the other forest to compare to this one

Returns

true iff the forests are equal.

Return type: boolean

get

Signature

get(id: NodeId): ForestNode;

Parameters

Parameter	Type	Description
id	NodeId

Returns

the node associated with id. Should not be used if there is no node with the provided id.

Return type: ForestNode

getParent

Signature

getParent(id: NodeId): ParentData;

Parameters

Parameter	Type	Description
id	NodeId

Returns

the parent of id. Should not be used if there is no node with id or if id refers to the root node.

Return type: ParentData

has

Signature

has(id: NodeId): boolean;

Parameters

Parameter	Type	Description
id	NodeId

Returns

true if the node associated with id exists in this forest, otherwise false

Return type: boolean

setValue

Replaces a node's value. The node must exist in this Forest.

Signature

setValue(nodeId: NodeId, value: Payload | null): Forest;

Parameters

Parameter	Type	Description
nodeId	NodeId	the id of the node
value	Payload | null	the new value

Returns

Return type: Forest

tryGet

Signature

tryGet(id: NodeId): ForestNode | undefined;

Parameters

Parameter	Type	Description
id	NodeId

Returns

the node associated with id, or undefined if there is none

Return type: ForestNode | undefined

tryGetParent

Signature

tryGetParent(id: NodeId): ParentData | undefined;

Parameters

Parameter	Type	Description
id	NodeId

Returns

undefined iff root, otherwise the parent of id.

Return type: ParentData | undefined