orx_linked_list/list/
get_doubly.rs

1use super::{List, helper_traits::HasDoublyEnds, slice::ListSlice};
2use crate::{DoublyIdx, variant::Doubly};
3use core::ops::RangeBounds;
4use orx_selfref_col::MemoryPolicy;
5
6impl<T, M> List<Doubly<T>, M>
7where
8    M: MemoryPolicy<Doubly<T>>,
9{
10    /// Creates and returns a slice of the list between the given `range` of indices.
11    ///
12    /// Note that a linked list slice itself also behaves like a linked list,
13    /// reflecting the recursive nature of the data type.
14    /// However, it does not own the data.
15    /// It is rather a view, like a slice is a view to a vec.
16    ///
17    /// Note that slicing might be useful in various ways.
18    /// For instance, we can keep indices of several critical elements of the list.
19    /// We can then get all elements before, after or between any pair of these indices.
20    /// Or we can combine the list with an indices vector, which provides the linked list
21    /// a vec-like usage
22    /// * with the disadvantage of using more memory, and
23    /// * with the advantage of constant time insertions, removals or moves.
24    ///
25    /// # Panics
26    ///
27    /// Panics if any of indices of the range bounds is invalid.
28    ///
29    /// # Example
30    ///
31    /// ```rust
32    /// use orx_linked_list::*;
33    ///
34    /// let mut list = DoublyList::new();
35    ///
36    /// list.push_back(3);
37    /// list.push_front(1);
38    /// list.push_front(7);
39    /// list.push_back(4);
40    /// list.push_front(9);
41    ///
42    /// let expected_values = vec![9, 7, 1, 3, 4];
43    ///
44    /// assert!(list.eq_to_iter_refs(&expected_values));
45    /// assert!(list.slice(..).eq_to_iter_refs(&expected_values));
46    ///
47    /// let idx: Vec<_> = list.indices().collect();
48    ///
49    /// let slice = list.slice(idx[1]..=idx[3]);
50    /// assert_eq!(slice.front(), Some(&7));
51    /// assert_eq!(slice.back(), Some(&3));
52    /// assert!(slice.eq_to_iter_vals([7, 1, 3]));
53    ///
54    /// let sum: usize = slice.iter().sum();
55    /// assert_eq!(sum, 11);
56    /// ```
57    ///
58    /// Note that the linked list and its slices are directed.
59    /// In other words, it does not by default have a cyclic behavior.
60    /// Therefore, if the end of the `range` is before the beginning,
61    /// the slice will stop at the `back` of the list.
62    /// See the following example for clarification.
63    ///
64    /// Currently, cyclic or ring behavior can be achieved by `ring_iter` method.
65    ///
66    /// ```rust
67    /// use orx_linked_list::*;
68    ///
69    /// let list: DoublyList<_> = (0..10).collect();
70    /// let idx: Vec<_> = list.indices().collect();
71    ///
72    /// // a..b where b comes later, hence, we get the slice a..b
73    /// let slice = list.slice(idx[1]..idx[4]);
74    /// assert!(slice.eq_to_iter_vals([1, 2, 3]));
75    ///
76    /// // a..b where b comes earlier, then, we get the slice a..back
77    /// let slice = list.slice(idx[4]..idx[1]);
78    /// assert!(slice.eq_to_iter_vals([4, 5, 6, 7, 8, 9]));
79    /// ```
80    pub fn slice<R>(&self, range: R) -> ListSlice<'_, Doubly<T>, M>
81    where
82        R: RangeBounds<DoublyIdx<T>>,
83    {
84        let ends = self.slice_ends(range).expect("invalid indices in range");
85        ListSlice { col: &self.0, ends }
86    }
87}
orx_linked_list/list/get_doubly.rs

orx_linked_list/list/
get_doubly.rs
