Struct IndexList 

pub struct IndexList<T> { /* private fields */ }

Doubly-linked list implemented in safe Rust.

Implementations

impl<T> IndexList<T>

pub fn new() -> Self

Creates a new empty index list.

Example:

use index_list::IndexList;

let list = IndexList::<u64>::new();

pub fn with_capacity(capacity: usize) -> Self

Creates an empty IndexList with at least the specified capacity.

Example:

use index_list::IndexList;
let list = IndexList::<u64>::with_capacity(233);

pub fn capacity(&self) -> usize

Returns the current capacity of the list.

This value is always greater than or equal to the length.

Example:

let cap = list.capacity();
assert!(cap >= list.len());

pub fn len(&self) -> usize

Returns the number of valid elements in the list.

This value is always less than or equal to the capacity.

Example:

let first = list.remove_first();
assert!(list.len() < list.capacity());

pub fn clear(&mut self)

Clears the list be removing all elements, making it empty.

Example:

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

pub fn is_empty(&self) -> bool

Returns true when the list is empty.

Example:

let list = IndexList::<u64>::new();
assert!(list.is_empty());

pub fn is_index_used(&self, index: ListIndex) -> bool

Returns true if the index is valid.

pub fn first_index(&self) -> ListIndex

Returns the index of the first element, or None if the list is empty.

Example:

let index = list.first_index();

pub fn last_index(&self) -> ListIndex

Returns the index of the last element, or None if the list is empty.

Example:

let index = list.last_index();

pub fn next_index(&self, index: ListIndex) -> ListIndex

Returns the index of the next element, after index, or None when the end is reached.

If index is None then the first index in the list is returned.

NOTE that indexes are likely not sequential.

Example:

let mut index = list.first_index();
while index.is_some() {
    // Do something
    index = list.next_index(index);
}

pub fn prev_index(&self, index: ListIndex) -> ListIndex

Returns the index of the previous element, before index, or None when the beginning is reached.

If index is None then the last index in the list is returned.

NOTE that indexes are likely not sequential.

Example:

let mut index = list.last_index();
while index.is_some() {
    // Do something
    index = list.prev_index(index);
}

pub fn move_index(&self, index: ListIndex, steps: i32) -> ListIndex

Move to an index steps number of elements away. Positive numbers will move in the next direction, while negative number in the prev direction.

Returns the index steps elements away, or None when the end is reached.

NOTE that indexes are likely not sequential.

Example:

let mut index = list.first_index();
index = list.move_index(index, 3);
// Do something with the 4:th element
index = list.move_index(index, -2);
// Do something with the 2:nd element
index = list.move_index(index, -2);
assert!(index.is_none());

pub fn shift_index_before(&mut self, this: ListIndex, that: ListIndex) -> bool

Make the index this (and associated element) come before the index that (and associated element).

Returns true if the operation was successful. This will fail if either index is invalid or if this and that are the same index.

This is similar to calling let elem = self.remove(this); followed by self.insert_before(that, elem) except that it doesn’t invalildate or change the index this. That is, the index this is guaranteed to still point to the same element elem after this operation completes.

Example:

let mut list = IndexList::from(&mut vec![1, 2, 3]);
let index = list.first_index();
let moved = list.shift_index_before(index, list.last_index());
assert!(moved);
assert_eq!(list.get(index), Some(&1));
assert_eq!(list.to_string(), "[2 >< 1 >< 3]");

pub fn shift_index_after(&mut self, this: ListIndex, that: ListIndex) -> bool

Make the index this (and associated element) come after the index that (and associated element).

Returns true if the operation was successful. This will fail if either index is invalid or if this and that are the same index.

This is similar to calling let elem = self.remove(this); followed by self.insert_after(that, elem) except that it doesn’t invalildate or change the index this. That is, the index this is guaranteed to still point to the same element elem after this operation completes.

Example:

let mut list = IndexList::from(&mut vec![1, 2, 3]);
let index = list.first_index();
let next_index = list.next_index(index);
let moved = list.shift_index_after(index, next_index);
assert!(moved);
assert_eq!(list.get(index), Some(&1));
assert_eq!(list.to_string(), "[2 >< 1 >< 3]");

