Skip to main content

TreeArrayNode Interface

A TreeNode which implements 'readonly T[]' and the array mutation APIs.

Signature​

/** @sealed */
export interface TreeArrayNode<TAllowedTypes extends Unenforced<ImplicitAllowedTypes> = ImplicitAllowedTypes, out T = [TAllowedTypes] extends [ImplicitAllowedTypes] ? TreeNodeFromImplicitAllowedTypes<TAllowedTypes> : TreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>, in TNew = [TAllowedTypes] extends [ImplicitAllowedTypes] ? InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes> : InsertableTreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>, in TMoveFrom = ReadonlyArrayNode> extends ReadonlyArrayNode<T>

Extends: ReadonlyArrayNode<T>

Type Parameters​

Parameter Constraint Default Description
TAllowedTypes Unenforced<ImplicitAllowedTypes> ImplicitAllowedTypes Schema for types which are allowed as members of this array.
T [TAllowedTypes] extends [ImplicitAllowedTypes] ? TreeNodeFromImplicitAllowedTypes<TAllowedTypes> : TreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes> Use Default: Do not specify. Type of values to read from the array.
TNew [TAllowedTypes] extends [ImplicitAllowedTypes] ? InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes> : InsertableTreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes> Use Default: Do not specify. Type of values to write into the array.
TMoveFrom ReadonlyArrayNode Use Default: Do not specify. Type of node from which children can be moved into this array.

Methods​

Method Return Type Description
insertAt(index, value) void Inserts new item(s) at a specified location.
insertAtEnd(value) void Inserts new item(s) at the end of the array.
insertAtStart(value) void Inserts new item(s) at the start of the array.
moveRangeToEnd(sourceStart, sourceEnd) void Moves the specified items to the end of the array.
moveRangeToEnd(sourceStart, sourceEnd, source) void Moves the specified items to the end of the array.
moveRangeToIndex(destinationGap, sourceStart, sourceEnd) void

Moves the specified items to the desired location within the array.

WARNING - This API is easily misused. Please read the documentation for the destinationGap parameter carefully.
moveRangeToIndex(destinationGap, sourceStart, sourceEnd, source) void

Moves the specified items to the desired location within the array.

WARNING - This API is easily misused. Please read the documentation for the destinationGap parameter carefully.
moveRangeToStart(sourceStart, sourceEnd) void Moves the specified items to the start of the array.
moveRangeToStart(sourceStart, sourceEnd, source) void Moves the specified items to the start of the array.
moveToEnd(sourceIndex) void Moves the specified item to the end of the array.
moveToEnd(sourceIndex, source) void Moves the specified item to the end of the array.
moveToIndex(destinationGap, sourceIndex) void

Moves the specified item to the desired location in the array.

WARNING - This API is easily misused. Please read the documentation for the destinationGap parameter carefully.
moveToIndex(destinationGap, sourceIndex, source) void

Moves the specified item to the desired location in the array.

WARNING - This API is easily misused. Please read the documentation for the destinationGap parameter carefully.
moveToStart(sourceIndex) void Moves the specified item to the start of the array.
moveToStart(sourceIndex, source) void Moves the specified item to the start of the array.
removeAt(index) void Removes the item at the specified location.
removeRange(start, end) void Removes all items between the specified indices.
values() IterableIterator<T> Returns a custom IterableIterator which throws usage errors if concurrent editing and iteration occurs.

Method Details​

insertAt​

Inserts new item(s) at a specified location.

Signature​

