ISequenceIntervalCollection Interface

Collection of intervals that supports addition, modification, removal, and efficient spatial querying. Changes to this collection will be incur updates on collaborating clients (i.e. they are not local-only).

This API is provided for existing users, but is not recommended for new users.

To use, import via fluid-framework/legacy.

For more information about our API support guarantees, see here.

Signature

export interface ISequenceIntervalCollection extends TypedEventEmitter<ISequenceIntervalCollectionEvents>

Extends: TypedEventEmitter<ISequenceIntervalCollectionEvents>

Properties

Property	Alerts	Modifiers	Type	Description
attached	Beta	readonly	boolean

Methods

Method	Alerts	Return Type	Description
[Symbol.iterator]()	Beta	Iterator<SequenceInterval>
add({ start, end, props, }, input)	Beta	SequenceInterval	Creates a new interval and add it to the collection.
attachDeserializer(onDeserialize)	Deprecated, Beta	void
attachIndex(index)	Beta	void	Attaches an index to this collection. All intervals which are part of this collection will be added to the index, and the index will automatically be updated when this collection updates due to local or remote changes.
change(id, { start, end, props }, input)	Beta	SequenceInterval | undefined	Changes the endpoints, properties, or both of an existing interval.
CreateBackwardIteratorWithEndPosition(endPosition)	Beta	Iterator<SequenceInterval>
CreateBackwardIteratorWithStartPosition(startPosition)	Beta	Iterator<SequenceInterval>
CreateForwardIteratorWithEndPosition(endPosition)	Beta	Iterator<SequenceInterval>
CreateForwardIteratorWithStartPosition(startPosition)	Beta	Iterator<SequenceInterval>
detachIndex(index)	Beta	boolean	Detaches an index from this collection. All intervals which are part of this collection will be removed from the index, and updates to this collection due to local or remote changes will no longer incur updates to the index.
findOverlappingIntervals(startPosition, endPosition)	Deprecated, Beta	SequenceInterval[]
gatherIterationResults(results, iteratesForward, start, end)	Beta	void	Gathers iteration results that optionally match a start/end criteria into the provided array.
getIntervalById(id)	Beta	SequenceInterval | undefined
map(fn)	Beta	void	Applies a function to each interval in this collection.
nextInterval(pos)	Deprecated, Beta	SequenceInterval | undefined
previousInterval(pos)	Deprecated, Beta	SequenceInterval | undefined
removeIntervalById(id)	Beta	SequenceInterval | undefined	Removes an interval from the collection.

Property Details

attached

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly attached: boolean;

Type: boolean

Method Details

[Symbol.iterator]

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

[Symbol.iterator](): Iterator<SequenceInterval>;

Returns

an iterator over all intervals in this collection.

Return type: Iterator<SequenceInterval>

add

Creates a new interval and add it to the collection.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

add(input: {
        start: SequencePlace;
        end: SequencePlace;
        props?: PropertySet;
    }): SequenceInterval;

Remarks

See documentation on SequenceInterval for comments on interval endpoint semantics: there are subtleties with how the current half-open behavior is represented.

Note that intervals may behave unexpectedly if the entire contents of the string are deleted. In this case, it is possible for one endpoint of the interval to become detached, while the other remains on the string.

By adjusting the side and pos values of the start and end parameters, it is possible to control whether the interval expands to include content inserted at its start or end.

See SequencePlace for more details on the model.

Example

Given the string "ABCD":

// Refers to "BC". If any content is inserted before B or after C, this
	// interval will include that content
	//
	// Picture:
	// \{start\} - A[- B - C -]D - \{end\}
	// \{start\} - A - B - C - D - \{end\}
	collection.add(\{ pos: 0, side: Side.After \}, \{ pos: 3, side: Side.Before \}, IntervalType.SlideOnRemove);
	// Equivalent to specifying the same positions and Side.Before.
	// Refers to "ABC". Content inserted after C will be included in the
	// interval, but content inserted before A will not.
	// \{start\} -[A - B - C -]D - \{end\}
	// \{start\} - A - B - C - D - \{end\}
	collection.add(0, 3, IntervalType.SlideOnRemove);

In the case of the first example, if text is deleted,

// Delete the character "B"
	string.removeRange(1, 2);

The start point of the interval will slide to the position immediately before "C", and the same will be true.

\{start\} - A[- C -]D - \{end\}

In this case, text inserted immediately before "C" would be included in the interval.

string.insertText(1, "EFG");

With the string now being,

\{start\} - A[- E - F - G - C -]D - \{end\}

Parameters

Parameter	Type	Description
{ start, end, props, }
input	{ start: SequencePlace; end: SequencePlace; props?: PropertySet; }

Returns

the created interval

Return type: SequenceInterval

attachDeserializer

This API is deprecated and will be removed in a future release.

This api is not meant or necessary for external consumption and will be removed in subsequent release

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

attachDeserializer(onDeserialize: DeserializeCallback): void;

Parameters

Parameter	Type	Description
onDeserialize	DeserializeCallback

attachIndex

Attaches an index to this collection. All intervals which are part of this collection will be added to the index, and the index will automatically be updated when this collection updates due to local or remote changes.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

attachIndex(index: SequenceIntervalIndex): void;

Remarks

After attaching an index to an interval collection, applications should typically store this index somewhere in their in-memory data model for future reference and querying.

Parameters

Parameter	Type	Description
index	SequenceIntervalIndex

change

Changes the endpoints, properties, or both of an existing interval.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

