SequenceInterval Interface

Interval implementation whose ends are associated with positions in a mutatable sequence. As such, when content is inserted into the middle of the interval, the interval expands to include that content.

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 SequenceInterval extends ISerializableInterval

Extends: ISerializableInterval

Remarks

The endpoints' positions should be treated exclusively to get reasonable behavior. E.g., an interval referring to "hello" in "hello world" should have a start position of 0 and an end position of 5.

To see why, consider what happens if "llo wor" is removed from the string to make "held". The interval's startpoint remains on the "h" (it isn't altered), but the interval's endpoint slides forward to the next unremoved position, which is the "l" in "held". Users would generally expect the interval to now refer to "he" (as it is the subset of content remaining after the removal), hence the "l" should be excluded. If the interval endpoint was treated inclusively, the interval would now refer to "hel", which is undesirable.

Since the endpoints of an interval are treated exclusively but cannot be greater than or equal to the length of the associated sequence, there exist special endpoint segments, "start" and "end", which represent the position immediately before or immediately after the string respectively.

If a SequenceInterval is created on a sequence with the mergeTreeReferencesCanSlideToEndpoint feature flag set to true, the endpoints of the interval that are exclusive will have the ability to slide to these special endpoint segments.

Properties

Property	Alerts	Modifiers	Type	Description
end	Alpha	readonly	LocalReferencePosition	End endpoint of this interval.
endSide	Alpha	readonly	Side
intervalType	Alpha	readonly	IntervalType
start	Alpha	readonly	LocalReferencePosition
startSide	Alpha	readonly	Side
stickiness	Alpha	readonly	IntervalStickiness

Methods

Method	Alerts	Return Type	Description
addPositionChangeListeners(beforePositionChange, afterPositionChange)	Alpha	void	Subscribes to position change events on this interval if there are no current listeners.
clone()	Alpha	SequenceInterval
compare(b)	Alpha	number	Compares this interval to b with standard comparator semantics: - returns -1 if this is less than b - returns 1 if this is greater than b - returns 0 if this is equivalent to b
compareEnd(b)	Alpha	number	Compares the end endpoint of this interval to b's end endpoint. Standard comparator semantics apply.
compareStart(b)	Alpha	number	Compares the start endpoint of this interval to b's start endpoint. Standard comparator semantics apply.
modify(label, start, end, op, localSeq, useNewSlidingBehavior)	Alpha	SequenceInterval | undefined	Modifies one or more of the endpoints of this interval, returning a new interval representing the result.
overlaps(b)	Alpha	boolean
overlapsPos(bstart, bend)	Alpha	boolean
removePositionChangeListeners()	Alpha	void	Removes the currently subscribed position change listeners.
union(b)	Alpha	SequenceInterval	Unions this interval with b, returning a new interval. The union operates as a convex hull, i.e. if the two intervals are disjoint, the return value includes intermediate values between the two intervals.

Property Details

end

End endpoint of this 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

readonly end: LocalReferencePosition;

Type: LocalReferencePosition

Remarks

This endpoint can be resolved into a character position using the SharedString it's a part of.

endSide

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 endSide: Side;

Type: Side

intervalType

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 intervalType: IntervalType;

Type: IntervalType

start

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 start: LocalReferencePosition;

Type: LocalReferencePosition

startSide

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 startSide: Side;

Type: Side

stickiness

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 stickiness: IntervalStickiness;

Type: IntervalStickiness

Method Details

addPositionChangeListeners

Subscribes to position change events on this interval if there are no current listeners.

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

addPositionChangeListeners(beforePositionChange: () => void, afterPositionChange: () => void): void;

Parameters

Parameter	Type	Description
beforePositionChange	() => void
afterPositionChange	() => void

clone

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

clone(): SequenceInterval;

Returns

a new interval object with identical semantics.

Return type: SequenceInterval

compare

Compares this interval to b with standard comparator semantics: - returns -1 if this is less than b - returns 1 if this is greater than b - returns 0 if this is equivalent to b

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

compare(b: SequenceInterval): number;

Parameters

Parameter	Type	Description
b	SequenceInterval	Interval to compare against

Returns

Return type: number

compareEnd

Compares the end endpoint of this interval to b's end endpoint. Standard comparator semantics apply.

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

compareEnd(b: SequenceInterval): number;

Parameters

Parameter	Type	Description
b	SequenceInterval	Interval to compare against

Returns

Return type: number

compareStart

Compares the start endpoint of this interval to b's start endpoint. Standard comparator semantics apply.

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

compareStart(b: SequenceInterval): number;

Parameters

Parameter	Type	Description
b	SequenceInterval	Interval to compare against

Returns

Return type: number

modify

Modifies one or more of the endpoints of this interval, returning a new interval representing the result.

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

modify(label: string, start: SequencePlace | undefined, end: SequencePlace | undefined, op?: ISequencedDocumentMessage, localSeq?: number, useNewSlidingBehavior?: boolean): SequenceInterval | undefined;

Parameters

Parameter	Modifiers	Type	Description
label		string
start		SequencePlace | undefined
end		SequencePlace | undefined
op	optional	ISequencedDocumentMessage
localSeq	optional	number
useNewSlidingBehavior	optional	boolean

Returns

Return type: SequenceInterval | undefined

overlaps

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

overlaps(b: SequenceInterval): boolean;

Parameters

Parameter	Type	Description
b	SequenceInterval

Returns

whether this interval overlaps with b. Intervals are considered to overlap if their intersection is non-empty.

Return type: boolean

overlapsPos

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

overlapsPos(bstart: number, bend: number): boolean;

Parameters

Parameter	Type	Description
bstart	number
bend	number

Returns

whether this interval overlaps two numerical positions.

Return type: boolean

removePositionChangeListeners

Removes the currently subscribed position change listeners.

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

removePositionChangeListeners(): void;

union

Unions this interval with b, returning a new interval. The union operates as a convex hull, i.e. if the two intervals are disjoint, the return value includes intermediate values between the two intervals.

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

union(b: SequenceInterval): SequenceInterval;

Parameters

Parameter	Type	Description
b	SequenceInterval

Returns

Return type: SequenceInterval