TreeArrayNode Interface

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

Sealed

This type is "sealed," meaning that code outside of the library defining it should not implement or extend it. Future versions of this type may add members or make typing of readonly members more specific.

Signature

/** @sealed */
export interface TreeArrayNode<TAllowedTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe = 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	System_Unsafe.ImplicitAllowedTypesUnsafe	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.
push(value)	void	Inserts new item(s) at the end 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;

Remarks

All items inserted by a single call to this method are inserted consecutively. The order of the inserted items relative to other concurrently inserted items at the same location is only partially specified: Concurrently inserting [A, B] and [X, Y] at the same location may yield either [A, B, X, Y] or [X, Y, A, B], regardless of the order in which those edits are sequenced. No other interleavings are possible. (e.g. [A, X, B, Y] is not possible.)

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;

Remarks

Equivalent to insertAt(array.length, ...value): see insertAt(index, value) for details, including merge semantics with concurrent edits.

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;

Remarks

Equivalent to insertAt(0, ...value): see insertAt(index, value) for details, including merge semantics with concurrent edits.

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).

push

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

Signature

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

Remarks

Unlike Array.prototype.push, this method does not return the new length of the array.

Equivalent to insertAt(array.length, ...value): see insertAt(index, value) for details, including merge semantics with concurrent edits.

Parameters

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

removeAt

Removes the item at the specified location.

Signature

removeAt(index: number): void;

Remarks

The item to remove is determined when this method is called, not when the resulting edit is sequenced. This means that, once the edit is sequenced, the item being removed may no longer be at index, and may in fact no longer be in this array at all (for example, if a concurrent edit moved it to another array). This operation removes that item from wherever it then resides.

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>