SharedString Class

The Shared String is a specialized data structure for handling collaborative text. It is based on a more general Sequence data structure but has additional features that make working with text easier.

In addition to text, a Shared String can also contain markers. Markers can be used to store metadata at positions within the text, like the details of an image or Fluid object that should be rendered with the text.

Signature

export declare class SharedString extends SharedSegmentSequence<SharedStringSegment> implements ISharedString

Extends: SharedSegmentSequence<SharedStringSegment

Implements: ISharedString

Constructors

Constructor	Description
(constructor)(document, id, attributes)	Constructs a new instance of the SharedString class

Static Methods

Method	Return Type	Description
create(runtime, id)	SharedString	Create a new shared string.
getFactory()	SharedStringFactory	Get a factory for SharedString to register with the data store.

Properties

Property	Type	Description
id	string
ISharedString	ISharedString

Methods

Method	Return Type	Description
annotateMarker(marker, props, combiningOp)	void	Annotates the marker with the provided properties.
annotateMarkerNotifyConsensus(marker, props, callback)	void	Annotates the marker with the provided properties and calls the callback on consensus.
findTile(startPos, tileLabel, preceding)	{ tile: ReferencePosition; pos: number; }
getMarkerFromId(id)	ISegment
getText(start, end)	string	Retrieve text from the SharedString in string format.
getTextAndMarkers(label)	{ parallelText: string[]; parallelMarkers: Marker[]; }
getTextRangeWithMarkers(start, end)	string
getTextRangeWithPlaceholders(start, end)	string
getTextWithPlaceholders()	string	Adds spaces for markers and handles, so that position calculations account for them.
insertMarker(pos, refType, props)	IMergeTreeInsertMsg	Inserts a marker at the position.
insertMarkerRelative(relativePos1, refType, props)	void	Inserts a marker at a relative position.
insertText(pos, text, props)	void	Inserts the text at the position.
insertTextRelative(relativePos1, text, props)	void	Inserts the text at the position.
removeText(start, end)	IMergeTreeRemoveMsg	Removes the text in the given range.
replaceText(start, end, text, props)	void	Replaces a range with the provided text.

Constructor Details

(constructor)

Constructs a new instance of the SharedString class

Signature

constructor(document: IFluidDataStoreRuntime, id: string, attributes: IChannelAttributes);

Parameters

Parameter	Type	Description
document	IFluidDataStoreRuntime
id	string
attributes	IChannelAttributes

Property Details

id

Signature

id: string;

Type: string

ISharedString

Signature

get ISharedString(): ISharedString;

Type: ISharedString

Method Details

annotateMarker

Annotates the marker with the provided properties.

Signature

annotateMarker(marker: Marker, props: PropertySet, combiningOp?: ICombiningOp): void;

Parameters

Parameter	Modifiers	Type	Description
marker		Marker	The marker to annotate
props		PropertySet	The properties to annotate the marker with
combiningOp	optional	ICombiningOp	Optional. Specifies how to combine values for the property, such as "incr" for increment.

annotateMarkerNotifyConsensus

Annotates the marker with the provided properties and calls the callback on consensus.

Signature

annotateMarkerNotifyConsensus(marker: Marker, props: PropertySet, callback: (m: Marker) => void): void;

Parameters

Parameter	Type	Description
marker	Marker	The marker to annotate
props	PropertySet	The properties to annotate the marker with
callback	(m: Marker) => void

create

Create a new shared string.

Signature

static create(runtime: IFluidDataStoreRuntime, id?: string): SharedString;

Parameters

Parameter	Modifiers	Type	Description
runtime		IFluidDataStoreRuntime	data store runtime the new shared string belongs to
id	optional	string	optional name of the shared string

Returns

newly create shared string (but not attached yet)

Return type: SharedString

findTile

Signature

findTile(startPos: number | undefined, tileLabel: string, preceding?: boolean): {
        tile: ReferencePosition;
        pos: number;
    };

Parameters

Parameter	Modifiers	Type	Description
startPos		number | undefined
tileLabel		string
preceding	optional	boolean

Returns

Return type: { tile: ReferencePosition; pos: number; }

getFactory

Get a factory for SharedString to register with the data store.

Signature

static getFactory(): SharedStringFactory;

Returns

a factory that creates and load SharedString

Return type: SharedStringFactory

getMarkerFromId

Signature

getMarkerFromId(id: string): ISegment;

Parameters

Parameter	Type	Description
id	string

Returns

Return type: ISegment

getText

Retrieve text from the SharedString in string format.

Signature

getText(start?: number, end?: number): string;

Parameters

Parameter	Modifiers	Type	Description
start	optional	number	The starting index of the text to retrieve, or 0 if omitted.
end	optional	number	The ending index of the text to retrieve, or the end of the string if omitted

Returns

The requested text content as a string.

Return type: string

getTextAndMarkers

Signature

getTextAndMarkers(label: string): {
        parallelText: string[];
        parallelMarkers: Marker[];
    };

Parameters

Parameter	Type	Description
label	string

Returns

Return type: { parallelText: string[]; parallelMarkers: Marker[]; }

getTextRangeWithMarkers

Signature

getTextRangeWithMarkers(start: number, end: number): string;

Parameters

Parameter	Type	Description
start	number
end	number

Returns

Return type: string

getTextRangeWithPlaceholders

Signature

getTextRangeWithPlaceholders(start: number, end: number): string;

Parameters

Parameter	Type	Description
start	number
end	number

Returns

Return type: string

getTextWithPlaceholders

Adds spaces for markers and handles, so that position calculations account for them.

Signature

getTextWithPlaceholders(): string;

Returns

Return type: string

insertMarker

Inserts a marker at the position.

Signature

insertMarker(pos: number, refType: ReferenceType, props?: PropertySet): IMergeTreeInsertMsg;

Parameters

Parameter	Modifiers	Type	Description
pos		number	The position to insert the marker at
refType		ReferenceType	The reference type of the marker
props	optional	PropertySet	The properties of the marker

Returns

Return type: IMergeTreeInsertMsg

insertMarkerRelative

Inserts a marker at a relative position.

Signature

insertMarkerRelative(relativePos1: IRelativePosition, refType: ReferenceType, props?: PropertySet): void;

Parameters

Parameter	Modifiers	Type	Description
relativePos1		IRelativePosition	The relative position to insert the marker at
refType		ReferenceType	The reference type of the marker
props	optional	PropertySet	The properties of the marker

insertText

Inserts the text at the position.

Signature

insertText(pos: number, text: string, props?: PropertySet): void;

Parameters

Parameter	Modifiers	Type	Description
pos		number	The position to insert the text at
text		string	The text to insert
props	optional	PropertySet	The properties of the text

insertTextRelative

Inserts the text at the position.

Signature

insertTextRelative(relativePos1: IRelativePosition, text: string, props?: PropertySet): void;

Parameters

Parameter	Modifiers	Type	Description
relativePos1		IRelativePosition	The relative position to insert the text at
text		string	The text to insert
props	optional	PropertySet	The properties of text

removeText

Removes the text in the given range.

Signature

removeText(start: number, end: number): IMergeTreeRemoveMsg;

Parameters

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

Returns

the message sent.

Return type: IMergeTreeRemoveMsg

replaceText

Replaces a range with the provided text.

Signature

replaceText(start: number, end: number, text: string, props?: PropertySet): void;

Parameters

Parameter	Modifiers	Type	Description
start		number	The inclusive start of the range to replace
end		number	The exclusive end of the range to replace
text		string	The text to replace the range with
props	optional	PropertySet	Optional. The properties of the replacement text