pub fn shift_index_to_front(&mut self, this: ListIndex) -> bool

Make the index this (and associated element) come first in the list.

Returns true if the operation was successful. This will fail if this is an invalid index.

This is similar to calling let elem = self.remove(this); followed by self.insert_first(elem) except that it doesn’t invalildate or change the index this. That is, the index this is guaranteed to still point to the same element elem after this operation completes.

Example:

let mut list = IndexList::from(&mut vec![1, 2, 3]);
let index = list.last_index();
let moved = list.shift_index_to_front(index);
assert!(moved);
assert_eq!(list.get(index), Some(&3));
assert_eq!(list.to_string(), "[3 >< 1 >< 2]");

pub fn shift_index_to_back(&mut self, this: ListIndex) -> bool

Make the index this (and associated element) come last in the list.

Returns true if the operation was successful. This will fail if this is an invalid index.

This is similar to calling let elem = self.remove(this); followed by self.insert_last(elem) except that it doesn’t invalildate or change the index this. That is, the index this is guaranteed to still point to the same element elem after this operation completes.

Example:

let mut list = IndexList::from(&mut vec![1, 2, 3]);
let index = list.first_index();
let moved = list.shift_index_to_back(index);
assert!(moved);
assert_eq!(list.get(index), Some(&1));
assert_eq!(list.to_string(), "[2 >< 3 >< 1]");

pub fn get_first(&self) -> Option<&T>

Get a reference to the first element data, or None.

Example:

let data = list.get_first();

pub fn get_last(&self) -> Option<&T>

Get a reference to the last element data, or None.

Example:

let data = list.get_last();

pub fn get(&self, index: ListIndex) -> Option<&T>

Get an immutable reference to the element data at the index, or None.

Example:

let data = list.get(index);

pub fn get_mut_first(&mut self) -> Option<&mut T>

Get a mutable reference to the first element data, or None.

Example:

if let Some(data) = list.get_mut_first() {
    // Update the data somehow
    *data = 0;
}

pub fn get_mut_last(&mut self) -> Option<&mut T>

Get a mutable reference to the last element data, or None.

Example:

if let Some(data) = list.get_mut_last() {
    // Update the data somehow
    *data *= 2;
}

pub fn get_mut(&mut self, index: ListIndex) -> Option<&mut T>

Get a mutable reference to the element data at the index, or None.

Example:

if let Some(data) = list.get_mut(index) {
    // Update the data somehow
    *data += 1;
}

pub fn swap_index(&mut self, this: ListIndex, that: ListIndex)

Swap the element data between two indexes.

Both indexes must be valid.

Example:

list.swap_index(list.first_index(), list.last_index());

pub fn peek_next(&self, index: ListIndex) -> Option<&T>

Peek at next element data, after the index, if any.

Returns None if there is no next index in the list.

Example:

if let Some(data) = list.peek_next(index) {
    // Consider the next data
}

pub fn peek_prev(&self, index: ListIndex) -> Option<&T>

Peek at previous element data, before the index, if any.

Returns None if there is no previous index in the list.

Example:

if let Some(data) = list.peek_prev(index) {
    // Consider the previous data
}

pub fn contains(&self, elem: T) -> bool

where T: PartialEq,

Returns true if the element is in the list.

Example:

if list.contains(42) {
    // Find it?
} else {
    // Insert it?
}

pub fn index_of(&self, elem: T) -> ListIndex

where T: PartialEq,

Returns the index of the element containg the data.

If there is more than one element with the same data, the one with the lowest index will always be returned.

Example:

let index = list.index_of(2);

pub fn insert_first(&mut self, elem: T) -> ListIndex

Insert a new element at the beginning.

It is usually not necessary to keep the index, as the element data can always be found again by walking the list.

Example:

let index = list.insert_first(42);

pub fn insert_last(&mut self, elem: T) -> ListIndex

Insert a new element at the end.

It is typically not necessary to store the index, as the data will be there when walking the list.

Example:

let index = list.insert_last(42);

pub fn insert_before(&mut self, index: ListIndex, elem: T) -> ListIndex

