Struct ArrayRef

pub struct ArrayRef(/* private fields */);

A collection used to store data in an indexed sequence structure. This type is internally implemented as a double linked list, which may squash values inserted directly one after another into single list node upon transaction commit.

Reading a root-level type as an ArrayRef means treating its sequence components as a list, where every countable element becomes an individual entity:

• JSON-like primitives (booleans, numbers, strings, JSON maps, arrays etc.) are counted individually.
• Text chunks inserted by [Text] data structure: each character becomes an element of an array.
• Embedded and binary values: they count as a single element even though they correspond of multiple bytes.

Like all Yrs shared data types, ArrayRef is resistant to the problem of interleaving (situation when elements inserted one after another may interleave with other peers concurrent inserts after merging all updates together). In case of Yrs conflict resolution is solved by using unique document id to determine correct and consistent ordering.

Example

use yrs::{Array, Doc, Map, MapPrelim, Transact, Any, any};
use yrs::types::ToJson;

let doc = Doc::new();
let array = doc.get_or_insert_array("array");
let mut txn = doc.transact_mut();

// insert single scalar value
array.insert(&mut txn, 0, "value");
array.remove_range(&mut txn, 0, 1);

assert_eq!(array.len(&txn), 0);

// insert multiple values at once
array.insert_range(&mut txn, 0, ["a", "b", "c"]);
assert_eq!(array.len(&txn), 3);

// get value
let value = array.get(&txn, 1);
assert_eq!(value, Some("b".into()));

// insert nested shared types
let map = array.insert(&mut txn, 1, MapPrelim::from([("key1", "value1")]));
map.insert(&mut txn, "key2", "value2");

assert_eq!(array.to_json(&txn), any!([
  "a",
  { "key1": "value1", "key2": "value2" },
  "b",
  "c"
]));

Trait Implementations

impl Array for ArrayRef

fn len<T: ReadTxn>(&self, _txn: &T) -> u32

Returns a number of elements stored in current array.

