Struct eyeball_im::ObservableVector
source · pub struct ObservableVector<T> { /* private fields */ }
Expand description
An ordered list of elements that broadcasts any changes made to it.
Implementations§
source§impl<T: Clone + Send + Sync + 'static> ObservableVector<T>
impl<T: Clone + Send + Sync + 'static> ObservableVector<T>
sourcepub fn new() -> Self
pub fn new() -> Self
Create a new ObservableVector
.
As of the time of writing, this is equivalent to
ObservableVector::with_capacity(16)
, but the internal buffer capacity
is subject to change in non-breaking releases.
See with_capacity
for details about the buffer
capacity.
sourcepub fn with_capacity(capacity: usize) -> Self
pub fn with_capacity(capacity: usize) -> Self
Create a new ObservableVector
with the given capacity for the inner
buffer.
Up to capacity
updates that have not been received by all of the
subscribers yet will be retained in the inner buffer. If an update
happens while the buffer is at capacity, the oldest update is discarded
from it and all subscribers that have not yet received it will instead
see VectorDiff::Reset
as the next update.
§Panics
Panics if the capacity is 0
, or larger than usize::MAX / 2
.
sourcepub fn into_inner(self) -> Vector<T>
pub fn into_inner(self) -> Vector<T>
Turn the ObservableVector
back into a regular Vector
.
sourcepub fn subscribe(&self) -> VectorSubscriber<T>
pub fn subscribe(&self) -> VectorSubscriber<T>
Obtain a new subscriber.
If you put the ObservableVector
behind a lock, it is highly
recommended to make access of the elements and subscribing one
operation. Otherwise, the values could be altered in between the
reading of the values and subscribing to changes.
sourcepub fn append(&mut self, values: Vector<T>)
pub fn append(&mut self, values: Vector<T>)
Append the given elements at the end of the Vector
and notify
subscribers.
sourcepub fn push_front(&mut self, value: T)
pub fn push_front(&mut self, value: T)
Add an element at the front of the list and notify subscribers.
sourcepub fn push_back(&mut self, value: T)
pub fn push_back(&mut self, value: T)
Add an element at the back of the list and notify subscribers.
sourcepub fn pop_front(&mut self) -> Option<T>
pub fn pop_front(&mut self) -> Option<T>
Remove the first element, notify subscribers and return the element.
If there are no elements, subscribers will not be notified and this
method will return None
.
sourcepub fn pop_back(&mut self) -> Option<T>
pub fn pop_back(&mut self) -> Option<T>
Remove the last element, notify subscribers and return the element.
If there are no elements, subscribers will not be notified and this
method will return None
.
sourcepub fn set(&mut self, index: usize, value: T) -> T
pub fn set(&mut self, index: usize, value: T) -> T
Replace the element at the given position, notify subscribers and return the previous element at that position.
§Panics
Panics if index > len
.
sourcepub fn remove(&mut self, index: usize) -> T
pub fn remove(&mut self, index: usize) -> T
Remove the element at the given position, notify subscribers and return the element.
§Panics
Panics if index >= len
.
sourcepub fn truncate(&mut self, len: usize)
pub fn truncate(&mut self, len: usize)
Truncate the vector to len
elements and notify subscribers.
Does nothing if len
is greater or equal to the vector’s current
length.
sourcepub fn entry(&mut self, index: usize) -> ObservableVectorEntry<'_, T>
pub fn entry(&mut self, index: usize) -> ObservableVectorEntry<'_, T>
Gets an entry for the given index, through which only the element at that index alone can be updated or removed.
§Panics
Panics if index >= len
.
sourcepub fn for_each(&mut self, f: impl FnMut(ObservableVectorEntry<'_, T>))
pub fn for_each(&mut self, f: impl FnMut(ObservableVectorEntry<'_, T>))
Call the given closure for every element in this ObservableVector
,
with an entry struct that allows updating or removing that element.
Iteration happens in order, i.e. starting at index 0
.
sourcepub fn entries(&mut self) -> ObservableVectorEntries<'_, T>
pub fn entries(&mut self) -> ObservableVectorEntries<'_, T>
Get an iterator over all the entries in this ObservableVector
.
This is a more flexible, but less convenient alternative to
for_each
. If you don’t need to use special control
flow like .await
or break
when iterating, it’s recommended to use
that method instead.
Because std
’s Iterator
trait does not allow iterator items to borrow
from the iterator itself, the returned typed does not implement the
Iterator
trait and can thus not be used with a for
loop. Instead,
you have to call its .next()
method directly, as in:
let mut entries = ob.entries();
while let Some(entry) = entries.next() {
// use entry
}
sourcepub fn transaction(&mut self) -> ObservableVectorTransaction<'_, T>
pub fn transaction(&mut self) -> ObservableVectorTransaction<'_, T>
Start a new transaction to make multiple updates as one unit.
See ObservableVectorTransaction
s documentation for more details.
Methods from Deref<Target = Vector<T>>§
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Test whether a vector is empty.
Time: O(1)
§Examples
let vec = vector!["Joe", "Mike", "Robert"];
assert_eq!(false, vec.is_empty());
assert_eq!(true, Vector::<i32>::new().is_empty());
sourcepub fn is_inline(&self) -> bool
pub fn is_inline(&self) -> bool
Test whether a vector is currently inlined.
Vectors small enough that their contents could be stored entirely inside
the space of std::mem::size_of::<Vector<A>>()
bytes are stored inline on
the stack instead of allocating any chunks. This method returns true
if
this vector is currently inlined, or false
if it currently has chunks allocated
on the heap.
This may be useful in conjunction with ptr_eq()
, which checks if
two vectors’ heap allocations are the same, and thus will never return true
for inlined vectors.
Time: O(1)
sourcepub fn ptr_eq(&self, other: &Vector<A>) -> bool
pub fn ptr_eq(&self, other: &Vector<A>) -> bool
Test whether two vectors refer to the same content in memory.
This uses the following rules to determine equality:
- If the two sides are references to the same vector, return true.
- If the two sides are single chunk vectors pointing to the same chunk, return true.
- If the two sides are full trees pointing to the same chunks, return true.
This would return true if you’re comparing a vector to itself, or
if you’re comparing a vector to a fresh clone of itself. The exception to this is
if you’ve cloned an inline array (ie. an array with so few elements they can fit
inside the space a Vector
allocates for its pointers, so there are no heap allocations
to compare).
Time: O(1)
sourcepub fn leaves(&self) -> Chunks<'_, A>
pub fn leaves(&self) -> Chunks<'_, A>
Get an iterator over the leaf nodes of a vector.
This returns an iterator over the Chunk
s at the leaves of the
RRB tree. These are useful for efficient parallelisation of work on
the vector, but should not be used for basic iteration.
Time: O(1)
sourcepub fn get(&self, index: usize) -> Option<&A>
pub fn get(&self, index: usize) -> Option<&A>
Get a reference to the value at index index
in a vector.
Returns None
if the index is out of bounds.
Time: O(log n)
§Examples
let vec = vector!["Joe", "Mike", "Robert"];
assert_eq!(Some(&"Robert"), vec.get(2));
assert_eq!(None, vec.get(5));
sourcepub fn front(&self) -> Option<&A>
pub fn front(&self) -> Option<&A>
Get the first element of a vector.
If the vector is empty, None
is returned.
Time: O(log n)
sourcepub fn head(&self) -> Option<&A>
pub fn head(&self) -> Option<&A>
Get the first element of a vector.
If the vector is empty, None
is returned.
This is an alias for the front
method.
Time: O(log n)
sourcepub fn back(&self) -> Option<&A>
pub fn back(&self) -> Option<&A>
Get the last element of a vector.
If the vector is empty, None
is returned.
Time: O(log n)
sourcepub fn last(&self) -> Option<&A>
pub fn last(&self) -> Option<&A>
Get the last element of a vector.
If the vector is empty, None
is returned.
This is an alias for the back
method.
Time: O(log n)
sourcepub fn index_of(&self, value: &A) -> Option<usize>where
A: PartialEq,
pub fn index_of(&self, value: &A) -> Option<usize>where
A: PartialEq,
Get the index of a given element in the vector.
Searches the vector for the first occurrence of a given value,
and returns the index of the value if it’s there. Otherwise,
it returns None
.
Time: O(n)
§Examples
let mut vec = vector![1, 2, 3, 4, 5];
assert_eq!(Some(2), vec.index_of(&3));
assert_eq!(None, vec.index_of(&31337));
sourcepub fn contains(&self, value: &A) -> boolwhere
A: PartialEq,
pub fn contains(&self, value: &A) -> boolwhere
A: PartialEq,
Test if a given element is in the vector.
Searches the vector for the first occurrence of a given value,
and returns true
if it’s there. If it’s nowhere to be found
in the vector, it returns false
.
Time: O(n)
§Examples
let mut vec = vector![1, 2, 3, 4, 5];
assert_eq!(true, vec.contains(&3));
assert_eq!(false, vec.contains(&31337));
sourcepub fn binary_search_by<F>(&self, f: F) -> Result<usize, usize>
pub fn binary_search_by<F>(&self, f: F) -> Result<usize, usize>
Binary search a sorted vector for a given element using a comparator function.
Assumes the vector has already been sorted using the same comparator
function, eg. by using sort_by
.
If the value is found, it returns Ok(index)
where index
is the index
of the element. If the value isn’t found, it returns Err(index)
where
index
is the index at which the element would need to be inserted to
maintain sorted order.
Time: O(log n)
sourcepub fn binary_search(&self, value: &A) -> Result<usize, usize>where
A: Ord,
pub fn binary_search(&self, value: &A) -> Result<usize, usize>where
A: Ord,
Binary search a sorted vector for a given element.
If the value is found, it returns Ok(index)
where index
is the index
of the element. If the value isn’t found, it returns Err(index)
where
index
is the index at which the element would need to be inserted to
maintain sorted order.
Time: O(log n)
sourcepub fn binary_search_by_key<B, F>(&self, b: &B, f: F) -> Result<usize, usize>
pub fn binary_search_by_key<B, F>(&self, b: &B, f: F) -> Result<usize, usize>
Binary search a sorted vector for a given element with a key extract function.
Assumes the vector has already been sorted using the same key extract
function, eg. by using sort_by_key
.
If the value is found, it returns Ok(index)
where index
is the index
of the element. If the value isn’t found, it returns Err(index)
where
index
is the index at which the element would need to be inserted to
maintain sorted order.
Time: O(log n)
sourcepub fn update(&self, index: usize, value: A) -> Vector<A>
pub fn update(&self, index: usize, value: A) -> Vector<A>
Create a new vector with the value at index index
updated.
Panics if the index is out of bounds.
Time: O(log n)
§Examples
let mut vec = vector![1, 2, 3];
assert_eq!(vector![1, 5, 3], vec.update(1, 5));