Insert a new element before the index.

If the index is None then the new element will be inserted first.

Example:

index = list.insert_before(index, 42);

pub fn insert_after(&mut self, index: ListIndex, elem: T) -> ListIndex

Insert a new element after the index.

If the index is None then the new element will be inserted last.

Example:

index = list.insert_after(index, 42);

pub fn remove_first(&mut self) -> Option<T>

Remove the first element and return its data.

Example:

let data = list.remove_first();

pub fn remove_last(&mut self) -> Option<T>

Remove the last element and return its data.

Example:

let data = list.remove_last();

pub fn remove(&mut self, index: ListIndex) -> Option<T>

Remove the element at the index and return its data.

Example:

let data = list.remove(index);

pub fn iter(&self) -> ListIter<'_, T>

Create a new iterator over all the elements.

Example:

let total: usize = list.iter().sum();
assert_eq!(total, 720);

pub fn drain_iter(&mut self) -> ListDrainIter<'_, T>

Create a draining iterator over all the elements.

This iterator will remove the elements as it is iterating over them.

Example:

let items: Vec<&str> = list.drain_iter().collect();
assert_eq!(list.len(), 0);
assert_eq!(items, vec!["A", "B", "C"]);

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

Create a vector for all elements.

Returns a new vector with immutable reference to the elements data.

Example:

let vector: Vec<&u64> = list.to_vec();

pub fn from(vec: &mut Vec<T>) -> IndexList<T>

Insert all the elements from the vector, which will be drained.

Example:

let mut the_numbers = vec![4, 8, 15, 16, 23, 42];
let list = IndexList::from(&mut the_numbers);
assert_eq!(the_numbers.len(), 0);
assert_eq!(list.len(), 6);

pub fn trim_safe(&mut self)

Remove any unused indexes at the end by truncating.

If the unused indexes don’t appear at the end, then nothing happens.

No valid indexes are changed.

Example:

list.remove_last();
assert!(list.len() < list.capacity());
list.trim_safe();
assert_eq!(list.len(), list.capacity());

pub fn trim_swap(&mut self)

Remove all unused elements by swapping indexes and then truncating.

This will reduce the capacity of the list, but only if there are any unused elements. Length and capacity will be equal after the call.

NOTE that this call may invalidate some indexes.

While it is possible to tell if an index has become invalid, because only indexes at or above the new capacity limit has been moved, it is not recommended to rely on that fact or test for it.

Example:

list.remove_first();
assert!(list.len() < list.capacity());
list.trim_swap();
assert_eq!(list.len(), list.capacity());

pub fn append(&mut self, other: &mut IndexList<T>)

Add the elements of the other list at the end.

The other list will be empty after the call as all its elements have been moved to this list.

Example:

let sum_both = list.len() + other.len();
list.append(&mut other);
assert!(other.is_empty());
assert_eq!(list.len(), sum_both);

pub fn prepend(&mut self, other: &mut IndexList<T>)

Add the elements of the other list at the beginning.

The other list will be empty after the call as all its elements have been moved to this list.

Example:

let sum_both = list.len() + other.len();
list.prepend(&mut other);
assert!(other.is_empty());
assert_eq!(list.len(), sum_both);

pub fn split(&mut self, index: ListIndex) -> IndexList<T>

Split the list by moving the elements from the index to a new list.

The original list will no longer contain the elements data that was moved to the other list.

Example:

let total = list.len();
let other = list.split(index);
assert!(list.len() < total);
assert_eq!(list.len() + other.len(), total);

Trait Implementations

impl<T: Debug> Debug for IndexList<T>

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

Formats the value using the given formatter.

impl<T> Default for IndexList<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Display for IndexList<T>

where T: Display,

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

Formats the value using the given formatter.

impl<T> Extend<T> for IndexList<T>

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

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T> From<T> for IndexList<T>

fn from(elem: T) -> IndexList<T>

Converts to this type from the input type.

impl<T> FromIterator<T> for IndexList<T>

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

Creates a value from an iterator.

impl<'a, T> IntoIterator for &'a IndexList<T>

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = ListIter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.