Options
Menu

Class RealTimeString

This is a distributed string that wraps a native javascript string. Most often, these objects are mutated with the insert and remove methods which can operate on either individual characters or substrings.

See RealTimeStringEvents for the events that can be emitted on remote changes to this object.

Convergence supports two types of references unique to RealTimeStrings. These are useful for rendering remote cursors and selections.

See the developer guide for the most common use cases.

Hierarchy

Implements

Index

Properties

StaticEvents

Events: RealTimeStringEvents = ObservableStringEventConstants

A mapping of the events this array could emit to each event's unique name. Use this to refer an event name, e.g.

rtStr.on(RealTimeString.Events.INSERT, function listener(e) {
  // ...
})

Methods

addListener

events

  • Provides the events emitted by this object as an Observable stream.

    example
    
    eventEmitter.events()
      .filter(e => e.name === "myevent")
      .subscribe(e => console.log(e));

    Returns Observable<IConvergenceEvent>

    An Observable stream of all events emitted by this object.

id

  • id(): string

indexReference

  • Creates an IndexReference anchored to this string. Its index is automatically updated on all local and remote changes.

    See the developer guide for more information.

    Parameters

    • key: string

      a unique name for the reference

    Returns LocalIndexReference

    A local index reference anchored to this string

insert

  • insert(index: number, value: string): void
  • Inserts a substring of zero or more characters into this string at the provided index. Subsequent characters are shifted to the right appropriately.

    rtString.value() // "Hello world"
    rtString.insert(6, 'magical ');
    rtString.value() // "Hello magical world"

    On a successful insert, a StringInsertEvent will be emitted to any remote users.

    Parameters

    • index: number

      the zero-based index at which to being inserting the new value

    • value: string

      the single character or substring to be inserted

    Returns void

isAttached

  • isAttached(): boolean

isDetached

  • isDetached(): boolean

length

  • length(): number
  • Just like the string.length Javascript property. Returns the number of characters in this string.

    rtString.value() // "Hello world"
    rtString.length() // 11

    Returns number

model

off

on

once

parent

path

rangeReference

  • Creates a LocalRangeReference bound to this object. Its index bounds are automatically updated on all local and remote changes.

    See the developer guide for more information.

    Parameters

    • key: string

      a unique name for the range reference

    Returns LocalRangeReference

    A local range reference anchored to this string

reference

  • Returns the remote ModelReference created by the given sessionId with the unique name key, or undefined if no such reference exists.

    See Remote References in the developer guide.

    Parameters

    • sessionId: string

      The session ID that created the reference

    • key: string

      the reference's unique key

    Returns ModelReference

references

  • Returns any remote references that match the given filter. You can provide a single key which could return references from multiple users, sessionId which would return all of a particular user session's references, or both, which is really just the same as using the reference method.

    Parameters

    • Optional referenceFilter: ReferenceFilter

      an object containing either a sessionId, key, or both

    Returns ModelReference[]

    An array of remote ModelReferences, or an empty array if there were no matches.

relativePath

  • This returns the PathElement representing this element's location relevant to its parent. For example, given a model with contents

    {
      obj: {
        with: 1,
        stuff: ['a', 'string']
      }
    }
    let rtNumber = rtModel.elementAt(['obj', 'with']);
    rtNumber.value() // 1
    rtNumber.relativePath() // 'with'
    
    let rtString = rtModel.elementAt(['obj', 'stuff', 0]);
    rtString.value() // 'a'
    rtString.relativePath() // 0

    Returns PathElement

    a PathElement representing this node's location relative to its parent, or null if it has no parent.

remove

  • remove(index: number, length: number): void
  • Removes length characters from this string, starting at index. Subsequent characters are left-shifted appropriately.

    On a successful remove, a StringRemoveEvent will be emitted to any remote users.

    rtString.value() // "Hello world"
    rtString.remove(0, 6);
    rtString.value() // "world"

    Parameters

    • index: number

      the zero-based index at which to start removing characters

    • length: number

      the number of characters to remove

    Returns void

removeAllListeners

removeFromParent

  • removeFromParent(): void
  • A convenience function to delete this element. Throws an error if this is the root object in a model.

    Returns void

removeListener

removeListeners

toJSON

  • toJSON(): any

type

  • type(): string

value

  • value(): string
  • value(value: string): void