Trait Array

pub trait Array: AsRef<Branch> + Sized {
    // Provided methods
    fn len<T: ReadTxn>(&self, _txn: &T) -> u32 { ... }
    fn insert<V>(
        &self,
        txn: &mut TransactionMut<'_>,
        index: u32,
        value: V,
    ) -> V::Return
       where V: Prelim { ... }
    fn insert_range<T, V>(
        &self,
        txn: &mut TransactionMut<'_>,
        index: u32,
        values: T,
    )
       where T: IntoIterator<Item = V>,
             V: Into<Any> { ... }
    fn push_back<V>(&self, txn: &mut TransactionMut<'_>, value: V) -> V::Return
       where V: Prelim { ... }
    fn push_front<V>(
        &self,
        txn: &mut TransactionMut<'_>,
        content: V,
    ) -> V::Return
       where V: Prelim { ... }
    fn remove(&self, txn: &mut TransactionMut<'_>, index: u32) { ... }
    fn remove_range(&self, txn: &mut TransactionMut<'_>, index: u32, len: u32) { ... }
    fn get<T: ReadTxn>(&self, txn: &T, index: u32) -> Option<Out> { ... }
    fn get_as<T, V>(&self, txn: &T, index: u32) -> Result<V, Error>
       where T: ReadTxn,
             V: DeserializeOwned { ... }
    fn move_to(&self, txn: &mut TransactionMut<'_>, source: u32, target: u32) { ... }
    fn move_range_to(
        &self,
        txn: &mut TransactionMut<'_>,
        start: u32,
        assoc_start: Assoc,
        end: u32,
        assoc_end: Assoc,
        target: u32,
    ) { ... }
    fn iter<'a, T: ReadTxn + 'a>(&self, txn: &'a T) -> ArrayIter<&'a T, T>  { ... }
}

Provided Methods

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.

Returns a reference to an integrated preliminary input.

Panics

This method will panic if provided index is greater than the current length of an ArrayRef.

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.

Panics

This method will panic if provided index is greater than the current length of an ArrayRef.

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.

Returns a reference to an integrated preliminary input.

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.

Returns a reference to an integrated preliminary input.

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).

Example

use yrs::{Doc, In, Array, MapPrelim, Transact, WriteTxn};

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

// insert a multi-nested shared refs
let alice = array.insert(&mut txn, 0, MapPrelim::from([
  ("name", In::from("Alice")),
  ("age", In::from(30)),
  ("address", MapPrelim::from([
    ("city", In::from("London")),
    ("street", In::from("Baker st.")),
  ]).into())
]));

// define Rust types to map from the shared refs

#[derive(Debug, PartialEq, serde::Deserialize)]
struct Person {
  name: String,
  age: u32,
  address: Option<Address>,
}

#[derive(Debug, PartialEq, serde::Deserialize)]
struct Address {
  city: String,
  street: String,
}

// retrieve and deserialize the value across multiple shared refs
let alice: Person = array.get_as(&txn, 0).unwrap();
assert_eq!(alice, Person {
  name: "Alice".to_string(),
  age: 30,
  address: Some(Address {
    city: "London".to_string(),
    street: "Baker st.".to_string(),
  })
});

// try to retrieve value that doesn't exist
let bob: Option<Person> = array.get_as(&txn, 1).unwrap();
assert_eq!(bob, None);

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.

Panics

This method panics if either source or target indexes are greater than current array’s length.

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).

assoc_start/assoc_end flags are used to mark if ranges should include elements that might have been inserted concurrently at the edges of the range definition.

Example:

use yrs::{Doc, Transact, Array, Assoc};
let doc = Doc::new();
let array = doc.get_or_insert_array("array");
array.insert_range(&mut doc.transact_mut(), 0, [1,2,3,4]);
// move elements 2 and 3 after the 4
array.move_range_to(&mut doc.transact_mut(), 1, Assoc::After, 2, Assoc::Before, 4);
let values: Vec<_> = array.iter(&doc.transact()).collect();
assert_eq!(values, vec![1.into(), 4.into(), 2.into(), 3.into()]);

Panics

This method panics if either start, end or target indexes are greater than current array’s length.

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.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Array for ArrayRef