Struct matterdb::indexes::SparseListIndex

pub struct SparseListIndex<T: RawAccess, V> { /* fields omitted */ }

A list of items similar to ListIndex; however, it may contain “spaces”. For instance, a list might contain six elements with indexes: 1, 2, 3, 5, 7, 8 (missing 4 and 6). And if you try to get the element for index 4 or 6, you will get None.

Later, elements can be added to the spaces, if required. Elements in this list are added to the end of the list and are removed either from the end of the list or from certain indexes.

SparseListIndex has length and capacity. Length is the number of non-empty elements in the list. Capacity is the number of all elements in the list, both empty and non-empty.

SparseListIndex implements an array list, storing an element as a value and using u64 as an index. SparseListIndex requires that elements should implement the BinaryValue trait.

Implementations

impl<T, V> SparseListIndex<T, V> where
    T: RawAccess,
    V: BinaryValue, 

pub fn get(&self, index: u64) -> Option<V>

Returns an element at the indicated position or None if the indicated position is out of bounds or if it does not exist.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let fork = db.fork();
let mut index = fork.get_sparse_list("name");
assert_eq!(None, index.get(0));

index.push(42);
assert_eq!(Some(42), index.get(0));
index.push(1);
index.remove(0);
assert_eq!(None, index.get(0));
assert_eq!(Some(1), index.get(1));

pub fn is_empty(&self) -> bool

Returns true if the list contains no elements.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let fork = db.fork();
let mut index = fork.get_sparse_list("name");
assert!(index.is_empty());

index.push(42);
assert!(!index.is_empty());

pub fn capacity(&self) -> u64

Returns the total amount of elements, including empty elements, in the list. The value of capacity is determined by the maximum index of an element ever inserted into the given index.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let fork = db.fork();
let mut index = fork.get_sparse_list("name");
assert_eq!(0, index.capacity());

index.push(10);
index.push(12);
assert_eq!(2, index.capacity());

index.remove(0);

index.push(100);
assert_eq!(3, index.capacity());

pub fn len(&self) -> u64

Returns the total amount of non-empty elements in the list.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let fork = db.fork();
let mut index = fork.get_sparse_list("name");
assert_eq!(0, index.len());

index.push(10);
assert_eq!(1, index.len());

index.remove(0);

index.push(100);
assert_eq!(1, index.len());

pub fn iter(&self) -> Entries<'_, u64, V>

Returns an iterator over the list elements with corresponding indexes.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let fork = db.fork();
let mut index = fork.get_sparse_list("name");

index.extend([1, 2, 3, 4, 5].iter().cloned());

for val in index.iter() {
    println!("{:?}", val);
}

pub fn indexes(&self) -> Keys<'_, u64>

Returns an iterator over the indexes of the SparseListIndex.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let mut fork = db.fork();
let mut index = fork.get_sparse_list("name");

index.extend([1, 2, 3, 4, 5].iter().cloned());

for val in index.indexes() {
    println!("{}", val);
}

pub fn values(&self) -> Values<'_, V>

Returns an iterator over list elements.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let mut fork = db.fork();
let mut index = fork.get_sparse_list("name");

index.extend([1, 2, 3, 4, 5].iter().cloned());

for val in index.values() {
    println!("{}", val);
}

pub fn iter_from(&self, from: u64) -> Entries<'_, u64, V>

Returns an iterator over the list elements starting from the specified position. Elements are yielded with the corresponding index.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let mut fork = db.fork();
let mut index = fork.get_sparse_list("name");

index.extend([1, 2, 3, 4, 5].iter().cloned());
index.remove(3);

for val in index.iter_from(3) {
    println!("{:?}", val);
}

impl<T, V> SparseListIndex<T, V> where
    T: RawAccessMut,
    V: BinaryValue, 

pub fn push(&mut self, value: V)

Appends an element to the back of the SparseListIndex.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let mut fork = db.fork();
let mut index = fork.get_sparse_list("name");

index.push(1);
assert!(!index.is_empty());

pub fn remove(&mut self, index: u64) -> Option<V>

Removes the element with the given index from the list and returns it, or returns None if it is empty.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let mut fork = db.fork();
let mut index = fork.get_sparse_list("name");
assert_eq!(0, index.capacity());

index.push(10);
index.push(12);

assert_eq!(Some(10), index.remove(0));
assert_eq!(None, index.remove(0));
assert_eq!(2, index.capacity());
assert_eq!(1, index.len());
assert_eq!(Some(12), index.remove(1));
assert_eq!(2, index.capacity());

pub fn extend<I>(&mut self, iter: I) where
    I: IntoIterator<Item = V>, 

Extends the list with the contents of an iterator.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let mut fork = db.fork();
let mut index = fork.get_sparse_list("name");
assert!(index.is_empty());

index.extend([1, 2, 3].iter().cloned());
assert_eq!(3, index.capacity());

pub fn set(&mut self, index: u64, value: V) -> Option<V>

Changes a value at a specified position. If the position contains an empty value, it also increments the elements count. If the index value of the new element is greater than the current capacity, the capacity of the list is considered index + 1 and all further elements without specific index values will be appended after this index.

Returns the value of a previous element at the indicated position or None if it is empty.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let mut fork = db.fork();
let mut index = fork.get_sparse_list("name");

index.push(1);
assert_eq!(Some(1), index.get(0));

index.set(0, 10);
assert_eq!(Some(10), index.get(0));

pub fn clear(&mut self)

Clears the list, removing all values.

Notes

Currently, this method is not optimized to delete a large set of data. During the execution of this method, the amount of allocated memory is linearly dependent on the number of elements in the index.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let mut fork = db.fork();
let mut index = fork.get_sparse_list("name");

index.push(1);
assert!(!index.is_empty());

index.clear();
assert!(index.is_empty());

pub fn pop(&mut self) -> Option<V>

Removes the first element from the SparseListIndex and returns it, or returns None if it is empty.

Examples

use matterdb::{access::CopyAccessExt, TemporaryDB, Database, SparseListIndex};

let db = TemporaryDB::new();
let mut fork = db.fork();
let mut index = fork.get_sparse_list("name");
assert_eq!(None, index.pop());

index.push(1);
assert_eq!(Some(1), index.pop());

Trait Implementations

impl<T: Debug + RawAccess, V: Debug> Debug for SparseListIndex<T, V>

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

Formats the value using the given formatter.

impl<T, V> FromAccess<T> for SparseListIndex<T::Base, V> where
    T: Access,
    V: BinaryValue, 

fn from_access(access: T, addr: IndexAddress) -> Result<Self, AccessError>

Constructs the object at the given address.

fn from_root(access: T) -> Result<Self, AccessError>

Constructs the object from the root of the access.

impl<T, V> IndexIterator for SparseListIndex<T, V> where
    T: RawAccess,
    V: BinaryValue, 

type Key = u64

Type encompassing index keys.

type Value = V

Type encompassing index values.

fn index_iter(&self, from: Option<&u64>) -> Entries<'_, u64, V>

Continues iteration from the specified position. If from is None, starts the iteration from scratch.

impl<'a, T, V> IntoIterator for &'a SparseListIndex<T, V> where
    T: RawAccess,
    V: BinaryValue, 

type Item = (u64, V)

The type of the elements being iterated over.

type IntoIter = Entries<'a, u64, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.