Struct OnceList

pub struct OnceList<T: ?Sized, A: Allocator = Global> { /* private fields */ }

A single linked list which behaves like std::cell::OnceCell, but for multiple values.

Usage

A simple example:

use once_list2::OnceList;

// Create a new empty list. Note that the variable is immutable.
let list = OnceList::<i32>::new();

// You can push values to the list without the need for mutability.
list.push(1);
list.push(2);

// Or you can push multiple values at once.
list.extend([3, 4, 5]);

// You can iterate over the list.
assert_eq!(list.iter().copied().collect::<Vec<_>>(), vec![1, 2, 3, 4, 5]);

// Some methods are mutable only.
let mut list_mut = list;

// You can remove (take) a value from the list.
let removed = list_mut.remove(|&x| x % 2 == 0);
assert_eq!(removed, Some(2));
assert_eq!(list_mut.iter().copied().collect::<Vec<_>>(), vec![1, 3, 4, 5]);

(Almost nightly rustc only) Unsized types support

You can use the unsized types like str, [u8] or dyn Display as the value type of the OnceList.

Though you can use this feature without the nightly rustc compiler, you can not push or extend the values to the list without the nightly compiler and the nightly feature enabled. i.e. You can only create an empty list, that’s all.

In the nightly compiler and with the nightly feature enabled, the additional methods like push_unsized, remove_unsized_as become available:

// This code only works with the nightly compiler and the `nightly` feature enabled.

use once_list2::OnceList;

// Creating a `OnceList` for `[i32]`, the unsized type.
let list = OnceList::<[i32]>::new();

list.push_unsized([1] /* A sized array type, `[i32; 1]`, can be coerced into [i32].*/);
list.push_unsized([2, 3] /* Same for `[i32; 2] type. */);

// The normal methods like `iter` are available because it returns a reference to the value.
assert_eq!(list.iter().nth(0).unwrap(), &[1]);
assert_eq!(list.iter().nth(1).unwrap(), &[2, 3]);

let mut list_mut = list;

// `remove_unsized_as` method allows you to check the unsized value type and remove it.
let removed: Option<[i32; 2]> = unsafe {
    list_mut.remove_unsized_as(|x| if x.len() == 2 {
        Some(x.try_into().unwrap())
    } else {
        None
    })
};
// The removed value is an array, not a slice!
assert_eq!(removed, Some([2, 3]));

Implementations

impl<T: ?Sized> OnceList<T, Global>

pub fn new() -> Self

Creates a new empty OnceList. This method does not allocate.

impl<T: ?Sized, A: Allocator> OnceList<T, A>

pub fn new_in(alloc: A) -> Self

Creates a new empty OnceList with the given allocator. This method does not allocate.

pub fn len(&self) -> usize

Returns the number of values in the list. This method is O(n).

pub fn is_empty(&self) -> bool

Returns true if the list is empty.

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

where T: PartialEq,

Returns true if the list contains the value.

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

Returns a first value, if it exists.

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

Returns a mutable reference to the first value, if it exists.

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

Returns a last value, if it exists. This method is O(n).

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

Returns a mutable reference to the last value, if it exists. This method is O(n).

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

Returns an iterator over the &T references in the list.

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

Returns an iterator over the &mut T references in the list.

pub fn clear(&mut self)

Clears the list, dropping all values.

pub fn allocator(&self) -> &A

Returns an allocator of this struct.

impl<T, A: Allocator> OnceList<T, A>

pub fn remove<P>(&mut self, pred: P) -> Option<T>

where P: FnMut(&T) -> bool,

Find a first value in the list matches the predicate, remove that item from the list, and then returns that value.

impl<T, A: Allocator + Clone> OnceList<T, A>

pub fn push(&self, val: T) -> &T

Appends a value to the list, and returns the reference to that value.

Note that this method takes &self, not &mut self.

pub fn extend<U: IntoIterator<Item = T>>(&self, iter: U)

An almost same method with the std::iter::Extend::extend, though this method takes &self instead of &mut self.

Trait Implementations

impl<T: Clone + ?Sized, A: Clone + Allocator> Clone for OnceList<T, A>

fn clone(&self) -> OnceList<T, A>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: ?Sized + Debug, A: Allocator> Debug for OnceList<T, A>

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

Formats the value using the given formatter.

impl<T: ?Sized> Default for OnceList<T, Global>

fn default() -> Self

Returns the “default value” for a type.

impl<T, A: Allocator + Clone> Extend<T> for OnceList<T, A>

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

Due to the definition of the Extend trait, this method takes &mut self. Use the OnceList::extend method instead if you want to use &self.

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> FromIterator<T> for OnceList<T, Global>

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

Creates a value from an iterator.

impl<T, A: Allocator> IntoIterator for OnceList<T, A>

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T, A>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.