ISharedSegmentSequence Interface

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 ISharedSegmentSequence<T extends ISegment> extends ISharedObject<ISharedSegmentSequenceEvents>, MergeTreeRevertibleDriver

Extends: ISharedObject<ISharedSegmentSequenceEvents>, MergeTreeRevertibleDriver

Type Parameters

Parameter	Constraint	Description
T	ISegment

Methods

Method	Alerts	Return Type	Description
annotateAdjustRange(start, end, adjust)	Beta	void	Annotates a specified range within the sequence by applying the provided adjustments.
annotateRange(start, end, props)	Beta	void	Annotates the range with the provided properties
createLocalReferencePosition(segment, offset, refType, properties, slidingPreference, canSlideToEndpoint)	Beta	LocalReferencePosition	Creates a LocalReferencePosition on this SharedString. If the refType does not include ReferenceType.Transient, the returned reference will be added to the localRefs on the provided segment.
getContainingSegment(pos)	Beta	{ segment: T | undefined; offset: number | undefined; }	Finds the segment information (i.e. segment + offset) corresponding to a character position in the SharedString. If the position is past the end of the string, segment and offset on the returned object may be undefined.
getCurrentSeq()	Beta	number
getIntervalCollection(label)	Beta	ISequenceIntervalCollection	Retrieves the interval collection keyed on label. If no such interval collection exists, creates one.
getIntervalCollectionLabels()	Beta	IterableIterator<string>
getLength()	Beta	number	Returns the length of the current sequence for the client
getPosition(segment)	Beta	number	Returns the current position of a segment, and -1 if the segment does not exist in this sequence
getPropertiesAtPosition(pos)	Beta	PropertySet | undefined
getRangeExtentsOfPosition(pos)	Beta	{ posStart: number | undefined; posAfterEnd: number | undefined; }
groupOperation(groupOp)	Deprecated, Beta	void
initializeLocal()	Beta	void	Initializes the object as a local, non-shared object. This object can become shared after it is attached to the document.
insertAtReferencePosition(pos, segment)	Beta	void	Inserts a segment directly before a ReferencePosition.
insertFromSpec(pos, spec)	Beta	void	Inserts a segment
localReferencePositionToPosition(lref)	Beta	number	Resolves a ReferencePosition into a character position using this client's perspective. Reference positions that point to a character that has been removed will always return the position of the nearest non-removed character, regardless of ReferenceType. To handle this case specifically, one may wish to look at the segment returned by ReferencePosition.getSegment.
obliterateRange(start, end)	Beta	void	Obliterate is similar to remove, but differs in that segments concurrently inserted into an obliterated range will also be removed. Inserts are considered concurrent to an obliterate iff the insert op's seq is after the obliterate op's refSeq and the insert's refSeq is before the obliterates seq. Inserts made by the client which most recently obliterated a range containing the insert position are not considered concurrent to any obliteration (the last client to obliterate gets the right to insert). The endpoints can either be inclusive or exclusive. Exclusive endpoints allow the obliterated range to "grow" to include adjacent concurrently inserted segments on that side.
posFromRelativePos(relativePos)	Beta	number	Given a position specified relative to a marker id, lookup the marker and convert the position to a character position.
removeLocalReferencePosition(lref)	Beta	LocalReferencePosition | undefined	Removes a LocalReferencePosition from this SharedString.
removeRange(start, end)	Beta	void
resolveRemoteClientPosition(remoteClientPosition, remoteClientRefSeq, remoteClientId)	Beta	number | undefined	Resolves a remote client's position against the local sequence and returns the remote client's position relative to the local sequence. The client ref seq must be above the minimum sequence number or the return value will be undefined. Generally this method is used in conjunction with signals which provide point in time values for the below parameters, and is useful for things like displaying user position. It should not be used with persisted values as persisted values will quickly become invalid as the remoteClientRefSeq moves below the minimum sequence number
walkSegments(handler, start, end, accum, splitRange)	Beta	void	Walk the underlying segments of the sequence. The walked segments may extend beyond the range if the segments cross the ranges start or end boundaries. Set split range to true to ensure only segments within the range are walked.

Method Details

annotateAdjustRange

Annotates a specified range within the sequence by applying the provided adjustments.

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

annotateAdjustRange(start: number, end: number, adjust: MapLike<AdjustParams>): void;

Remarks

The range is defined by the start and end positions, where the start position is inclusive and the end position is exclusive. The properties provided in the adjust parameter will be applied to the specified range. Each adjustment modifies the current value of the property by adding the specified value. If the current value is not a number, the delta will be summed with 0 to compute the new value. The optional min and max constraints are applied after the adjustment to ensure the final value falls within the specified bounds.