change(id: string, input: {
        start?: SequencePlace;
        end?: SequencePlace;
        props?: PropertySet;
    }): SequenceInterval | undefined;

Parameters

Parameter	Type	Description
id	string	Id of the Interval to change
{ start, end, props }
input	{ start?: SequencePlace; end?: SequencePlace; props?: PropertySet; }

Returns

the interval that was changed, if it existed in the collection. Pass the desired new start position, end position, and/or properties in an object. Start and end positions must be changed simultaneously - they must either both be specified or both undefined. To only change the properties, leave both endpoints undefined. To only change the endpoints, leave the properties undefined.

Return type: SequenceInterval | undefined

CreateBackwardIteratorWithEndPosition

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

CreateBackwardIteratorWithEndPosition(endPosition: number): Iterator<SequenceInterval>;

Parameters

Parameter	Type	Description
endPosition	number

Returns

a backward iterator over all intervals in this collection with end point equal to endPosition.

Return type: Iterator<SequenceInterval>

CreateBackwardIteratorWithStartPosition

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

CreateBackwardIteratorWithStartPosition(startPosition: number): Iterator<SequenceInterval>;

Parameters

Parameter	Type	Description
startPosition	number

Returns

a backward iterator over all intervals in this collection with start point equal to startPosition.

Return type: Iterator<SequenceInterval>

CreateForwardIteratorWithEndPosition

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

CreateForwardIteratorWithEndPosition(endPosition: number): Iterator<SequenceInterval>;

Parameters

Parameter	Type	Description
endPosition	number

Returns

a forward iterator over all intervals in this collection with end point equal to endPosition.

Return type: Iterator<SequenceInterval>

CreateForwardIteratorWithStartPosition

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

CreateForwardIteratorWithStartPosition(startPosition: number): Iterator<SequenceInterval>;

Parameters

Parameter	Type	Description
startPosition	number

Returns

a forward iterator over all intervals in this collection with start point equal to startPosition.

Return type: Iterator<SequenceInterval>

detachIndex

Detaches an index from this collection. All intervals which are part of this collection will be removed from the index, and updates to this collection due to local or remote changes will no longer incur updates to the index.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

detachIndex(index: SequenceIntervalIndex): boolean;

Parameters

Parameter	Type	Description
index	SequenceIntervalIndex

Returns

false if the target index cannot be found in the indexes, otherwise remove all intervals in the index and return true.

Return type: boolean

findOverlappingIntervals

This API is deprecated and will be removed in a future release.

Users must manually attach the corresponding interval index to utilize this functionality, for instance:

const overlappingIntervalsIndex = createOverlappingIntervalsIndex(sharedString);
collection.attachIndex(overlappingIntervalsIndex)
const result = overlappingIntervalsIndex.findOverlappingIntervals(start, end);

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

findOverlappingIntervals(startPosition: number, endPosition: number): SequenceInterval[];

Parameters

Parameter	Type	Description
startPosition	number
endPosition	number

Returns

an array of all intervals in this collection that overlap with the interval [startPosition, endPosition].

Return type: SequenceInterval[]

gatherIterationResults

Gathers iteration results that optionally match a start/end criteria into the provided array.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

gatherIterationResults(results: SequenceInterval[], iteratesForward: boolean, start?: number, end?: number): void;

Parameters

Parameter	Modifiers	Type	Description
results		SequenceInterval[]	Array to gather the results into. In lieu of a return value, this array will be populated with intervals matching the query upon edit.
iteratesForward		boolean	whether or not iteration should be in the forward direction
start	optional	number	If provided, only match intervals whose start point is equal to start.
end	optional	number	If provided, only match intervals whose end point is equal to end.

getIntervalById

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getIntervalById(id: string): SequenceInterval | undefined;

Parameters

Parameter	Type	Description
id	string

Returns

the interval in this collection that has the provided id. If no interval in the collection has this id, returns undefined.

Return type: SequenceInterval | undefined

map

Applies a function to each interval in this collection.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

map(fn: (interval: SequenceInterval) => void): void;

Parameters

Parameter	Type	Description
fn	(interval: SequenceInterval) => void

nextInterval

This API is deprecated and will be removed in a future release.

due to the forthcoming change where the endpointIndex will no longer be automatically added to the collection. Users are advised to independently attach the index to the collection and utilize the API accordingly, for instance:

const endpointIndex = createEndpointIndex(sharedString);
collection.attachIndex(endpointIndex);
const result2 = endpointIndex.nextInterval(pos);

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

nextInterval(pos: number): SequenceInterval | undefined;

Parameters

Parameter	Type	Description
pos	number

Returns

Return type: SequenceInterval | undefined

previousInterval

This API is deprecated and will be removed in a future release.

due to the forthcoming change where the endpointIndex will no longer be automatically added to the collection. Users are advised to independently attach the index to the collection and utilize the API accordingly, for instance:

const endpointIndex = createEndpointIndex(sharedString);
collection.attachIndex(endpointIndex);
const result1 = endpointIndex.previousInterval(pos);

If an index is used repeatedly, applications should generally attach it once and store it in memory.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

previousInterval(pos: number): SequenceInterval | undefined;

Parameters

Parameter	Type	Description
pos	number

Returns

Return type: SequenceInterval | undefined

removeIntervalById

Removes an interval from the collection.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

removeIntervalById(id: string): SequenceInterval | undefined;

Parameters

Parameter	Type	Description
id	string	Id of the interval to remove

Returns

the removed interval

Return type: SequenceInterval | undefined