pub struct ArrayRef(/* private fields */);
Expand description
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§
source§impl Array for ArrayRef
impl Array for ArrayRef
source§fn len<T: ReadTxn>(&self, _txn: &T) -> u32
fn len<T: ReadTxn>(&self, _txn: &T) -> u32
Returns a number of elements stored in current array.
source§fn insert<V>(
&self,
txn: &mut TransactionMut<'_>,
index: u32,
value: V
) -> V::Returnwhere
V: Prelim,
fn insert<V>(
&self,
txn: &mut TransactionMut<'_>,
index: u32,
value: V
) -> V::Returnwhere
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. Read moresource§fn insert_range<T, V>(
&self,
txn: &mut TransactionMut<'_>,
index: u32,
values: T
)
fn insert_range<T, V>( &self, txn: &mut TransactionMut<'_>, index: u32, values: T )
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. Read moresource§fn push_back<V>(&self, txn: &mut TransactionMut<'_>, value: V) -> V::Returnwhere
V: Prelim,
fn push_back<V>(&self, txn: &mut TransactionMut<'_>, value: V) -> V::Returnwhere
V: Prelim,
Inserts given
value
at the end of the current array. Read moresource§fn push_front<V>(&self, txn: &mut TransactionMut<'_>, content: V) -> V::Returnwhere
V: Prelim,
fn push_front<V>(&self, txn: &mut TransactionMut<'_>, content: V) -> V::Returnwhere
V: Prelim,
Inserts given
value
at the beginning of the current array. Read moresource§fn remove(&self, txn: &mut TransactionMut<'_>, index: u32)
fn remove(&self, txn: &mut TransactionMut<'_>, index: u32)
Removes a single element at provided
index
.source§fn remove_range(&self, txn: &mut TransactionMut<'_>, index: u32, len: u32)
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.source§fn get<T: ReadTxn>(&self, txn: &T, index: u32) -> Option<Value>
fn get<T: ReadTxn>(&self, txn: &T, index: u32) -> Option<Value>
Retrieves a value stored at a given
index
. Returns None
when provided index was out
of the range of a current array.source§fn move_to(&self, txn: &mut TransactionMut<'_>, source: u32, target: u32)
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. Read moresource§fn move_range_to(
&self,
txn: &mut TransactionMut<'_>,
start: u32,
assoc_start: Assoc,
end: u32,
assoc_end: Assoc,
target: u32
)
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). Read moresource§impl DeepObservable for ArrayRef
impl DeepObservable for ArrayRef
source§fn observe_deep<F>(&self, f: F) -> Subscription
fn observe_deep<F>(&self, f: F) -> Subscription
source§impl IndexedSequence for ArrayRef
impl IndexedSequence for ArrayRef
source§fn sticky_index(
&self,
txn: &mut TransactionMut<'_>,
index: u32,
assoc: Assoc
) -> Option<StickyIndex>
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.source§impl Into<ArrayRef> for XmlElementRef
impl Into<ArrayRef> for XmlElementRef
source§impl Observable for ArrayRef
impl Observable for ArrayRef
type Event = ArrayEvent
source§fn observe<F>(&self, f: F) -> Subscription
fn observe<F>(&self, f: F) -> Subscription
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. Read more
source§impl PartialEq for ArrayRef
impl PartialEq for ArrayRef
impl Eq for ArrayRef
Auto Trait Implementations§
impl Freeze for ArrayRef
impl !RefUnwindSafe for ArrayRef
impl !Send for ArrayRef
impl !Sync for ArrayRef
impl Unpin for ArrayRef
impl !UnwindSafe for ArrayRef
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more