Skip to main content

IIntervalCollection 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 IIntervalCollection<TInterval extends ISerializableInterval> extends TypedEventEmitter<IIntervalCollectionEvent<TInterval>>

Extends: TypedEventEmitter<IIntervalCollectionEvent<TInterval>>

Type Parameters​

Parameter Constraint Description
TInterval ISerializableInterval

Properties​

Property Alerts Modifiers Type Description
attached Alpha readonly boolean

Methods​

Method Alerts Return Type Description
[Symbol.iterator]() Alpha Iterator<TInterval>
add({ start, end, props, }) Alpha TInterval Creates a new interval and add it to the collection.
attachDeserializer(onDeserialize) Alpha void
attachIndex(index) Alpha 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 }) Alpha TInterval | undefined Changes the endpoints, properties, or both of an existing interval.
CreateBackwardIteratorWithEndPosition(endPosition) Alpha Iterator<TInterval>
CreateBackwardIteratorWithStartPosition(startPosition) Alpha Iterator<TInterval>
CreateForwardIteratorWithEndPosition(endPosition) Alpha Iterator<TInterval>
CreateForwardIteratorWithStartPosition(startPosition) Alpha Iterator<TInterval>
detachIndex(index) Alpha 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, Alpha TInterval[]
gatherIterationResults(results, iteratesForward, start, end) Alpha void Gathers iteration results that optionally match a start/end criteria into the provided array.
getIntervalById(id) Alpha TInterval | undefined
map(fn) Alpha void Applies a function to each interval in this collection.
nextInterval(pos) Deprecated, Alpha TInterval | undefined
previousInterval(pos) Deprecated, Alpha TInterval | undefined
removeIntervalById(id) Alpha TInterval | undefined Removes an interval from the collection.

Property Details​

attached​

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

readonly attached: boolean;

Type: boolean

Method Details​

[Symbol.iterator]​

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

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.

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

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​

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

Returns​

  • the created interval

Return type: TInterval

attachDeserializer​

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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 as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

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​

Parameter Type Description
index IntervalIndex<TInterval>

change​

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

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

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

Parameters​

Parameter Type Description
id string Id of the Interval to change
{ start, end, props } { 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: TInterval | undefined

CreateBackwardIteratorWithEndPosition​

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

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

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

CreateBackwardIteratorWithStartPosition​

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

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

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

CreateForwardIteratorWithEndPosition​

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

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

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

CreateForwardIteratorWithStartPosition​

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

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

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

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

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

Parameters​

Parameter Type Description
index IntervalIndex<TInterval>

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 as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

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

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: TInterval[]

gatherIterationResults​

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

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

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

Parameters​

Parameter Modifiers Type Description
results TInterval[] 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 as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

getIntervalById(id: string): TInterval | 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: TInterval | undefined

map​

Applies a function to each interval in this collection.

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

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

Parameters​

Parameter Type Description
fn (interval: TInterval) => 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 as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

nextInterval(pos: number): TInterval | undefined;

Parameters​

Parameter Type Description
pos number

Returns​

Return type: TInterval | 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 as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

previousInterval(pos: number): TInterval | undefined;

Parameters​

Parameter Type Description
pos number

Returns​

Return type: TInterval | undefined

removeIntervalById​

Removes an interval from the collection.

This API is provided as an alpha preview and may change without notice.

To use, import via fluid-framework/alpha.

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

Signature​

removeIntervalById(id: string): TInterval | undefined;

Parameters​

Parameter Type Description
id string Id of the interval to remove

Returns​

the removed interval

Return type: TInterval | undefined