fn insert<V>( &self, txn: &mut TransactionMut<'_>, index: u32, value: V, ) -> V::Return

where V: Prelim,

Inserts a value at the given index. Inserting at index 0 is equivalent to prepending current array with given value, while inserting at array length is equivalent to appending that value at the end of it.

fn insert_range<T, V>( &self, txn: &mut TransactionMut<'_>, index: u32, values: T, )

where T: IntoIterator<Item = V>, V: Into<Any>,

Inserts multiple values at the given index. Inserting at index 0 is equivalent to prepending current array with given values, while inserting at array length is equivalent to appending that value at the end of it.

fn push_back<V>(&self, txn: &mut TransactionMut<'_>, value: V) -> V::Return

where V: Prelim,

Inserts given value at the end of the current array.

fn push_front<V>(&self, txn: &mut TransactionMut<'_>, content: V) -> V::Return

where V: Prelim,

Inserts given value at the beginning of the current array.

fn remove(&self, txn: &mut TransactionMut<'_>, index: u32)

Removes a single element at provided index.

fn remove_range(&self, txn: &mut TransactionMut<'_>, index: u32, len: u32)

Removes a range of elements from current array, starting at given index up until a particular number described by len has been deleted. This method panics in case when not all expected elements were removed (due to insufficient number of elements in an array) or index is outside of the bounds of an array.

fn get<T: ReadTxn>(&self, txn: &T, index: u32) -> Option<Out>

Retrieves a value stored at a given index. Returns None when provided index was out of the range of a current array.

fn get_as<T, V>(&self, txn: &T, index: u32) -> Result<V, Error>

where T: ReadTxn, V: DeserializeOwned,

Returns a value stored under a given index within current map, deserializing it into expected type if found. If value was not found, the Any::Null will be substituted and deserialized instead (i.e. into instance of Option type, if so desired).

fn move_to(&self, txn: &mut TransactionMut<'_>, source: u32, target: u32)

Moves element found at source index into target index position. Both indexes refer to a current state of the document.

fn move_range_to( &self, txn: &mut TransactionMut<'_>, start: u32, assoc_start: Assoc, end: u32, assoc_end: Assoc, target: u32, )

Moves all elements found within start..end indexes range (both side inclusive) into new position pointed by target index. All elements inserted concurrently by other peers inside of moved range will be moved as well after synchronization (although it make take more than one sync roundtrip to achieve convergence).

fn iter<'a, T: ReadTxn + 'a>(&self, txn: &'a T) -> ArrayIter<&'a T, T>

Returns an iterator, that can be used to lazely traverse over all values stored in a current array.

impl AsPrelim for ArrayRef

type Prelim = ArrayPrelim

fn as_prelim<T: ReadTxn>(&self, txn: &T) -> Self::Prelim

Converts current type contents into a Prelim type that can be used to create a new type that’s a deep copy equivalent of a current type.

impl AsRef<ArrayRef> for XmlElementRef

fn as_ref(&self) -> &ArrayRef

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<ArrayRef> for XmlFragmentRef

fn as_ref(&self) -> &ArrayRef

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Branch> for ArrayRef

fn as_ref(&self) -> &Branch

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for ArrayRef

fn clone(&self) -> ArrayRef

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ArrayRef

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl DeepObservable for ArrayRef

fn observe_deep<F>(&self, f: F) -> Subscription

where F: Fn(&TransactionMut<'_>, &Events<'_>) + 'static,

Subscribe a callback f for all events emitted by this and nested collaborative types. Callback is accepting transaction which triggered that event and event itself, wrapped within an Event structure.

fn observe_deep_with<K, F>(&self, key: K, f: F)

where K: Into<Origin>, F: Fn(&TransactionMut<'_>, &Events<'_>) + 'static,

Subscribe a callback f for all events emitted by this and nested collaborative types. Callback is accepting transaction which triggered that event and event itself, wrapped within an Event structure.

fn unobserve_deep<K: Into<Origin>>(&self, key: K) -> bool

Unsubscribe a callback identified by a given key, that was previously subscribed using Self::observe_deep_with.

impl DefaultPrelim for ArrayRef

type Prelim = ArrayPrelim

fn default_prelim() -> Self::Prelim

Returns an instance of Prelim-compatible type, which will turn into reference of a current type after being integrated into the document store.

impl From<BranchPtr> for ArrayRef

fn from(inner: BranchPtr) -> Self

Converts to this type from the input type.

impl IndexedSequence for ArrayRef

fn sticky_index( &self, txn: &mut TransactionMut<'_>, index: u32, assoc: Assoc, ) -> Option<StickyIndex>

Returns a StickyIndex equivalent to a human-readable index. Returns None if index is beyond the length of current sequence.

impl Observable for ArrayRef

type Event = ArrayEvent

fn observe<F>(&self, f: F) -> Subscription

where F: Fn(&TransactionMut<'_>, &Self::Event) + 'static, Event: AsRef<Self::Event>,

Subscribes a given callback to be triggered whenever current y-type is changed. A callback is triggered whenever a transaction gets committed. This function does not trigger if changes have been observed by nested shared collections.

fn observe_with<K, F>(&self, key: K, f: F)

where K: Into<Origin>, F: Fn(&TransactionMut<'_>, &Self::Event) + 'static, Event: AsRef<Self::Event>,

Subscribes a given callback to be triggered whenever current y-type is changed. A callback is triggered whenever a transaction gets committed. This function does not trigger if changes have been observed by nested shared collections.

fn unobserve<K: Into<Origin>>(&self, key: K) -> bool

Unsubscribes a given callback identified by key, that was previously subscribed using Self::observe_with.

impl PartialEq for ArrayRef

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RootRef for ArrayRef

fn type_ref() -> TypeRef

fn root<N: Into<Arc<str>>>(name: N) -> Root<Self>

Create a logical collaborative collection reference to a root-level type with a given name

impl SharedRef for ArrayRef

fn hook(&self) -> Hook<Self>

Returns a logical descriptor of a current shared collection.

impl ToJson for ArrayRef

fn to_json<T: ReadTxn>(&self, txn: &T) -> Any

Converts all contents of a current type into a JSON-like representation.

impl TryFrom<ItemPtr> for ArrayRef

type Error = ItemPtr

The type returned in the event of a conversion error.

fn try_from(value: ItemPtr) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Out> for ArrayRef

type Error = Out

The type returned in the event of a conversion error.

fn try_from(value: Out) -> Result<Self, Self::Error>

Performs the conversion.

impl Eq for ArrayRef