Struct List 

pub struct List { /* private fields */ }

Ordered list with stable positioning for CRDT operations.

List maintains a stable ordering of elements using Position keys in a BTreeMap. This design enables concurrent insertions without requiring coordination between distributed replicas.

Key Features

• Stable ordering: Elements maintain their relative positions even with concurrent modifications
• Insertion anywhere: Can insert between any two existing elements
• CRDT semantics: Proper merge behavior for distributed systems
• Efficient access: O(log n) access by position, O(1) by index for small lists

Usage Patterns

let mut list = List::new();

// Simple append operations
list.push("first");  // Returns index 0
list.push("second"); // Returns index 1

// Insert between existing elements using index
list.insert(1, "between").unwrap();

// Access by traditional index
assert_eq!(list.get(0).unwrap().as_text(), Some("first"));

// Advanced users can use Position for precise control
let pos1 = Position::new(1, 1);  // 1.0
let pos2 = Position::new(2, 1);  // 2.0
let middle = Position::between(&pos1, &pos2);
list.insert_at_position(middle, "advanced");

Concurrent Operations

When two replicas insert at the same logical position, the rational number system ensures a consistent final order:

Replica A: ["item1", "item3"] -> inserts "item2" between them
Replica B: ["item1", "item3"] -> inserts "item4" between them

After merge: ["item1", "item2", "item4", "item3"]
(order determined by Position comparison)

Implementations

impl List

pub fn new() -> Self

Creates a new empty list

pub fn len(&self) -> usize

Returns the number of items in the list (excluding tombstones)

pub fn total_len(&self) -> usize

Returns the total number of items including tombstones

pub fn is_empty(&self) -> bool

Returns true if the list is empty

pub fn push(&mut self, value: impl Into<Value>) -> usize

Pushes a value to the end of the list Returns the index of the newly added element

pub fn insert( &mut self, index: usize, value: impl Into<Value>, ) -> Result<(), CRDTError>

Inserts a value at a specific index

pub fn get(&self, index: usize) -> Option<&Value>

Gets a value by index (0-based), filtering out tombstones

pub fn get_mut(&mut self, index: usize) -> Option<&mut Value>

Gets a mutable reference to a value by index (0-based), filtering out tombstones

pub fn insert_at_position( &mut self, position: Position, value: impl Into<Value>, )

Inserts a value at a specific position (advanced API)

pub fn get_by_position(&self, position: &Position) -> Option<&Value>

Gets a value by position

pub fn get_by_position_mut(&mut self, position: &Position) -> Option<&mut Value>

Gets a mutable reference to a value by position

pub fn set(&mut self, index: usize, value: impl Into<Value>) -> Option<Value>

Sets a value at a specific index, returns the old value if present Only considers non-tombstone elements for indexing

pub fn remove(&mut self, index: usize) -> Option<Value>

Removes a value by index (tombstones it for CRDT semantics) Only considers non-tombstone elements for indexing

pub fn remove_by_position(&mut self, position: &Position) -> Option<Value>

Removes a value by position

pub fn iter(&self) -> impl Iterator<Item = &Value>

Returns an iterator over the values in order (excluding tombstones)

pub fn iter_all(&self) -> impl Iterator<Item = &Value>

Returns an iterator over all values including tombstones

pub fn iter_with_positions(&self) -> impl Iterator<Item = (&Position, &Value)>

Returns an iterator over position-value pairs in order

pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut Value>

Returns a mutable iterator over the values in order

pub fn merge(&mut self, other: &List)

Merges another List into this one (CRDT merge operation)

pub fn clear(&mut self)

Clears all items from the list

pub fn to_vec(&self) -> Vec<Value>

Converts to a Vec of values (loses position information)

Trait Implementations

impl Clone for List

fn clone(&self) -> List

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for List

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

Formats the value using the given formatter.

impl Default for List

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for List

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<List> for Value

fn from(value: List) -> Self

Converts to this type from the input type.

impl FromIterator<Value> for List

fn from_iter<T: IntoIterator<Item = Value>>(iter: T) -> Self

Creates a value from an iterator.

impl PartialEq for List

fn eq(&self, other: &List) -> 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 Serialize for List

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<&Value> for List

type Error = CRDTError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl Data for List

impl Eq for List

impl StructuralPartialEq for List