Struct StickyIndex

pub struct StickyIndex {
    pub assoc: Assoc,
    /* private fields */
}

Expand description

A sticky index is based on the Yjs model and is not affected by document changes. E.g. If you place a sticky index before a certain character, it will always point to this character. If you place a sticky index at the end of a type, it will always point to the end of the type.

A numeric position is often unsuited for user selections, because it does not change when content is inserted before or after.

Insert(0, 'x')('a.bc') = 'xa.bc' Where . is the relative position.

Example:

use yrs::{Assoc, Doc, IndexedSequence, Text, Transact};

let doc = Doc::new();
let txt = doc.get_or_insert_text("text");
let mut txn = doc.transact_mut();
txt.insert(&mut txn, 0, "abc"); // => 'abc'

// create position tracker (marked as . in the comments)
let pos = txt.sticky_index(&mut txn, 2, Assoc::After).unwrap(); // => 'ab.c'

// modify text
txt.insert(&mut txn, 1, "def"); // => 'adefb.c'
txt.remove_range(&mut txn, 4, 1); // => 'adef.c'

// get current offset index within the containing collection
let a = pos.get_offset(&txn).unwrap();
assert_eq!(a.index, 4);

Fields§

§assoc: Assoc

If true - associate to the right block. Otherwise, associate to the left one.

Implementations§

§

impl StickyIndex

pub fn new(scope: IndexScope, assoc: Assoc) -> StickyIndex

pub fn from_id(id: ID, assoc: Assoc) -> StickyIndex

pub fn from_type<T, B>(_txn: &T, branch: &B, assoc: Assoc) -> StickyIndex
where T: ReadTxn, B: AsRef<Branch>,

pub fn scope(&self) -> &IndexScope

pub fn is_root(&self) -> bool

Scope refers to root collection.

pub fn is_nested(&self) -> bool

Scope refers to nested shared collection.

pub fn is_relative(&self) -> bool

Scope refers to a position relative to another block.

pub fn id(&self) -> Option<&ID>

Returns an ID of the block position which is used as a reference to keep track the location of current StickyIndex even in face of changes performed by different peers.

Returns None if current StickyIndex has been created on an empty shared collection (in that case there’s no block that we can refer to).

pub fn get_offset<T>(&self, txn: &T) -> Option<Offset>
where T: ReadTxn,

Maps current StickyIndex onto Offset which points to shared collection and a human-readable index in that collection.

That index is only valid at the current point in time - if i.e. another update from remote peer has been applied, it may have changed relative index position that StickyIndex points to, so that Offset’s index will no longer point to the same place.

§Examples

use yrs::{Assoc, Doc, IndexedSequence, Text, Transact};

let doc = Doc::new();
let text = doc.get_or_insert_text("text");
let mut txn = doc.transact_mut();

text.insert(&mut txn, 0, "hello world");

const INDEX: u32 = 4;

// set perma index at position before letter 'o' => "hell.o world"
let pos = text.sticky_index(&mut txn, INDEX, Assoc::After).unwrap();
let off = pos.get_offset(&txn).unwrap();
assert_eq!(off.index, INDEX);

// perma index will maintain it's position before letter 'o' even if another update
// shifted it's index inside of the text
text.insert(&mut txn, 1, "(see)"); // => "h(see)ell.o world" where . is perma index position
let off2 = pos.get_offset(&txn).unwrap();
assert_ne!(off2.index, off.index); // offset index changed due to new insert above