IIntervalCollection Interface

Packages > fluid-framework > IIntervalCollection

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

Signature

export interface IIntervalCollection<TInterval extends ISerializableInterval> extends TypedEventEmitter<IIntervalCollectionEvent<TInterval>>

Extends: TypedEventEmitter <IIntervalCollectionEvent <TInterval>>

Type Parameters

Properties

Methods

Property Details

attached

Signature

readonly attached: boolean;

Type: boolean

Method Details

[Symbol.iterator]

Signature

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

Returns

an iterator over all intervals in this collection.

Return type: Iterator<TInterval>

add

Creates a new interval and add it to the collection.

Signature

add({ start, end, props, }: {
        start: SequencePlace;
        end: SequencePlace;
        props?: PropertySet;
    }): TInterval;

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

Returns

• the created interval

Return type: TInterval

attachDeserializer

Signature

attachDeserializer(onDeserialize: DeserializeCallback): void;

Parameters

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.

Signature

attachIndex(index: IntervalIndex<TInterval>): 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

change

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

Signature

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

Parameters

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: TInterval | undefined

CreateBackwardIteratorWithEndPosition

Signature

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

Parameters

Returns

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

Return type: Iterator<TInterval>

CreateBackwardIteratorWithStartPosition

Signature

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

Parameters

Returns

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

Return type: Iterator<TInterval>

CreateForwardIteratorWithEndPosition

Signature

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

Parameters

Returns

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

Return type: Iterator<TInterval>

CreateForwardIteratorWithStartPosition

Signature

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

Parameters

Returns

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

Return type: Iterator<TInterval>

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.

Signature

detachIndex(index: IntervalIndex<TInterval>): boolean;

Parameters

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

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

Signature

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

Parameters

Returns

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

Return type: TInterval[]

gatherIterationResults

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

Signature

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

Parameters

getIntervalById

Signature

getIntervalById(id: string): TInterval | undefined;

Parameters

Returns

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

Return type: TInterval | undefined

map

Applies a function to each interval in this collection.

Signature

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

Parameters

nextInterval

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

Signature

nextInterval(pos: number): TInterval | undefined;

Parameters

Returns

Return type: TInterval | undefined

previousInterval

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

Signature

previousInterval(pos: number): TInterval | undefined;

Parameters

Returns

Return type: TInterval | undefined

removeIntervalById

Removes an interval from the collection.

Signature

removeIntervalById(id: string): TInterval | undefined;

Parameters

Returns

the removed interval

Return type: TInterval | undefined