Parameters

Parameter	Type	Description
start	number	The inclusive start position of the range to annotate. This is a zero-based index.
end	number	The exclusive end position of the range to annotate. This is a zero-based index.
adjust	MapLike<AdjustParams>	A map-like object specifying the properties to adjust. Each key-value pair represents a property and its corresponding adjustment to be applied over the range. An adjustment is defined by an object containing a delta to be added to the current property value, and optional min and max constraints to limit the adjusted value.

annotateRange

Annotates the range with the provided properties

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

annotateRange(start: number, end: number, props: PropertySet): void;

Parameters

Parameter	Type	Description
start	number	The inclusive start position of the range to annotate
end	number	The exclusive end position of the range to annotate
props	PropertySet	The properties to annotate the range with

createLocalReferencePosition

Creates a LocalReferencePosition on this SharedString. If the refType does not include ReferenceType.Transient, the returned reference will be added to the localRefs on the provided segment.

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

createLocalReferencePosition(segment: T, offset: number, refType: ReferenceType, properties: PropertySet | undefined, slidingPreference?: SlidingPreference, canSlideToEndpoint?: boolean): LocalReferencePosition;

Parameters

Parameter	Modifiers	Type	Description
segment		T	Segment to add the local reference on
offset		number	Offset on the segment at which to place the local reference
refType		ReferenceType	ReferenceType for the created local reference
properties		PropertySet | undefined	PropertySet to place on the created local reference
slidingPreference	optional	SlidingPreference
canSlideToEndpoint	optional	boolean

Returns

Return type: LocalReferencePosition

getContainingSegment

Finds the segment information (i.e. segment + offset) corresponding to a character position in the SharedString. If the position is past the end of the string, segment and offset on the returned object may be undefined.

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

getContainingSegment(pos: number): {
        segment: T | undefined;
        offset: number | undefined;
    };

Parameters

Parameter	Type	Description
pos	number	Character position (index) into the current local view of the SharedString.

Returns

Return type: { segment: T | undefined; offset: number | undefined; }

getCurrentSeq

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

getCurrentSeq(): number;

Returns

The most recent sequence number which has been acked by the server and processed by this SharedSegmentSequence.

Return type: number

getIntervalCollection

Retrieves the interval collection keyed on label. If no such interval collection exists, creates one.

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

getIntervalCollection(label: string): ISequenceIntervalCollection;

Parameters

Parameter	Type	Description
label	string

Returns

Return type: ISequenceIntervalCollection

getIntervalCollectionLabels

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

getIntervalCollectionLabels(): IterableIterator<string>;

Example

const iter = this.getIntervalCollectionKeys();
for (key of iter)
    const collection = this.getIntervalCollection(key);
    ...

Returns

An iterable object that enumerates the IntervalCollection labels.

Return type: IterableIterator<string>

getLength

Returns the length of the current sequence for the client

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

getLength(): number;

Returns

Return type: number

getPosition

Returns the current position of a segment, and -1 if the segment does not exist in this sequence

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

getPosition(segment: ISegment): number;

Parameters

Parameter	Type	Description
segment	ISegment	The segment to get the position of

Returns

Return type: number

getPropertiesAtPosition

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

getPropertiesAtPosition(pos: number): PropertySet | undefined;

Parameters

Parameter	Type	Description
pos	number

Returns

Return type: PropertySet | undefined

getRangeExtentsOfPosition

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

getRangeExtentsOfPosition(pos: number): {
        posStart: number | undefined;
        posAfterEnd: number | undefined;
    };

Parameters

Parameter	Type	Description
pos	number

Returns

Return type: { posStart: number | undefined; posAfterEnd: number | undefined; }

groupOperation

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

The ability to create group ops will be removed in an upcoming release, as group ops are redundant with the native batching capabilities of the runtime

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

groupOperation(groupOp: IMergeTreeGroupMsg): void;

Parameters

Parameter	Type	Description
groupOp	IMergeTreeGroupMsg

initializeLocal

Initializes the object as a local, non-shared object. This object can become shared after it is attached to the document.

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

initializeLocal(): void;

insertAtReferencePosition

Inserts a segment directly before a ReferencePosition.

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

insertAtReferencePosition(pos: ReferencePosition, segment: T): void;

Parameters

Parameter	Type	Description
pos	ReferencePosition
segment	T	The segment to insert

