dyn_list 0.2.1

A linked list that can hold dynamically sized values in its nodes.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

use core::alloc::Allocator;

use dynode::AllocateError;

use crate::{
    iter::IntoIter,
    node::{self, Header},
    DynList, Ends, MaybeUninitNode,
};

impl<T, A> DynList<T, A>
where
    A: Allocator,
{
    #[inline]
    /// Attempts to allocate an uninitialised, sized node at the front of the list.
    ///
    /// # Errors
    /// If allocation fails, this will return an [`AllocateError`].
    pub fn try_allocate_uninit_sized_front(
        &mut self,
    ) -> Result<MaybeUninitNode<T, A>, AllocateError> {
        let header = Header {
            next: self.ends.map(|Ends { front, .. }| front),
            previous: None,
        };

        unsafe { node::try_new_sized(self, header) }
    }

    #[inline]
    /// Attempts to allocate an uninitialised, sized node at the back of the list.
    ///
    /// # Errors
    /// If allocation fails, this will return an [`AllocateError`].
    pub fn try_allocate_uninit_sized_back(
        &mut self,
    ) -> Result<MaybeUninitNode<T, A>, AllocateError> {
        let header = Header {
            next: None,
            previous: self.ends.map(|Ends { back, .. }| back),
        };

        unsafe { node::try_new_sized(self, header) }
    }

    #[must_use]
    #[inline]
    /// Allocates an uninitialised, sized node at the front of the list.
    pub fn allocate_uninit_sized_front(&mut self) -> MaybeUninitNode<T, A> {
        AllocateError::unwrap_result(self.try_allocate_uninit_sized_front())
    }

    #[must_use]
    #[inline]
    /// Allocates an uninitialised, sized node at the back of the list.
    pub fn allocate_uninit_sized_back(&mut self) -> MaybeUninitNode<T, A> {
        AllocateError::unwrap_result(self.try_allocate_uninit_sized_back())
    }

    #[inline]
    /// Attempts to push `value` to the front of the list.
    ///
    /// # Errors
    /// If allocation fails, this will return an [`AllocateError`].
    pub fn try_push_front(&mut self, value: T) -> Result<(), AllocateError<T>> {
        let node = match self.try_allocate_uninit_sized_front() {
            Ok(node) => node,
            Err(error) => return Err(error.with_value(value)),
        };
        unsafe { node.value_ptr().cast().write(value) };
        unsafe { node.insert() };
        Ok(())
    }

    #[inline]
    /// Attempts to push `value` to the back of the list.
    ///
    /// # Errors
    /// If allocation fails, this will return an [`AllocateError`].
    pub fn try_push_back(&mut self, value: T) -> Result<(), AllocateError<T>> {
        let node = match self.try_allocate_uninit_sized_back() {
            Ok(node) => node,
            Err(error) => return Err(error.with_value(value)),
        };
        unsafe { node.value_ptr().cast().write(value) };
        unsafe { node.insert() };
        Ok(())
    }

    #[inline]
    /// Pushes `value` to the front of the list.
    pub fn push_front(&mut self, value: T) {
        let node = self.allocate_uninit_sized_front();
        unsafe { node.value_ptr().cast().write(value) };
        unsafe { node.insert() };
    }

    #[inline]
    /// Pushes `value` to the back of the list.
    pub fn push_back(&mut self, value: T) {
        let node = self.allocate_uninit_sized_back();
        unsafe { node.value_ptr().cast().write(value) };
        unsafe { node.insert() };
    }

    #[must_use]
    #[inline]
    /// Removes the front value from the list and returns it.
    pub fn pop_front(&mut self) -> Option<T> {
        self.pop_front_node().map(|front| unsafe { front.take() })
    }

    #[must_use]
    #[inline]
    /// Removes the back value from the list and returns it.
    pub fn pop_back(&mut self) -> Option<T> {
        self.pop_back_node().map(|back| unsafe { back.take() })
    }

    #[must_use]
    #[inline]
    /// Converts the list to an iterator that yields the elements.
    pub const fn into_iter(self) -> IntoIter<T, A> {
        IntoIter::new(self)
    }
}