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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
pub trait ReadableSliceQueue<T> {
/// The amount of elements stored
///
/// Returns __the amount of elements stored in `self`__
fn len(&self) -> usize;
/// Checks if there are __no__ elements stored
///
/// Returns either __`true`__ if `self` is empty or __`false`__ otherwise
fn is_empty(&self) -> bool;
/// Take a look at the first element __without__ consuming it
///
/// Returns either _`Some(element_ref)`_ if we have a first element or _`None`_ otherwise
fn peek(&self) -> Option<&T>;
/// Take a look at the first `n` elements __without__ consuming them
///
/// Parameters:
/// - `n`: The amount of elements to peek at
///
/// Returns either __`Ok(element_refs)`__ if there were `n` elements avaliable to peek at or
/// __`Err(element_refs)`__ if less elements were available
fn peek_n(&self, n: usize) -> Result<&[T], &[T]>;
/// Consumes the first element and returns it
///
/// Returns either __`Ok(element)`__ if there was an element to consume or __`Err(())`__
/// otherwise
fn pop(&mut self) -> Result<T, ()>;
/// Consumes the first `n` elements and returns them
///
/// Parameters:
/// - `n`: The amount of elements to consume
///
/// Returns either __`Ok(elements)`__ if there were `n` elements avaliable to consume or
/// __`Err(elements)`__ if less elements were available
fn pop_n(&mut self, n: usize) -> Result<Vec<T>, Vec<T>>;
/// Consumes the first `dst.len()` and moves them into `dst`
///
/// Parameters:
/// - `dst`: The target to move the elements into
///
/// Returns either __`Ok(())`__ if `dst` was filled completely or __`Err(element_count)`__ if
/// only `element_count` elements were moved
fn pop_into(&mut self, dst: &mut[T]) -> Result<(), usize>;
/// Discards the first `n` elements
///
/// Parameters:
/// - `n`: The amount of elements to discard
///
/// Returns either __`Ok(())`__ if `n` elements were discarded or __`Err(element_count)`__ if
/// only `element_count` elements were discarded
fn drop_n(&mut self, n: usize) -> Result<(), usize>;
}
pub trait WriteableSliceQueue<T> {
/// The amount of space remaining until `self.limit` is reached
///
/// Returns __the amount of space remaining in `self` until `self.limit` is reached__
fn remaining(&self) -> usize;
/// Reserves an additional amount of memory to append `n` elements without reallocating
///
/// Does nothing if `self.reserved` is greater or equal `n`
///
/// Parameters:
/// - `n`: The amount of elements that we should be able to append without reallocating
///
/// Returns either _nothing_ if the space for `n` elements could be reserved or _the amount of
/// elements reserved_ if `n` was greater than `self.remaining`.
fn reserve_n(&mut self, n: usize) -> Result<(), usize>;
/// The amount of elements that can be appended with out reallocating
///
/// Returns __the amount of elements that can be appended with out reallocating__
fn reserved(&self) -> usize;
/// Appends `element` at the end
///
/// Parameters:
/// - `element`: The element to append at the end
///
/// Returns either __`Ok(())`__ if the element was pushed successfully or __`Err(element)`__ if
/// `element` was not appended because `self.limit` would have been exceeded
fn push(&mut self, element: T) -> Result<(), T>;
/// Appends `n` at the end
///
/// Parameters:
/// - `n`: The n elements to append at the end
///
/// Returns either __`Ok(())`__ if `n` was appended completely or __`Err(remaining_elements)`__
/// if `n` was only appended partially because `self.limit` would have been exceeded
fn push_n(&mut self, n: Vec<T>) -> Result<(), Vec<T>>;
/// Clones and appends the elements in `src` at the end
///
/// Parameters:
/// - `src`: A slice containing the elements to clone and append
///
/// Returns either __`Ok(())`__ if `src` was appended completely or
/// __`Err(remaining_element_count)`__ if `src` was only appended partially because `self.limit`
/// would have been exceeded
fn push_from(&mut self, src: &[T]) -> Result<(), usize> where T: Clone;
/// Calls `push_fn` to push up to `n` elements in place
///
/// __Warning: This function panics if `self.limit` is exceeded__
///
/// The function works like this:
/// 1. `n` default elements are inserted at the end
/// 2. `push_fn` is called with a mutable slice referencing the new elements and returns either
/// the amount of elements pushed or an error
/// 3. If the amount of elements pushed is smaller than `n` or an error occurred, the unused
/// default elements are removed again
///
/// Parameters:
/// - `n`: The amount of bytes to reserve
/// - `push_fn`: The pushing callback
///
/// Returns either _the amount of elements pushed_ or _the error `push_fn` returned_
///
/// Example:
/// ```
/// # extern crate slice_queue;
/// # use slice_queue::*;
/// let mut slice_queue = SliceQueue::new();
///
/// // Successful push
/// slice_queue.push_in_place(7, |buffer: &mut[usize]| -> Result<usize, ()> {
/// (0..4).for_each(|i| buffer[i] = i);
/// Ok(4)
/// });
/// assert_eq!(slice_queue.len(), 4);
/// (0..4).for_each(|i| assert_eq!(slice_queue[i], i));
///
/// // Failed push
/// slice_queue.push_in_place(7, |buffer: &mut[usize]| -> Result<usize, ()> {
/// (0..4).for_each(|i| buffer[i] = i + 7);
/// Err(())
/// });
/// assert_eq!(slice_queue.len(), 4);
/// (0..4).for_each(|i| assert_eq!(slice_queue[i], i));
/// ```
fn push_in_place<E>(&mut self, n: usize, push_fn: impl FnMut(&mut[T]) -> Result<usize, E>) -> Result<usize, E> where T: Default;
}