cl_generic_vec/iter/cursor.rs
1#[allow(unused_imports)]
2use crate::{iter::RawCursor, GenericVec, Storage};
3
4/// This struct is created by [`GenericVec::cursor`]. See its documentation for more.
5pub struct Cursor<'a, S: ?Sized + Storage> {
6 raw: RawCursor<'a, S>,
7}
8
9impl<'a, S: ?Sized + Storage> Cursor<'a, S> {
10 #[inline]
11 pub(crate) fn new(raw: RawCursor<'a, S>) -> Self { Self { raw } }
12
13 /// Get a mutable reference to the underlying `RawCursor`
14 ///
15 /// Updating the state of the underlying `RawCursor` does
16 /// update the state of this `Cursor`
17 pub fn as_raw_cursor_mut(&mut self) -> &mut RawCursor<'a, S> { &mut self.raw }
18
19 /// The number of remaining elements in range of this `Cursor`
20 ///
21 /// The `Cursor` is empty when there are 0 remaining elements
22 #[inline]
23 pub fn len(&self) -> usize { self.raw.len() }
24
25 /// Returns `true` if the `Cursor` is empty
26 #[inline]
27 pub fn is_empty(&self) -> bool { self.raw.is_empty() }
28
29 /// Returns `true` if the `Cursor` is has no unfilled slots
30 /// and the `Cursor` is empty
31 #[inline]
32 pub fn is_write_empty(&self) -> bool { self.raw.is_write_empty() }
33
34 /// Returns true if there is an unfilled slot at the front
35 /// of the `Cursor`
36 #[inline]
37 pub fn is_write_front_empty(&self) -> bool { self.raw.is_write_front_empty() }
38
39 /// Returns true if there is an unfilled slot at the back
40 /// of the `Cursor`
41 #[inline]
42 pub fn is_write_back_empty(&self) -> bool { self.raw.is_write_back_empty() }
43
44 /// Returns the number of unfilled slots if the `Cursor` is empty
45 /// if the `Cursor` is not empty, the behavior is unspecified
46 #[inline]
47 pub fn write_len(&self) -> usize { self.raw.write_len() }
48
49 /// Returns the number of unfilled slots at the front
50 /// of the `Cursor`
51 #[inline]
52 pub fn write_front_len(&self) -> usize { self.raw.write_front_len() }
53
54 /// Returns the number of unfilled slots at the back
55 /// of the `Cursor`
56 #[inline]
57 pub fn write_back_len(&self) -> usize { self.raw.write_back_len() }
58
59 /// Returns a reference to the next element of the `Cursor`.
60 /// Returns `None` if the `Cursor` is empty
61 ///
62 /// Note: this does *not* advance the `Cursor` or
63 /// change the number of unfilled slots
64 #[inline]
65 pub fn front(&self) -> Option<&S::Item> {
66 if self.is_empty() {
67 None
68 } else {
69 unsafe { Some(self.raw.front()) }
70 }
71 }
72
73 /// Returns a mutable reference to the next element of the `Cursor`.
74 /// Returns `None` if the `Cursor` is empty
75 ///
76 /// Note: this does *not* advance the `Cursor` or
77 /// change the number of unfilled slots
78 #[inline]
79 pub fn front_mut(&mut self) -> Option<&mut S::Item> {
80 if self.is_empty() {
81 None
82 } else {
83 unsafe { Some(self.raw.front_mut()) }
84 }
85 }
86
87 /// Returns a reference to the last element of the `Cursor`.
88 /// Returns `None` if the `Cursor` is empty
89 ///
90 /// Note: this does *not* advance the `Cursor` or
91 /// change the number of unfilled slots
92 #[inline]
93 pub fn back(&self) -> Option<&S::Item> {
94 if self.is_empty() {
95 None
96 } else {
97 unsafe { Some(self.raw.back()) }
98 }
99 }
100
101 /// Returns a mutable reference to the last element of the `Cursor`.
102 /// Returns `None` if the `Cursor` is empty
103 ///
104 /// Note: this does *not* advance the `Cursor` or
105 /// change the number of unfilled slots
106 #[inline]
107 pub fn back_mut(&mut self) -> Option<&mut S::Item> {
108 if self.is_empty() {
109 None
110 } else {
111 unsafe { Some(self.raw.back_mut()) }
112 }
113 }
114
115 /// Removes the next element of the `Cursor`
116 /// and removes it from the underlying [`GenericVec`]
117 ///
118 /// Advances the `Cursor` by 1 element
119 ///
120 /// Creates 1 unfilled slot at the front of the `Cursor`.
121 ///
122 /// # Panics
123 ///
124 /// Panics if the `Cursor` is empty
125 #[inline]
126 pub fn take_front(&mut self) -> S::Item {
127 assert!(!self.is_empty(), "Cannot take from a empty `Cursor`");
128 unsafe { self.raw.take_front() }
129 }
130
131 /// Removes the last element of the `Cursor`
132 /// and removes it from the underlying [`GenericVec`]
133 ///
134 /// Advances the `Cursor` by 1 element
135 ///
136 /// Creates 1 unfilled slot at the back of the `Cursor`.
137 ///
138 /// # Panics
139 ///
140 /// Panics if the `Cursor` is empty
141 #[inline]
142 pub fn take_back(&mut self) -> S::Item {
143 assert!(!self.is_empty(), "Cannot take from a empty `Cursor`");
144 unsafe { self.raw.take_back() }
145 }
146
147 /// Drops the next element of the `Cursor`
148 /// and removes them it the underlying [`GenericVec`]
149 ///
150 /// Advances the `Cursor` by 1 element
151 ///
152 /// Creates 1 unfilled slot at the front of the `Cursor`.
153 ///
154 /// # Panics
155 ///
156 /// Panics if the `Cursor` is empty
157 #[inline]
158 pub fn drop_front(&mut self) {
159 assert!(!self.is_empty(), "Cannot drop an element from a empty `Cursor`");
160
161 unsafe { self.raw.drop_front() }
162 }
163
164 /// Drops the last element of the `Cursor`
165 /// and removes them it the underlying [`GenericVec`]
166 ///
167 /// Advances the `Cursor` by 1 element
168 ///
169 /// Creates 1 unfilled slot at the back of the `Cursor`.
170 ///
171 /// # Panics
172 ///
173 /// Panics if the `Cursor` is empty
174 #[inline]
175 pub fn drop_back(&mut self) {
176 assert!(!self.is_empty(), "Cannot drop an element from a empty `Cursor`");
177
178 unsafe { self.raw.drop_back() }
179 }
180
181 /// Drops the next `n` elements of the `Cursor`
182 /// and removes them from the underlying [`GenericVec`]
183 ///
184 /// Advances the `Cursor` by `n` elements
185 ///
186 /// Creates `n` unfilled slots at the front of the `Cursor`.
187 ///
188 /// # Panics
189 ///
190 /// Panics if the `Cursor`'s length is less than `n`
191 #[inline]
192 pub fn drop_n_front(&mut self, n: usize) {
193 assert!(
194 self.len() >= n,
195 "Cannot drop {} elements from a `Cursor` of length {}",
196 n,
197 self.len()
198 );
199
200 unsafe { self.raw.drop_n_front(n) }
201 }
202
203 /// Drops the last `n` elements of the `Cursor`
204 /// and removes them from the underlying [`GenericVec`]
205 ///
206 /// Advances the `Cursor` by `n` elements
207 ///
208 /// Creates `n` unfilled slots at the back of the `Cursor`.
209 ///
210 /// # Panics
211 ///
212 /// Panics if the `Cursor`'s length is less than `n`
213 #[inline]
214 pub fn drop_n_back(&mut self, n: usize) {
215 assert!(
216 self.len() >= n,
217 "Cannot drop {} elements from a `Cursor` of length {}",
218 n,
219 self.len()
220 );
221
222 unsafe { self.raw.drop_n_back(n) }
223 }
224
225 /// Returns `Ok(())` and writes `value` into the unfilled slot
226 /// at the front of the `Cursor` if there is an unfilled slot
227 /// at the front of the `Cursor`
228 ///
229 /// # Errors
230 /// If there are no unfilled slots at the front of the `Cursor`
231 /// then return `Err(value)`
232 #[inline]
233 pub fn try_write_front(&mut self, value: S::Item) -> Result<(), S::Item> {
234 if self.is_write_front_empty() {
235 unsafe { self.raw.write_front(value) }
236 Ok(())
237 } else {
238 Err(value)
239 }
240 }
241
242 /// Writes `value` into the unfilled slot at the front of the
243 /// `Cursor` if there is an unfilled slot at the front of the `Cursor`
244 ///
245 /// Fills in 1 unfilled slot at the front of the `Cursor`
246 ///
247 /// # Panics
248 ///
249 /// Panics if there are no unfilled slots at the front of the `Cursor`
250 #[inline]
251 pub fn write_front(&mut self, value: S::Item) {
252 assert!(
253 !self.is_write_front_empty(),
254 "Cannot write to a empty `Cursor` or if there are not unfilled slots at the front of the `Cursor`"
255 );
256
257 unsafe { self.raw.write_front(value) }
258 }
259
260 /// Returns `Ok(())` and writes `value` into the unfilled slot
261 /// at the back of the `Cursor` if there is an unfilled slot
262 /// at the back of the `Cursor`
263 ///
264 /// # Errors
265 /// If there are no unfilled slots at the back of the `Cursor`
266 /// then return `Err(value)`
267 #[inline]
268 pub fn try_write_back(&mut self, value: S::Item) -> Result<(), S::Item> {
269 if self.is_write_back_empty() {
270 Err(value)
271 } else {
272 unsafe { self.raw.write_back(value) }
273 Ok(())
274 }
275 }
276
277 /// Writes `value` into the unfilled slot at the back of the
278 /// `Cursor` if there is an unfilled slot at the back of the `Cursor`
279 ///
280 /// Fills in 1 unfilled slot at the back of the `Cursor`
281 ///
282 /// # Panics
283 ///
284 /// Panics if there are no unfilled slots at the back of the `Cursor`
285 #[inline]
286 pub fn write_back(&mut self, value: S::Item) {
287 assert!(
288 !self.is_write_back_empty(),
289 "Cannot write to a empty `Cursor` or if there are not unfilled slots at the back of the `Cursor`"
290 );
291
292 unsafe { self.raw.write_back(value) }
293 }
294
295 /// Copies `slice` into the unfilled slots at the front of the
296 /// `Cursor` if there are `slice.len()` unfilled slots at the
297 /// front of the `Cursor`
298 ///
299 /// Fills in `slice.len()` unfilled slots at the front of the `Cursor`
300 ///
301 /// # Panics
302 ///
303 /// Panics if there are less than `slice.len()` unfilled slots
304 /// at the front of the `Cursor`
305 pub fn write_slice_front(&mut self, slice: &[S::Item])
306 where
307 S::Item: Copy,
308 {
309 let write_front_len = self.write_front_len();
310 assert!(
311 write_front_len >= slice.len(),
312 "Cannot write {} elements, only {} slots remaining",
313 slice.len(),
314 write_front_len
315 );
316
317 unsafe { self.raw.write_slice_front(slice) }
318 }
319
320 /// Copies `slice` into the unfilled slots at the back of the
321 /// `Cursor` if there are `slice.len()` unfilled slots at the
322 /// back of the `Cursor`
323 ///
324 /// Fills in `slice.len()` unfilled slots at the back of the `Cursor`
325 ///
326 /// # Panics
327 ///
328 /// Panics if there are less than `slice.len()` unfilled slots
329 /// at the back of the `Cursor`
330 pub fn write_slice_back(&mut self, slice: &[S::Item])
331 where
332 S::Item: Copy,
333 {
334 let write_back_len = self.write_back_len();
335 assert!(
336 write_back_len >= slice.len(),
337 "Cannot write {} elements, only {} slots remaining",
338 slice.len(),
339 write_back_len
340 );
341
342 unsafe { self.raw.write_slice_back(slice) }
343 }
344
345 /// Skips the next element of the `Cursor`
346 /// and keeps it in the underlying [`GenericVec`]
347 ///
348 /// Advances the `Cursor` by 1 element
349 ///
350 /// Does not change the number of unfilled slots.
351 ///
352 /// # Panics
353 ///
354 /// Panics if the `Cursor` is empty
355 #[inline]
356 pub fn skip_front(&mut self) {
357 assert!(!self.is_empty(), "Cannot skip elements from a empty `Cursor`");
358 unsafe { self.raw.skip_front() }
359 }
360
361 /// Skips the last element of the `Cursor`
362 /// and keeps it in the underlying [`GenericVec`]
363 ///
364 /// Advances the `Cursor` by 1 element
365 ///
366 /// Does not change the number of unfilled slots.
367 ///
368 /// # Panics
369 ///
370 /// Panics if the `Cursor` is empty
371 #[inline]
372 pub fn skip_back(&mut self) {
373 assert!(!self.is_empty(), "Cannot skip elements from a empty `Cursor`");
374 unsafe { self.raw.skip_back() }
375 }
376
377 /// Skips the next `n` elements of the `Cursor`
378 /// and keeps them in the underlying [`GenericVec`]
379 ///
380 /// Advances the `Cursor` by `n` elements
381 ///
382 /// Does not change the number of unfilled slots.
383 ///
384 /// # Panics
385 ///
386 /// Panics if the `Cursor`'s length is less than `n`
387 #[inline]
388 pub fn skip_n_front(&mut self, n: usize) {
389 assert!(
390 self.len() >= n,
391 "Cannot skip {} elements from a `Cursor` of length {}",
392 n,
393 self.len()
394 );
395
396 unsafe { self.raw.skip_n_front(n) }
397 }
398
399 /// Skips the last `n` elements of the `Cursor`
400 /// and keeps them in the underlying [`GenericVec`]
401 ///
402 /// Advances the `Cursor` by `n` elements
403 ///
404 /// Does not change the number of unfilled slots.
405 ///
406 /// # Panics
407 ///
408 /// Panics if the `Cursor`'s length is less than `n`
409 #[inline]
410 pub fn skip_n_back(&mut self, n: usize) {
411 assert!(
412 self.len() >= n,
413 "Cannot skip {} elements from a `Cursor` of length {}",
414 n,
415 self.len()
416 );
417
418 unsafe { self.raw.skip_n_back(n) }
419 }
420
421 /// Reserve at least space unfilled slots in the `Cursor`
422 ///
423 /// # Panics
424 ///
425 /// * Panics if the `Cursor` is not empty
426 /// * May panic if the underlying [`GenericVec`] cannot
427 /// reserve more space
428 pub fn reserve(&mut self, space: usize) {
429 assert!(self.is_empty(), "You can only call `reserve` on a empty `Cursor`");
430 self.raw.reserve(space);
431 }
432}