insertAt(index: number, ...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;

Parameters​

Parameter Type Description
index number The index at which to insert value.
value readonly (TNew | IterableTreeArrayContent<TNew>)[] The content to insert.

Error Handling​

Throws if index is not in the range [0, array.length).

insertAtEnd​

Inserts new item(s) at the end of the array.

Signature​

insertAtEnd(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;

Parameters​

Parameter Type Description
value readonly (TNew | IterableTreeArrayContent<TNew>)[] The content to insert.

insertAtStart​

Inserts new item(s) at the start of the array.

Signature​

insertAtStart(...value: readonly (TNew | IterableTreeArrayContent<TNew>)[]): void;

Parameters​

Parameter Type Description
value readonly (TNew | IterableTreeArrayContent<TNew>)[] The content to insert.

moveRangeToEnd​

Moves the specified items to the end of the array.

Signature​

moveRangeToEnd(sourceStart: number, sourceEnd: number): void;

Parameters​

Parameter Type Description
sourceStart number The starting index of the range to move (inclusive).
sourceEnd number The ending index of the range to move (exclusive)

Error Handling​

Throws if either of the input indices are not in the range [0, array.length) or if sourceStart is greater than sourceEnd. if any of the input indices are not in the range [0, array.length], or if sourceStart is greater than sourceEnd.

moveRangeToEnd​

Moves the specified items to the end of the array.

Signature​

moveRangeToEnd(sourceStart: number, sourceEnd: number, source: TMoveFrom): void;

Parameters​

Parameter Type Description
sourceStart number The starting index of the range to move (inclusive).
sourceEnd number The ending index of the range to move (exclusive)
source TMoveFrom The source array to move items out of.

Error Handling​

Throws if the types of any of the items being moved are not allowed in the destination array, if either of the input indices are not in the range [0, array.length) or if sourceStart is greater than sourceEnd. if any of the input indices are not in the range [0, array.length], or if sourceStart is greater than sourceEnd.

moveRangeToIndex​

Moves the specified items to the desired location within the array.

WARNING - This API is easily misused. Please read the documentation for the destinationGap parameter carefully.

Signature​

moveRangeToIndex(destinationGap: number, sourceStart: number, sourceEnd: number): void;

Parameters​

Parameter Type Description
destinationGap number

The location *between* existing items that the moved item should be moved to.

WARNING - destinationGap describes a location between existing items *prior to applying the move operation*.

For example, if the array contains items [A, B, C] before the move, the destinationGap must be one of the following:

- 0 (between the start of the array and A's original position) - 1 (between A's original position and B's original position) - 2 (between B's original position and C's original position) - 3 (between C's original position and the end of the array)

So moving A between B and C would require destinationGap to be 2.

This interpretation of destinationGap makes it easy to specify the desired destination relative to a sibling item that is not being moved, or relative to the start or end of the array:

- Move to the start of the array: array.moveToIndex(0, ...) (see also moveToStart) - Move to before some item X: array.moveToIndex(indexOfX, ...) - Move to after some item X: array.moveToIndex(indexOfX + 1, ...) - Move to the end of the array: array.moveToIndex(array.length, ...) (see also moveToEnd)

This interpretation of destinationGap does however make it less obvious how to move an item relative to its current position:

- Move item B before its predecessor: array.moveToIndex(indexOfB - 1, ...) - Move item B after its successor: array.moveToIndex(indexOfB + 2, ...)

Notice the asymmetry between -1 and +2 in the above examples. In such scenarios, it can often be easier to approach such edits by swapping adjacent items: If items A and B are adjacent, such that A precedes B, then they can be swapped with array.moveToIndex(indexOfA, indexOfB).
sourceStart number The starting index of the range to move (inclusive).
sourceEnd number The ending index of the range to move (exclusive)

Error Handling​

Throws if any of the input indices are not in the range [0, array.length) or if sourceStart is greater than sourceEnd. if any of the input indices are not in the range [0, array.length], or if sourceStart is greater than sourceEnd.

moveRangeToIndex​

Moves the specified items to the desired location within the array.

WARNING - This API is easily misused. Please read the documentation for the destinationGap parameter carefully.

Signature​

moveRangeToIndex(destinationGap: number, sourceStart: number, sourceEnd: number, source: TMoveFrom): void;

Parameters​

Parameter Type Description
destinationGap number

The location *between* existing items that the moved item should be moved to.

WARNING - destinationGap describes a location between existing items *prior to applying the move operation*.

For example, if the array contains items [A, B, C] before the move, the destinationGap must be one of the following:

- 0 (between the start of the array and A's original position) - 1 (between A's original position and B's original position) - 2 (between B's original position and C's original position) - 3 (between C's original position and the end of the array)

So moving A between B and C would require destinationGap to be 2.

This interpretation of destinationGap makes it easy to specify the desired destination relative to a sibling item that is not being moved, or relative to the start or end of the array:

- Move to the start of the array: array.moveToIndex(0, ...) (see also moveToStart) - Move to before some item X: array.moveToIndex(indexOfX, ...) - Move to after some item X: array.moveToIndex(indexOfX + 1, ...) - Move to the end of the array: array.moveToIndex(array.length, ...) (see also moveToEnd)

This interpretation of destinationGap does however make it less obvious how to move an item relative to its current position:

- Move item B before its predecessor: array.moveToIndex(indexOfB - 1, ...) - Move item B after its successor: array.moveToIndex(indexOfB + 2, ...)

Notice the asymmetry between -1 and +2 in the above examples. In such scenarios, it can often be easier to approach such edits by swapping adjacent items: If items A and B are adjacent, such that A precedes B, then they can be swapped with array.moveToIndex(indexOfA, indexOfB).
sourceStart number The starting index of the range to move (inclusive).
sourceEnd number The ending index of the range to move (exclusive)
source TMoveFrom The source array to move items out of.

Error Handling​

Throws if the types of any of the items being moved are not allowed in the destination array, if any of the input indices are not in the range [0, array.length], or if sourceStart is greater than sourceEnd.

moveRangeToStart​

Moves the specified items to the start of the array.

Signature​

moveRangeToStart(sourceStart: number, sourceEnd: number): void;

Parameters​

Parameter Type Description
sourceStart number The starting index of the range to move (inclusive).
sourceEnd number The ending index of the range to move (exclusive)

Error Handling​

Throws if either of the input indices are not in the range [0, array.length) or if sourceStart is greater than sourceEnd. if any of the input indices are not in the range [0, array.length], or if sourceStart is greater than sourceEnd.

moveRangeToStart​

Moves the specified items to the start of the array.

Signature​

moveRangeToStart(sourceStart: number, sourceEnd: number, source: TMoveFrom): void;

Parameters​

Parameter Type Description
sourceStart number The starting index of the range to move (inclusive).
sourceEnd number The ending index of the range to move (exclusive)
source TMoveFrom The source array to move items out of.

Error Handling​

Throws if the types of any of the items being moved are not allowed in the destination array, if either of the input indices are not in the range [0, array.length) or if sourceStart is greater than sourceEnd. if any of the input indices are not in the range [0, array.length], or if sourceStart is greater than sourceEnd.

moveToEnd​

Moves the specified item to the end of the array.

Signature​

moveToEnd(sourceIndex: number): void;

Parameters​

Parameter Type Description
sourceIndex number The index of the item to move.

Error Handling​

Throws if sourceIndex is not in the range [0, array.length).

moveToEnd​

Moves the specified item to the end of the array.

Signature​

moveToEnd(sourceIndex: number, source: TMoveFrom): void;

Parameters​

Parameter Type Description
sourceIndex number The index of the item to move.
source TMoveFrom The source array to move the item out of.

Error Handling​

Throws if sourceIndex is not in the range [0, array.length).

moveToIndex​

Moves the specified item to the desired location in the array.

WARNING - This API is easily misused. Please read the documentation for the destinationGap parameter carefully.

Signature​

moveToIndex(destinationGap: number, sourceIndex: number): void;

Parameters​

Parameter Type Description
destinationGap number

The location *between* existing items that the moved item should be moved to.

WARNING - destinationGap describes a location between existing items *prior to applying the move operation*.

For example, if the array contains items [A, B, C] before the move, the destinationGap must be one of the following:

- 0 (between the start of the array and A's original position) - 1 (between A's original position and B's original position) - 2 (between B's original position and C's original position) - 3 (between C's original position and the end of the array)

So moving A between B and C would require destinationGap to be 2.

This interpretation of destinationGap makes it easy to specify the desired destination relative to a sibling item that is not being moved, or relative to the start or end of the array:

- Move to the start of the array: array.moveToIndex(0, ...) (see also moveToStart) - Move to before some item X: array.moveToIndex(indexOfX, ...) - Move to after some item X: array.moveToIndex(indexOfX + 1, ...) - Move to the end of the array: array.moveToIndex(array.length, ...) (see also moveToEnd)

This interpretation of destinationGap does however make it less obvious how to move an item relative to its current position:

- Move item B before its predecessor: array.moveToIndex(indexOfB - 1, ...) - Move item B after its successor: array.moveToIndex(indexOfB + 2, ...)

Notice the asymmetry between -1 and +2 in the above examples. In such scenarios, it can often be easier to approach such edits by swapping adjacent items: If items A and B are adjacent, such that A precedes B, then they can be swapped with array.moveToIndex(indexOfA, indexOfB).
sourceIndex number The index of the item to move.

Error Handling​

Throws if any of the input indices are not in the range [0, array.length).

moveToIndex​

Moves the specified item to the desired location in the array.

WARNING - This API is easily misused. Please read the documentation for the destinationGap parameter carefully.

Signature​

moveToIndex(destinationGap: number, sourceIndex: number, source: TMoveFrom): void;

Parameters​

Parameter Type Description
destinationGap number

The location *between* existing items that the moved item should be moved to.

WARNING - destinationGap describes a location between existing items *prior to applying the move operation*.

For example, if the array contains items [A, B, C] before the move, the destinationGap must be one of the following:

- 0 (between the start of the array and A's original position) - 1 (between A's original position and B's original position) - 2 (between B's original position and C's original position) - 3 (between C's original position and the end of the array)

So moving A between B and C would require destinationGap to be 2.

This interpretation of destinationGap makes it easy to specify the desired destination relative to a sibling item that is not being moved, or relative to the start or end of the array:

- Move to the start of the array: array.moveToIndex(0, ...) (see also moveToStart) - Move to before some item X: array.moveToIndex(indexOfX, ...) - Move to after some item X: array.moveToIndex(indexOfX + 1, ...) - Move to the end of the array: array.moveToIndex(array.length, ...) (see also moveToEnd)

This interpretation of destinationGap does however make it less obvious how to move an item relative to its current position:

- Move item B before its predecessor: array.moveToIndex(indexOfB - 1, ...) - Move item B after its successor: array.moveToIndex(indexOfB + 2, ...)

Notice the asymmetry between -1 and +2 in the above examples. In such scenarios, it can often be easier to approach such edits by swapping adjacent items: If items A and B are adjacent, such that A precedes B, then they can be swapped with array.moveToIndex(indexOfA, indexOfB).
sourceIndex number The index of the item to move.
source TMoveFrom The source array to move the item out of.

Error Handling​

Throws if any of the source index is not in the range [0, array.length), or if the index is not in the range [0, array.length].

moveToStart​

Moves the specified item to the start of the array.

Signature​

moveToStart(sourceIndex: number): void;

Parameters​

Parameter Type Description
sourceIndex number The index of the item to move.

Error Handling​

Throws if sourceIndex is not in the range [0, array.length).

moveToStart​

Moves the specified item to the start of the array.

Signature​

moveToStart(sourceIndex: number, source: TMoveFrom): void;

Parameters​

Parameter Type Description
sourceIndex number The index of the item to move.
source TMoveFrom The source array to move the item out of.

Error Handling​

Throws if sourceIndex is not in the range [0, array.length).

removeAt​

Removes the item at the specified location.

Signature​

removeAt(index: number): void;

Parameters​

Parameter Type Description
index number The index at which to remove the item.

Error Handling​

Throws if index is not in the range [0, array.length).

removeRange​

Removes all items between the specified indices.

Signature​

removeRange(start?: number, end?: number): void;

Remarks​

The default values for start and end are computed when this is called, and thus the behavior is the same as providing them explicitly, even with respect to merge resolution with concurrent edits. For example, two concurrent transactions both emptying the array with node.removeRange() then inserting an item, will merge to result in the array having both inserted items.

Parameters​

Parameter Modifiers Type Description
start optional number The starting index of the range to remove (inclusive). Defaults to the start of the array.
end optional number The ending index of the range to remove (exclusive). Defaults to array.length.

Error Handling​

Throws if start is not in the range [0, array.length].

Throws if end is less than start. If end is not supplied or is greater than the length of the array, all items after start are removed.

values​

Returns a custom IterableIterator which throws usage errors if concurrent editing and iteration occurs.

Signature​

values(): IterableIterator<T>;

Returns​

Return type: IterableIterator<T>