insertFromSpec

Inserts a segment

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

insertFromSpec(pos: number, spec: IJSONSegment): void;

Parameters

Parameter	Type	Description
pos	number
spec	IJSONSegment	The segment to inserts spec

localReferencePositionToPosition

Resolves a ReferencePosition into a character position using this client's perspective.

Reference positions that point to a character that has been removed will always return the position of the nearest non-removed character, regardless of ReferenceType. To handle this case specifically, one may wish to look at the segment returned by ReferencePosition.getSegment.

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

localReferencePositionToPosition(lref: ReferencePosition): number;

Parameters

Parameter	Type	Description
lref	ReferencePosition

Returns

Return type: number

obliterateRange

Obliterate is similar to remove, but differs in that segments concurrently inserted into an obliterated range will also be removed. Inserts are considered concurrent to an obliterate iff the insert op's seq is after the obliterate op's refSeq and the insert's refSeq is before the obliterates seq. Inserts made by the client which most recently obliterated a range containing the insert position are not considered concurrent to any obliteration (the last client to obliterate gets the right to insert).

The endpoints can either be inclusive or exclusive. Exclusive endpoints allow the obliterated range to "grow" to include adjacent concurrently inserted segments on that side.

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

obliterateRange(start: number | InteriorSequencePlace, end: number | InteriorSequencePlace): void;

Example

Given the initial state "|ABC>", obliterateRange({ pos: 0, side: Side.After }, { pos: 4, side: Side.Before }) obliterates "ABC", leaving only "|>". insertFromSpec(1, { text: "AAA"}) would insert "AAA" before |, resulting in "|AAA>". If another client does the same thing but inserts "BBB" and gets sequenced later, all clients will eventually see |BBB>.

Parameters

Parameter	Type	Description
start	number | InteriorSequencePlace	The start of the range to obliterate. Inclusive if side is Before or a number is provided.
end	number | InteriorSequencePlace	The end of the range to obliterate. Inclusive if side is After. If a number is provided it is treated as exclusive, but the endpoint does not expand in order to preserve existing behavior.

posFromRelativePos

Given a position specified relative to a marker id, lookup the marker and convert the position to a character position.

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

posFromRelativePos(relativePos: IRelativePosition): number;

Parameters

Parameter	Type	Description
relativePos	IRelativePosition	Id of marker (may be indirect) and whether position is before or after marker.

Returns

Return type: number

removeLocalReferencePosition

Removes a LocalReferencePosition from this SharedString.

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

removeLocalReferencePosition(lref: LocalReferencePosition): LocalReferencePosition | undefined;

Parameters

Parameter	Type	Description
lref	LocalReferencePosition

Returns

Return type: LocalReferencePosition | undefined

removeRange

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

removeRange(start: number, end: number): void;

Parameters

Parameter	Type	Description
start	number	The inclusive start of the range to remove
end	number	The exclusive end of the range to remove

resolveRemoteClientPosition

Resolves a remote client's position against the local sequence and returns the remote client's position relative to the local sequence. The client ref seq must be above the minimum sequence number or the return value will be undefined. Generally this method is used in conjunction with signals which provide point in time values for the below parameters, and is useful for things like displaying user position. It should not be used with persisted values as persisted values will quickly become invalid as the remoteClientRefSeq moves below the minimum sequence number

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

resolveRemoteClientPosition(remoteClientPosition: number, remoteClientRefSeq: number, remoteClientId: string): number | undefined;

Parameters

Parameter	Type	Description
remoteClientPosition	number	The remote client's position to resolve
remoteClientRefSeq	number	The reference sequence number of the remote client
remoteClientId	string	The client id of the remote client

Returns

Return type: number | undefined

walkSegments

Walk the underlying segments of the sequence. The walked segments may extend beyond the range if the segments cross the ranges start or end boundaries.

Set split range to true to ensure only segments within the range are walked.

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

walkSegments<TClientData>(handler: ISegmentAction<TClientData>, start?: number, end?: number, accum?: TClientData, splitRange?: boolean): void;

Type Parameters

Parameter	Description
TClientData

Parameters

Parameter	Modifiers	Type	Description
handler		ISegmentAction<TClientData>	The function to handle each segment. Traversal ends if this function returns true.
start	optional	number	Optional. The start of range walk.
end	optional	number	Optional. The end of range walk
accum	optional	TClientData	Optional. An object that will be passed to the handler for accumulation
splitRange	optional	boolean	Optional. Splits boundary segments on the range boundaries. Defaults to false.