devela/data/list/queue/destaque/methods/general.rs
1// devela::data::list::queue::destaque::methods::general
2
3#[cfg(all(not(feature = "safe_data"), feature = "unsafe_array"))]
4use crate::_core::mem::{transmute_copy, MaybeUninit};
5use crate::{
6 array_from_fn, Array, Bare, Compare, DataNotEnough, Destaque, DestaqueIter, MismatchedCapacity,
7 NotEnoughElements, NotEnoughSpace, Storage,
8};
9#[cfg(feature = "alloc")]
10use crate::{vec_ as vec, Boxed, Vec};
11
12// helper macro to impl methods for a Destque with custom index size.
13macro_rules! impl_destaque {
14 () => {
15 impl_destaque![
16 u8:"_destaque_u8", u16:"_destaque_u16", u32:"_destaque_u32", usize:"_destaque_usize"];
17 };
18
19 // $IDX : the index type. E.g. u8, usize
20 // $cap: the capability feature that enables the given implementation. E.g "_destaque_u8".
21 ($( $IDX:ty: $cap:literal ),+) => {
22 $(
23 #[cfg(feature = $cap )]
24 impl_destaque![@$IDX:$cap];
25 )+
26 };
27 (@$IDX:ty : $cap:literal) => { $crate::paste! {
28
29 /* constructors */
30
31 #[doc = "# Methods for `Destaque" $IDX:camel "`\n\n"]
32 /// --------------------------------------------------
33 /// --------------------------------------------------
34 #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $cap)))]
35 impl<T: Clone, const CAP: usize> Destaque<T, CAP, $IDX, Bare> {}
36
37 // T: Clone, S: Bare
38 impl<T: Clone, const CAP: usize> Destaque<T, CAP, $IDX, Bare> {
39 /// Returns an empty destaque, allocated in the stack,
40 /// cloning `element` to fill the remaining free data.
41 ///
42 /// # Errors
43 #[doc = "Returns [`MismatchedCapacity`] if `CAP > `[`" $IDX "::MAX`]"]
44 /// or if `CAP > isize::MAX / size_of::<T>()`.
45 ///
46 /// # Examples
47 /// ```
48 #[doc = "# use devela::Destaque" $IDX:camel ";"]
49 #[doc = "let q = Destaque" $IDX:camel "::<_, 16>::new(0).unwrap();"]
50 /// ```
51 pub fn new(element: T) -> Result<Self, MismatchedCapacity> {
52 let max = Compare($IDX::MAX as usize).min(isize::MAX as usize / size_of::<T>());
53 if CAP > max {
54 Err(MismatchedCapacity::closed(0, max, CAP))
55 } else {
56 Ok(Self {
57 data: Array::<T, CAP, Bare>::with_cloned(element),
58 front: 0,
59 back: 0,
60 len: 0,
61 })
62 }
63 }
64 }
65
66 // T: Copy, S: Bare
67 impl<T: Copy, const CAP: usize> Destaque<T, CAP, $IDX, Bare> {
68 /// Returns an empty destaque, allocated in the stack,
69 /// copying `element` to fill the remaining free data, in compile-time.
70 ///
71 /// # Errors
72 #[doc = "Returns [`MismatchedCapacity`] if `CAP > `[`" $IDX "::MAX`]"]
73 /// or if `CAP > isize::MAX / size_of::<T>()`.
74 ///
75 /// # Examples
76 /// ```
77 #[doc = "# use devela::{Destaque" $IDX:camel ", unwrap};"]
78 #[doc = "const S: Destaque" $IDX:camel
79 "<i32, 16> = unwrap![ok Destaque" $IDX:camel "::new_copied(0)];"]
80 /// ```
81 pub const fn new_copied(element: T) -> Result<Self, MismatchedCapacity> {
82 let max = Compare($IDX::MAX as usize).min(isize::MAX as usize / size_of::<T>());
83 if CAP > max {
84 Err(MismatchedCapacity::closed(0, max, CAP))
85 } else {
86 let data = Array::with_copied(element);
87 Ok(Self { data, front: 0, back: 0, len: 0 })
88 }
89 }
90 }
91
92 // T: Clone, S: Boxed
93 #[cfg(feature = "alloc")]
94 #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "alloc")))]
95 impl<T: Clone, const CAP: usize> Destaque<T, CAP, $IDX, Boxed> {
96 /// Returns an empty destaque, allocated in the heap,
97 /// cloning `element` to fill the remaining free data.
98 ///
99 /// # Examples
100 /// ```
101 #[doc = "# use devela::{Boxed, Destaque" $IDX:camel "};"]
102 #[doc = "let q = Destaque" $IDX:camel "::<_, 3, Boxed>::new(0);"]
103 /// ```
104 pub fn new(element: T) -> Self {
105 Self {
106 data: Array::<T, CAP, Boxed>::with_cloned(element),
107 front: 0,
108 back: 0,
109 len: 0,
110 }
111 }
112 }
113
114 // T, S: Bare
115 impl<T, const CAP: usize> Destaque<T, CAP, $IDX, Bare> {
116 /// Converts an array into a [`full`][Self::is_full] destaque.
117 ///
118 /// # Examples
119 /// ```
120 #[doc = "# use devela::Destaque" $IDX:camel ";"]
121 #[doc = "let q = Destaque" $IDX:camel "::<_, 3>::from_array([1, 2, 3]);"]
122 /// ```
123 pub const fn from_array_copy(arr: [T; CAP]) -> Destaque<T, CAP, $IDX, Bare> {
124 Self {
125 data: Array::new_bare(arr),
126 front: 0,
127 back: 0,
128 len: CAP as $IDX,
129 }
130 }
131 }
132
133 // T, S
134 impl<T, const CAP: usize, S: Storage> Destaque<T, CAP, $IDX, S> {
135 /// Converts an array into a [`full`][Self::is_full] destaque.
136 ///
137 /// # Examples
138 /// ```
139 #[doc = "# use devela::Destaque" $IDX:camel ";"]
140 #[doc = "let q = Destaque" $IDX:camel "::<_, 3>::from_array([1, 2, 3]);"]
141 /// ```
142 pub fn from_array(arr: [T; CAP]) -> Destaque<T, CAP, $IDX, S> {
143 Self {
144 data: Array::new(arr),
145 front: 0,
146 back: 0,
147 len: CAP as $IDX,
148 }
149 }
150
151 /* queries */
152
153 /// Returns the number of destaqued elements.
154 pub const fn len(&self) -> $IDX {
155 self.len as $IDX
156 }
157
158 /// Returns `true` if the destaque is empty.
159 /// # Examples
160 /// ```
161 #[doc = "# use devela::Destaque" $IDX:camel ";"]
162 #[doc = "let q = Destaque" $IDX:camel "::<i32, 8>::default();"]
163 /// assert![q.is_empty()];
164 /// ```
165 pub const fn is_empty(&self) -> bool {
166 self.len() == 0
167 }
168
169 /// Returns `true` if the destaque is full.
170 /// # Examples
171 /// ```
172 #[doc = "# use devela::Destaque" $IDX:camel ";"]
173 #[doc = "let q = Destaque" $IDX:camel "::<_, 3>::from([1, 2, 3]);"]
174 /// assert![q.is_full()];
175 /// ```
176 pub const fn is_full(&self) -> bool {
177 self.len() as usize == CAP
178 }
179
180 /// Returns the destaque's total capacity.
181 /// # Examples
182 /// ```
183 #[doc = "# use devela::Destaque" $IDX:camel ";"]
184 #[doc = "let q = Destaque" $IDX:camel "::<i32, 3>::default();"]
185 /// assert_eq![3, q.capacity()];
186 /// ```
187 pub const fn capacity(&self) -> $IDX {
188 CAP as $IDX
189 }
190
191 /// Returns the destaque's remaining capacity.
192 /// # Examples
193 /// ```
194 #[doc = "# use devela::Destaque" $IDX:camel ";"]
195 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
196 #[doc = "let mut q = Destaque" $IDX:camel "::<i32, 3>::default();"]
197 /// assert_eq![3, q.remaining_capacity()];
198 /// q.push_back(1)?;
199 /// assert_eq![2, q.remaining_capacity()];
200 /// # Ok(()) }
201 /// ```
202 pub const fn remaining_capacity(&self) -> $IDX {
203 CAP as $IDX - self.len()
204 }
205
206 //
207
208 /// Returns the destaque as pair of shared slices, which contain, in order,
209 /// the contents of the destaque.
210 /// # Examples
211 /// ```
212 #[doc = "# use devela::Destaque" $IDX:camel ";"]
213 #[doc = "let q = Destaque" $IDX:camel "::<_, 3>::from([1, 2, 3]);"]
214 /// assert_eq![q.as_slices(), (&[1, 2, 3][..], &[][..])];
215 /// ```
216 pub fn as_slices(&self) -> (&[T], &[T]) {
217 if self.len == 0 {
218 (&[], &[])
219 } else if self.front < self.back {
220 // Non-wrap-around case
221 let slice = &self.data[self.front as usize..self.back as usize];
222 (slice, &[])
223 } else {
224 // Wrap-around case
225 let first_slice = &self.data[self.front as usize..CAP];
226 let second_slice = &self.data[..self.back as usize];
227 (first_slice, second_slice)
228 }
229 }
230
231 /// Returns `true` if the destaque is contiguous.
232 /// # Examples
233 /// ```
234 #[doc = "# use devela::Destaque" $IDX:camel ";"]
235 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
236 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 3>::from([1, 2, 3]);"]
237 /// assert_eq![q.as_slices(), (&[1, 2, 3][..], &[][..])];
238 /// assert![q.is_contiguous()];
239 /// q.pop_back()?;
240 /// q.push_front(4)?;
241 /// assert![!q.is_contiguous()];
242 /// assert_eq![q.as_slices(), (&[4][..], &[1, 2][..])];
243 /// # Ok(()) }
244 /// ```
245 pub const fn is_contiguous(&self) -> bool {
246 (self.front == 0 && self.back == 0) || (self.front < self.back)
247 }
248
249 /* push */
250
251 /// Pushes a new `element` to the front of the destaque.
252 ///
253 /// `( 1 2 -- 3 1 2 )`
254 /// # Errors
255 /// Returns [`NotEnoughSpace`] if the destaque is full.
256 /// # Examples
257 /// ```
258 #[doc = "# use devela::Destaque" $IDX:camel ";"]
259 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
260 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 3>::default();"]
261 /// q.push_front(1)?;
262 /// q.push_front(2)?;
263 /// q.push_front(3)?;
264 /// assert_eq![q.to_array(), Some([3, 2, 1])];
265 /// # Ok(()) }
266 /// ```
267 pub fn push_front(&mut self, element: T) -> Result<(), NotEnoughSpace> {
268 if self.is_full() {
269 Err(NotEnoughSpace(Some(1)))
270 } else {
271 self.front = (self.front + CAP as $IDX - 1) % CAP as $IDX;
272 self.data[self.front as usize] = element;
273 self.len += 1;
274 Ok(())
275 }
276 }
277
278 /// Unchecked version of [`push_front`][Self::push_front].
279 /// # Panics
280 /// Panics if the destaque is full.
281 pub fn push_front_unchecked(&mut self, element: T) {
282 self.front = (self.front + CAP as $IDX - 1) % CAP as $IDX;
283 self.data[self.front as usize] = element;
284 self.len += 1;
285 }
286
287 /// Pushes a new `element` to the front of the destaque,
288 /// overriding an element from the back if the destaque is full.
289 ///
290 /// Returns `true` if an element was overridden, and `false` otherwise.
291 ///
292 /// # Examples
293 /// ```
294 #[doc = "# use devela::Destaque" $IDX:camel ";"]
295 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 3>::from([1, 2]);"]
296 /// assert_eq!(q.push_front_override(3), false);
297 /// assert_eq![q.to_array(), Some([3, 1, 2])];
298 /// assert_eq!(q.push_front_override(4), true);
299 /// assert_eq![q.to_array(), Some([4, 3, 1])];
300 /// ```
301 pub fn push_front_override(&mut self, element: T) -> bool {
302 let overridden = self.is_full();
303 if overridden {
304 // drop_back
305 self.back = (self.back + CAP as $IDX - 1) % CAP as $IDX;
306 self.len -= 1;
307 }
308 // push_front
309 self.front = (self.front + CAP as $IDX - 1) % CAP as $IDX;
310 self.data[self.front as usize] = element;
311 self.len += 1;
312 overridden
313 }
314
315 /// Pushes a new `element` to the back of the destaque.
316 ///
317 /// This is the habitual *enqueue* operation for a single-ended **queue**.
318 ///
319 /// `( 1 2 -- 1 2 3 )`
320 /// # Errors
321 /// Returns [`NotEnoughSpace`] if the destaque is full.
322 /// # Examples
323 /// ```
324 #[doc = "# use devela::Destaque" $IDX:camel ";"]
325 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
326 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 3>::default();"]
327 /// q.push_back(1)?;
328 /// q.push_back(2)?;
329 /// q.push_back(3)?;
330 /// assert_eq![q.to_array(), Some([1, 2, 3])];
331 /// # Ok(()) }
332 /// ```
333 pub fn push_back(&mut self, element: T) -> Result<(), NotEnoughSpace> {
334 if self.is_full() {
335 Err(NotEnoughSpace(Some(1)))
336 } else {
337 Ok(self.push_back_unchecked(element))
338 }
339 }
340 /// Alias of [`push_back`][Self::push_back].
341 ///
342 /// This is the habitual *enqueue* operation for a single-ended **queue**.
343 pub fn enqueue(&mut self, element: T) -> Result<(), NotEnoughSpace> {
344 self.push_back(element)
345 }
346
347 /// Unchecked version of [`push_back`][Self::push_back].
348 /// # Panics
349 /// Panics if the destaque is full.
350 pub fn push_back_unchecked(&mut self, element: T) {
351 self.data[self.back as usize] = element;
352 self.back = (self.back + 1) % CAP as $IDX;
353 self.len += 1;
354 }
355
356 /// Pushes a new `element` to the back of the destaque,
357 /// overriding the first element if the destaque is full.
358 ///
359 /// Returns `true` if an element was overridden, and `false` otherwise.
360 ///
361 /// # Examples
362 /// ```
363 #[doc = "# use devela::Destaque" $IDX:camel ";"]
364 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 3>::from([1, 2]);"]
365 /// assert_eq!(q.push_back_override(3), false);
366 /// assert_eq![q.to_array(), Some([1, 2, 3])];
367 /// assert_eq!(q.push_back_override(4), true);
368 /// assert_eq![q.to_array(), Some([2, 3, 4])];
369 /// ```
370 pub fn push_back_override(&mut self, element: T) -> bool {
371 let overridden = self.is_full();
372 if overridden {
373 // drop_front
374 self.front = (self.front + 1) % CAP as $IDX;
375 self.len -= 1;
376 }
377 // push_back
378 self.data[self.back as usize] = element;
379 self.back = (self.back + 1) % CAP as $IDX;
380 self.len += 1;
381 overridden
382 }
383
384 /* pop */
385
386 /// Pops the front element.
387 ///
388 /// This is the habitual *dequeue* operation for a signle-ended **queue**.
389 ///
390 /// `( 1 2 -- 2 )`
391 /// # Errors
392 /// Returns [`NotEnoughElements`] if the queue is empty.
393 /// # Examples
394 /// ```
395 #[doc = "# use devela::Destaque" $IDX:camel ";"]
396 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
397 ///
398 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3]);"]
399 /// assert_eq![1, q.pop_front()?];
400 /// assert_eq![2, q.pop_front()?];
401 /// assert_eq![3, q.pop_front()?];
402 /// assert![q.is_empty()];
403 /// # Ok(()) }
404 /// ```
405 /// # Features
406 /// It's depends on `T: Clone`, unless the `unsafe_ptr` feature is enabled.
407 #[cfg(all(not(feature = "safe_data"), feature = "unsafe_ptr"))]
408 #[cfg_attr(feature = "nightly_doc", doc(cfg(any(feature = "unsafe_ptr", Clone))))]
409 pub fn pop_front(&mut self) -> Result<T, NotEnoughElements> {
410 if self.is_empty() {
411 Err(NotEnoughElements(Some(1)))
412 } else {
413 // MOTIVATION: to not depend on T: Clone
414 // SAFETY: we're not gonna access the value, but move it out
415 let e = unsafe {
416 core::ptr::read((self.data.get_unchecked(self.front as usize)) as *const T)
417 };
418 self.front = (self.front + 1) % CAP as $IDX;
419 self.len -= 1;
420 Ok(e)
421 }
422 }
423
424 /// Alias of [`pop_front`][Self::pop_front].
425 ///
426 /// This is the habitual *dequeue* operation for a single-ended **queue**.
427 #[cfg(all(not(feature = "safe_data"), feature = "unsafe_ptr"))]
428 #[cfg_attr(feature = "nightly_doc", doc(cfg(any(feature = "unsafe_ptr", Clone))))]
429 pub fn dequeue(&mut self) -> Result<T, NotEnoughElements> {
430 self.pop_front()
431 }
432
433 /// Pops the back element.
434 ///
435 /// `( 1 2-- 1 )`
436 /// # Errors
437 /// Returns [`NotEnoughElements`] if the destaque is empty.
438 /// # Examples
439 /// ```
440 #[doc = "# use devela::Destaque" $IDX:camel ";"]
441 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
442 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3]);"]
443 /// assert_eq![3, q.pop_back()?];
444 /// assert_eq![2, q.pop_back()?];
445 /// assert_eq![1, q.pop_back()?];
446 /// assert![q.is_empty()];
447 /// # Ok(()) }
448 /// ```
449 /// # Features
450 /// It's depends on `T: Clone`, unless the `unsafe_ptr` feature is enabled.
451 #[cfg(all(not(feature = "safe_data"), feature = "unsafe_ptr"))]
452 #[cfg_attr(feature = "nightly_doc", doc(cfg(any(feature = "unsafe_ptr", Clone))))]
453 pub fn pop_back(&mut self) -> Result<T, NotEnoughElements> {
454 if self.is_empty() {
455 Err(NotEnoughElements(Some(1)))
456 } else {
457 self.back = (self.back + CAP as $IDX - 1) % CAP as $IDX;
458 // MOTIVATION: to not depend on T: Clone
459 // SAFETY: we're not gonna access the value, but move it out
460 let e = unsafe {
461 core::ptr::read((self.data.get_unchecked(self.back as usize)) as *const T)
462 };
463 self.len -= 1;
464 Ok(e)
465 }
466 }
467
468 /* peek */
469
470 /// Returns a shared reference to the back element.
471 /// # Errors
472 /// Returns [`NotEnoughElements`] if the destaque is empty.
473 /// # Examples
474 /// ```
475 #[doc = "# use devela::Destaque" $IDX:camel ";"]
476 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
477 #[doc = "let q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3]);"]
478 /// assert_eq![&3, q.peek_back()?];
479 /// # Ok(()) }
480 /// ```
481 pub fn peek_back(&self) -> Result<&T, NotEnoughElements> {
482 if self.is_empty() {
483 Err(NotEnoughElements(Some(1)))
484 } else {
485 let bi = self.idx_back(0);
486 Ok(&self.data[bi])
487 }
488 }
489
490 /// Returns an exclusive reference to the back element.
491 /// # Errors
492 /// Returns [`NotEnoughElements`] if the destaque is empty.
493 /// # Examples
494 /// ```
495 #[doc = "# use devela::Destaque" $IDX:camel ";"]
496 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
497 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3]);"]
498 /// assert_eq![&mut 3, q.peek_back_mut()?];
499 /// # Ok(()) }
500 /// ```
501 pub fn peek_back_mut(&mut self) -> Result<&mut T, NotEnoughElements> {
502 if self.is_empty() {
503 Err(NotEnoughElements(Some(1)))
504 } else {
505 let bi = self.idx_back(0);
506 Ok(&mut self.data[bi])
507 }
508 }
509
510 /// Returns a shared reference to the `nth` back element.
511 /// # Errors
512 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least `nth` elements.
513 /// # Examples
514 /// ```
515 #[doc = "# use devela::Destaque" $IDX:camel ";"]
516 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
517 #[doc = "let q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3]);"]
518 /// assert_eq![&1, q.peek_nth_back(2)?];
519 /// # Ok(()) }
520 /// ```
521 pub fn peek_nth_back(&self, nth: $IDX) -> Result<&T, NotEnoughElements> {
522 if self.len() <= nth {
523 Err(NotEnoughElements(Some(nth as usize)))
524 } else {
525 let bi = self.idx_back(nth);
526 Ok(&self.data[bi])
527 }
528 }
529
530 /// Returns an exclusive reference to the `nth` back element.
531 /// # Errors
532 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least `nth` elements.
533 /// # Examples
534 /// ```
535 #[doc = "# use devela::Destaque" $IDX:camel ";"]
536 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
537 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3]);"]
538 /// assert_eq![&mut 1, q.peek_nth_back_mut(2)?];
539 /// # Ok(()) }
540 /// ```
541 pub fn peek_nth_back_mut(&mut self, nth: $IDX) -> Result<&mut T, NotEnoughElements> {
542 if self.len() <= nth {
543 Err(NotEnoughElements(Some(nth as usize)))
544 } else {
545 let bi = self.idx_back(nth);
546 Ok(&mut self.data[bi])
547 }
548 }
549
550 /// Returns a shared reference to the front element.
551 /// # Errors
552 /// Returns [`NotEnoughElements`] if the destaque is empty.
553 /// # Examples
554 /// ```
555 #[doc = "# use devela::Destaque" $IDX:camel ";"]
556 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
557 #[doc = "let q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3]);"]
558 /// assert_eq![&1, q.peek_front()?];
559 /// # Ok(()) }
560 /// ```
561 pub fn peek_front(&self) -> Result<&T, NotEnoughElements> {
562 if self.is_empty() {
563 Err(NotEnoughElements(Some(1)))
564 } else {
565 let fi = self.idx_front(0);
566 Ok(&self.data[fi])
567 }
568 }
569
570 /// Returns an exclusive reference to the front element.
571 /// # Errors
572 /// Returns [`NotEnoughElements`] if the destaque is empty.
573 /// # Examples
574 /// ```
575 #[doc = "# use devela::Destaque" $IDX:camel ";"]
576 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
577 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3]);"]
578 /// assert_eq![&mut 1, q.peek_front_mut()?];
579 /// # Ok(()) }
580 /// ```
581 pub fn peek_front_mut(&mut self) -> Result<&mut T, NotEnoughElements> {
582 if self.is_empty() {
583 Err(NotEnoughElements(Some(1)))
584 } else {
585 let fi = self.idx_front(0);
586 Ok(&mut self.data[fi])
587 }
588 }
589
590 /// Returns a shared reference to the `nth` front element.
591 /// # Errors
592 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least `nth` elements.
593 /// # Examples
594 /// ```
595 #[doc = "# use devela::Destaque" $IDX:camel ";"]
596 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
597 #[doc = "let q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3, 4]);"]
598 /// assert_eq![&3, q.peek_nth_front(2)?];
599 /// # Ok(()) }
600 /// ```
601 pub fn peek_nth_front(&self, nth: $IDX) -> Result<&T, NotEnoughElements> {
602 if self.len() <= nth {
603 Err(NotEnoughElements(Some(nth as usize)))
604 } else {
605 let bi = self.idx_front(nth);
606 Ok(&self.data[bi])
607 }
608 }
609
610 /// Returns an exclusive reference to the `nth` front element.
611 /// # Errors
612 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least `nth` elements.
613 /// # Examples
614 /// ```
615 #[doc = "# use devela::Destaque" $IDX:camel ";"]
616 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
617 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3, 4]);"]
618 /// assert_eq![&mut 3, q.peek_nth_front_mut(2)?];
619 /// # Ok(()) }
620 /// ```
621 pub fn peek_nth_front_mut(&mut self, nth: $IDX) -> Result<&mut T, NotEnoughElements> {
622 if self.len() <= nth {
623 Err(NotEnoughElements(Some(nth as usize)))
624 } else {
625 let bi = self.idx_front(nth);
626 Ok(&mut self.data[bi])
627 }
628 }
629
630 /* clear */
631
632 /// Clears the destaque.
633 ///
634 /// `( 1 2 -- )`
635 /// # Examples
636 /// ```
637 #[doc = "# use devela::Destaque" $IDX:camel ";"]
638 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3, 4]);"]
639 /// q.clear();
640 /// assert![q.is_empty()];
641 /// ```
642 pub const fn clear(&mut self) {
643 self.front = 0;
644 self.back = 0;
645 self.len = 0;
646 }
647
648 /* drop */
649
650 /// Drops the back element.
651 ///
652 /// `( 1 2 -- 1 )`
653 /// # Errors
654 /// Returns [`NotEnoughElements`] if the destaque is empty.
655 /// # Examples
656 /// ```
657 #[doc = "# use devela::Destaque" $IDX:camel ";"]
658 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
659 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2]);"]
660 /// q.drop_back()?;
661 /// assert_eq![q.to_array(), Some([1])];
662 /// # Ok(()) }
663 /// ```
664 pub fn drop_back(&mut self) -> Result<(), NotEnoughElements> {
665 if self.is_empty() {
666 Err(NotEnoughElements(Some(1)))
667 } else {
668 self.back = (self.back + CAP as $IDX - 1) % CAP as $IDX;
669 self.len -= 1;
670 Ok(())
671 }
672 }
673
674 /// Drops the front element.
675 ///
676 /// `( 1 2 -- 2 )`
677 /// # Errors
678 /// Returns [`NotEnoughElements`] if the destaque is empty.
679 /// # Examples
680 /// ```
681 #[doc = "# use devela::Destaque" $IDX:camel ";"]
682 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
683 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2]);"]
684 /// q.drop_front()?;
685 /// assert_eq![q.to_array(), Some([2])];
686 /// # Ok(()) }
687 /// ```
688 pub fn drop_front(&mut self) -> Result<(), NotEnoughElements> {
689 if self.is_empty() {
690 Err(NotEnoughElements(Some(1)))
691 } else {
692 self.front = (self.front as $IDX + 1) % CAP as $IDX;
693 self.len -= 1;
694 Ok(())
695 }
696 }
697
698 /// Drops `n` elements from the back.
699 ///
700 /// `( 1 2 3 4 -- 1 )` for `n = 3`
701 /// # Errors
702 /// Returns [`NotEnoughElements`] if the destaque doesn't contain at least `nth` elements.
703 /// # Examples
704 /// ```
705 #[doc = "# use devela::Destaque" $IDX:camel ";"]
706 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
707 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3, 4]);"]
708 /// q.drop_n_back(3)?;
709 /// assert_eq![q.to_array(), Some([1])];
710 /// # Ok(()) }
711 /// ```
712 pub fn drop_n_back(&mut self, nth: $IDX) -> Result<(), NotEnoughElements> {
713 if self.len() <= nth {
714 Err(NotEnoughElements(Some(nth as usize)))
715 } else {
716 self.back = (self.back + CAP as $IDX - nth) % CAP as $IDX;
717 self.len -= nth;
718 Ok(())
719 }
720 }
721
722 /// Drops `n` elements from the front.
723 ///
724 /// `( 1 2 3 4 -- 4 )` for `n = 3`
725 /// # Errors
726 /// Returns [`NotEnoughElements`]
727 /// if the destaque doesn't contain at least `nth` elements.
728 /// # Examples
729 /// ```
730 #[doc = "# use devela::Destaque" $IDX:camel ";"]
731 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
732 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3, 4]);"]
733 /// q.drop_n_front(3)?;
734 /// assert_eq![q.to_array(), Some([4])];
735 /// # Ok(()) }
736 /// ```
737 pub fn drop_n_front(&mut self, nth: $IDX) -> Result<(), NotEnoughElements> {
738 if self.len() <= nth {
739 Err(NotEnoughElements(Some(nth as usize)))
740 } else {
741 self.front = (self.front + nth) % CAP as $IDX;
742 self.len -= nth;
743 Ok(())
744 }
745 }
746
747 /* swap */
748
749 /// Swaps the last two elements at the back of the destaque.
750 ///
751 /// `( 1 2 3 4 -- 1 2 4 3 )`
752 /// # Errors
753 /// Returns [`NotEnoughElements`] if the destaque doesn't contain at least 2 elements.
754 /// # Examples
755 /// ```
756 #[doc = "# use devela::Destaque" $IDX:camel ";"]
757 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 4>::from([1, 2, 3, 4]);"]
758 /// q.swap_back();
759 /// assert_eq![q.to_array(), Some([1, 2, 4, 3])];
760 /// ```
761 pub fn swap_back(&mut self) -> Result<(), NotEnoughElements> {
762 if self.len() < 2 {
763 Err(NotEnoughElements(Some(2)))
764 } else {
765 self.swap_back_unchecked();
766 Ok(())
767 }
768 }
769 /// Unchecked version of [`swap_back`][Self::swap_back].
770 /// # Panics
771 /// Panics if the destaque doesn't contain at least 2 elements.
772 pub fn swap_back_unchecked(&mut self) {
773 let bi0 = self.idx_back(0);
774 let bi1 = self.idx_back(1);
775 self.data.swap(bi0, bi1);
776 }
777
778 /// Swaps the first two elements at the front of the destaque.
779 ///
780 /// `( 1 2 3 4 -- 2 1 3 4 )`
781 /// # Errors
782 /// Returns [`NotEnoughElements`] if the destaque doesn't contain at least 2 elements.
783 /// # Examples
784 /// ```
785 #[doc = "# use devela::Destaque" $IDX:camel ";"]
786 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 4>::from([1, 2, 3, 4]);"]
787 /// q.swap_front();
788 /// assert_eq![q.to_array(), Some([2, 1, 3, 4])];
789 /// ```
790 pub fn swap_front(&mut self) -> Result<(), NotEnoughElements> {
791 if self.len() < 2 {
792 Err(NotEnoughElements(Some(2)))
793 } else {
794 self.swap_front_unchecked();
795 Ok(())
796 }
797 }
798 /// Unchecked version of [`swap_front`][Self::swap_front].
799 /// # Panics
800 /// Panics if the destaque doesn't contain at least 2 elements.
801 pub fn swap_front_unchecked(&mut self) {
802 let fi0 = self.idx_front(0);
803 let fi1 = self.idx_front(1);
804 self.data.swap(fi0, fi1);
805 }
806
807 /// Swaps the last two pairs of elements at the back of the destaque.
808 ///
809 /// `( 1 2 3 4 5 6 7 8 -- 1 2 3 4 7 8 5 6 )`
810 /// # Errors
811 /// Returns [`NotEnoughElements`] if the destaque doesn't contain at least 2 elements.
812 /// # Examples
813 /// ```
814 #[doc = "# use devela::Destaque" $IDX:camel ";"]
815 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 16>::from([1, 2, 3, 4, 5, 6, 7, 8]);"]
816 /// q.swap2_back();
817 /// assert_eq![q.to_array(), Some([1, 2, 3, 4, 7, 8, 5, 6])];
818 /// ```
819 pub fn swap2_back(&mut self) -> Result<(), NotEnoughElements> {
820 if self.len() < 4 {
821 Err(NotEnoughElements(Some(4)))
822 } else {
823 self.swap2_back_unchecked();
824 Ok(())
825 }
826 }
827 /// Unchecked version of [`swap2_back`][Self::swap2_back].
828 /// # Panics
829 /// Panics if the destaque doesn't contain at least 2 elements.
830 pub fn swap2_back_unchecked(&mut self) {
831 let bi0 = self.idx_back(0);
832 let bi1 = self.idx_back(1);
833 let bi2 = self.idx_back(2);
834 let bi3 = self.idx_back(3);
835 self.data.swap(bi1, bi3);
836 self.data.swap(bi0, bi2);
837 }
838
839 /// Swaps the first two pairs of elements at the front of the destaque.
840 /// `( 1 2 3 4 5 6 7 8 -- 3 4 1 2 5 6 7 8 )`
841 /// # Errors
842 /// Returns [`NotEnoughElements`] if the destaque doesn't contain at least 4 elements.
843 /// # Examples
844 /// ```
845 #[doc = "# use devela::Destaque" $IDX:camel ";"]
846 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 16>::from([1, 2, 3, 4, 5, 6, 7, 8]);"]
847 /// q.swap2_front();
848 /// assert_eq![q.to_array(), Some([3, 4, 1, 2, 5, 6, 7, 8])];
849 /// ```
850 pub fn swap2_front(&mut self) -> Result<(), NotEnoughElements> {
851 if self.len() < 4 {
852 Err(NotEnoughElements(Some(4)))
853 } else {
854 self.swap2_front_unchecked();
855 Ok(())
856 }
857 }
858 /// Unchecked version of [`swap2_back`][Self::swap2_back].
859 /// # Panics
860 /// Panics if the destaque doesn't contain at least 2 elements.
861 pub fn swap2_front_unchecked(&mut self) {
862 let fi0 = self.idx_front(0);
863 let fi1 = self.idx_front(1);
864 let fi2 = self.idx_front(2);
865 let fi3 = self.idx_front(3);
866 self.data.swap(fi1, fi3);
867 self.data.swap(fi0, fi2);
868 }
869
870 /// Swaps the front and back elements.
871 ///
872 /// `( 1 2 3 4 -- 4 2 3 1 )`
873 /// # Errors
874 /// Returns [`NotEnoughElements`] if the destaque doesn't contain at least 2 elements.
875 /// # Examples
876 /// ```
877 #[doc = "# use devela::Destaque" $IDX:camel ";"]
878 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 6>::from([1, 2, 3, 4, 5]);"]
879 /// q.swap_ends();
880 /// assert_eq![q.to_array(), Some([5, 2, 3, 4, 1])];
881 /// ```
882 pub fn swap_ends(&mut self) -> Result<(), NotEnoughElements> {
883 if self.len() < 2 {
884 Err(NotEnoughElements(Some(2)))
885 } else {
886 let bi0 = self.idx_back(0);
887 let fi0 = self.idx_front(0);
888 self.data.swap(bi0, fi0);
889 Ok(())
890 }
891 }
892 /// Swaps the front and back pairs of elements.
893 ///
894 /// `( 1 2 3 4 5 6 7 8 -- 7 8 3 4 5 6 1 2 )`
895 /// # Errors
896 /// Returns [`NotEnoughElements`] if the destaque doesn't contain at least 4 elements.
897 /// # Examples
898 /// ```
899 #[doc = "# use devela::Destaque" $IDX:camel ";"]
900 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 16>::from([1, 2, 3, 4, 5, 6, 7, 8]);"]
901 /// q.swap2_ends();
902 /// assert_eq![q.to_array(), Some([7, 8, 3, 4, 5, 6, 1, 2])];
903 /// ```
904 pub fn swap2_ends(&mut self) -> Result<(), NotEnoughElements> {
905 if self.len() < 4 {
906 Err(NotEnoughElements(Some(4)))
907 } else {
908 let bi0 = self.idx_back(0);
909 let bi1 = self.idx_back(1);
910 let fi0 = self.idx_front(0);
911 let fi1 = self.idx_front(1);
912 self.data.swap(bi0, fi1);
913 self.data.swap(bi1, fi0);
914 Ok(())
915 }
916 }
917
918 /* rot */
919
920 /// Rotates all the destaqued elements one place to the right.
921 ///
922 /// `( 1 2 3 4 -- 4 1 2 3 )`
923 /// # Examples
924 /// ```
925 #[doc = "# use devela::Destaque" $IDX:camel ";"]
926 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
927 #[doc = "let mut q = Destaque" $IDX:camel "::<i32, 8>::from([2, 3]);"]
928 /// q.push_front(1)?;
929 /// q.push_back(4)?;
930 /// assert_eq![q.to_array(), Some([1, 2, 3, 4])];
931 /// q.rot_right();
932 /// assert_eq![q.to_array(), Some([4, 1, 2, 3])];
933 /// # Ok(()) }
934 /// ```
935 pub fn rot_right(&mut self) {
936 if !self.is_empty() {
937 // equivalent to: self.push_front(self.pop_back()?)?
938 self.back = (self.back + CAP as $IDX - 1) % CAP as $IDX;
939 self.front = (self.front + CAP as $IDX - 1) % CAP as $IDX;
940 self.data.swap(self.back as usize, self.front as usize);
941 }
942 }
943
944 /// Rotates all the destaqued elements `n` places to the right.
945 ///
946 /// `( 1 2 3 4 -- 2 3 4 1 )` for `n = 3`
947 /// # Examples
948 /// ```
949 #[doc = "# use devela::Destaque" $IDX:camel ";"]
950 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
951 #[doc = "let mut q = Destaque" $IDX:camel "::<i32, 8>::from([2, 3]);"]
952 /// q.push_front(1)?;
953 /// q.push_back(4)?;
954 /// assert_eq![q.to_array(), Some([1, 2, 3, 4])];
955 /// q.rot_right_n(3);
956 /// assert_eq![q.to_array(), Some([2, 3, 4, 1])];
957 /// # Ok(()) }
958 /// ```
959 pub fn rot_right_n(&mut self, nth: $IDX) {
960 // don't rotate more than necessary
961 let nth = nth % self.len();
962 for _ in 0..nth as usize {
963 self.back = (self.back + CAP as $IDX - 1) % CAP as $IDX;
964 self.front = (self.front + CAP as $IDX - 1) % CAP as $IDX;
965 self.data.swap(self.back as usize, self.front as usize);
966 }
967 }
968
969 /// Rotates all the destaqued elements one place to the left.
970 ///
971 /// `( 1 2 3 4 -- 2 3 4 1 )`
972 /// # Examples
973 /// ```
974 #[doc = "# use devela::Destaque" $IDX:camel ";"]
975 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
976 #[doc = "let mut q = Destaque" $IDX:camel "::<i32, 8>::from([2, 3]);"]
977 /// q.push_front(1)?;
978 /// q.push_back(4)?;
979 /// assert_eq![q.to_array(), Some([1, 2, 3, 4])];
980 /// q.rot_left();
981 /// assert_eq![q.to_array(), Some([2, 3, 4, 1])];
982 /// # Ok(()) }
983 /// ```
984 pub fn rot_left(&mut self) {
985 if !self.is_empty() {
986 // equivalent to: self.push_back(self.pop_front()?)?
987 self.data.swap(self.back as usize, self.front as usize);
988 self.back = (self.back + 1) % CAP as $IDX;
989 self.front = (self.front + 1) % CAP as $IDX;
990 }
991 }
992
993 /// Rotates all the destaqued elements `n` places to the left.
994 ///
995 /// `( 1 2 3 4 -- 4 1 2 3 )` for `nth = 3`
996 /// # Examples
997 /// ```
998 #[doc = "# use devela::Destaque" $IDX:camel ";"]
999 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1000 #[doc = "let mut q = Destaque" $IDX:camel "::<i32, 8>::from([2, 3]);"]
1001 /// q.push_front(1)?;
1002 /// q.push_back(4)?;
1003 /// assert_eq![q.to_array(), Some([1, 2, 3, 4])];
1004 /// q.rot_left_n(3);
1005 /// assert_eq![q.to_array(), Some([4, 1, 2, 3])];
1006 /// # Ok(()) }
1007 /// ```
1008 pub fn rot_left_n(&mut self, nth: $IDX) {
1009 // don't rotate more than necessary
1010 let nth = nth as usize % self.len() as usize;
1011 for _ in 0..nth {
1012 self.data.swap(self.back as usize, self.front as usize);
1013 self.back = (self.back + 1) % CAP as $IDX;
1014 self.front = (self.front + 1) % CAP as $IDX;
1015 }
1016 }
1017 }
1018
1019 // T: Clone, S
1020 impl<T: Clone, const CAP: usize, S: Storage> Destaque<T, CAP, $IDX, S> {
1021 /// Pops the front element.
1022 ///
1023 /// `( 1 2 -- 2 )`
1024 /// # Errors
1025 /// Returns [`NotEnoughElements`] if the destaque is empty.
1026 /// # Examples
1027 /// ```
1028 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1029 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1030 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3]);"]
1031 /// assert_eq![1, q.pop_front()?];
1032 /// assert_eq![2, q.pop_front()?];
1033 /// assert_eq![3, q.pop_front()?];
1034 /// assert![q.is_empty()];
1035 /// # Ok(()) }
1036 /// ```
1037 #[cfg(any(feature = "safe_data", not(feature = "unsafe_ptr")))]
1038 pub fn pop_front(&mut self) -> Result<T, NotEnoughElements> {
1039 if self.is_empty() {
1040 Err(NotEnoughElements(Some(1)))
1041 } else {
1042 let e = self.data[self.front as usize].clone();
1043 self.front = (self.front + 1) % CAP as $IDX;
1044 self.len -= 1;
1045 Ok(e)
1046 }
1047 }
1048 /// Alias of [`pop_front`][Self::pop_front].
1049 ///
1050 /// This is the habitual *dequeue* operation for a single-ended **queue**.
1051 #[cfg(any(feature = "safe_data", not(feature = "unsafe_ptr")))]
1052 pub fn dequeue(&mut self) -> Result<T, NotEnoughElements> {
1053 self.pop_front()
1054 }
1055
1056 /// Pops the back element.
1057 ///
1058 /// `( 1 2 -- 1 )`
1059 /// # Errors
1060 /// Returns [`NotEnoughElements`] if the destaque is empty.
1061 /// # Examples
1062 /// ```
1063 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1064 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1065 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 8>::from([1, 2, 3]);"]
1066 /// assert_eq![3, q.pop_back()?];
1067 /// assert_eq![2, q.pop_back()?];
1068 /// assert_eq![1, q.pop_back()?];
1069 /// assert![q.is_empty()];
1070 /// # Ok(()) }
1071 /// ```
1072 #[cfg(any(feature = "safe_data", not(feature = "unsafe_ptr")))]
1073 // safe-only version that depends on T: Clone
1074 pub fn pop_back(&mut self) -> Result<T, NotEnoughElements> {
1075 if self.is_empty() {
1076 Err(NotEnoughElements(Some(1)))
1077 } else {
1078 self.back = (self.back + CAP as $IDX - 1) % CAP as $IDX;
1079 let e = self.data[self.back as usize].clone();
1080 self.len -= 1;
1081 Ok(e)
1082 }
1083 }
1084
1085 /* make_contiguous, to_vec, to_array */
1086
1087 /// Makes the elements of the destaque contiguous, rearranging the elements
1088 /// so that they are in a single, continuous block starting from the front.
1089 ///
1090 /// This operation might rearrange the internal representation of the elements
1091 /// to ensure they are contiguous. It clones the default element provided during
1092 /// the destaque's construction to fill any gaps if necessary.
1093 ///
1094 /// Returns a mutable slice to the now contiguous elements.
1095 ///
1096 /// # Examples
1097 ///
1098 /// ```
1099 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1100 ///
1101 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 5>::new(0).unwrap();"]
1102 /// q.push_back(1);
1103 /// q.push_back(2);
1104 /// q.push_front(5);
1105 /// assert_eq!(q.as_slices(), (&[5][..], &[1, 2][..]));
1106 ///
1107 /// assert_eq!(q.make_contiguous(0), &[5, 1, 2]);
1108 /// assert_eq!(q.as_slices(), (&[5, 1, 2][..], &[][..]));
1109 /// ```
1110 #[allow(clippy::needless_range_loop)]
1111 pub fn make_contiguous(&mut self, element: T) -> &mut [T] {
1112 // Early return if already contiguous or empty
1113 if self.is_contiguous() || self.len == 0 {
1114 return &mut [];
1115 }
1116
1117 // Create a temporary array filled with clones of the default_element
1118 let mut temp: [T; CAP] = array_from_fn(|_| element.clone());
1119
1120 // IMPROVE: use the new array to construct the new self? BENCH
1121
1122 // Rearrange elements into their correct positions in the temporary array
1123 for i in 0..self.len as usize {
1124 let index = (self.front as usize + i) % CAP;
1125 temp[i] = self.data[index as usize].clone(); // Clone from array to temp
1126 }
1127
1128 // Move elements from temp back into self.data, now in a contiguous order
1129 // self.data[..self.len].copy_from_slice(&temp[..self.len]); // NOTE for Copy
1130 for i in 0..self.len as usize {
1131 self.data[i] = temp[i].clone();
1132 }
1133
1134 // Reset front and back to reflect the new contiguous layout
1135 self.front = 0;
1136 self.back = self.len;
1137
1138 &mut self.data[..self.len as usize]
1139 }
1140
1141 /// Returns the destaqued elements as a vector.
1142 /// # Examples
1143 /// ```
1144 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1145 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1146 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 5>::from([3, 4]);"]
1147 /// q.push_front(2)?;
1148 /// q.push_back(5)?;
1149 /// q.push_front(1)?;
1150 /// assert_eq![q.to_vec(), vec![1, 2, 3, 4, 5]];
1151 /// # Ok(()) }
1152 /// ```
1153 #[cfg(feature = "alloc")]
1154 #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "alloc")))]
1155 pub fn to_vec(&self) -> Vec<T> {
1156 if self.is_empty() {
1157 vec![]
1158 } else {
1159 let mut vec = Vec::with_capacity(self.len() as usize);
1160 let mut index = self.front as usize;
1161
1162 // makes sure a full destaque is not rejected
1163 vec.push(self.data[index].clone());
1164 index = (index + 1) % CAP;
1165
1166 while index != self.back as usize {
1167 vec.push(self.data[index].clone());
1168 index = (index + 1) % CAP;
1169 }
1170 vec
1171 }
1172 }
1173
1174 /// Returns some `LEN` destaqued elements as an array, or `None` if the destaque
1175 /// is empty, or there are not at least `LEN` elements.
1176 ///
1177 /// This is a non `alloc` alternative method to [`to_vec`][Self::to_vec].
1178 /// # Panics
1179 /// Panics if the new `LEN` sized array can't be allocated.
1180 /// # Examples
1181 /// ```
1182 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1183 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1184 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 5>::from([3, 4]);"]
1185 /// q.push_front(2)?;
1186 /// q.push_back(5)?;
1187 /// q.push_front(1)?;
1188 /// assert_eq![q.to_array::<5>(), Some([1, 2, 3, 4, 5])];
1189 /// # Ok(()) }
1190 /// ```
1191 /// # Features
1192 /// Makes use of the `unsafe_array` feature if enabled.
1193 pub fn to_array<const LEN: usize>(&self) -> Option<[T; LEN]> {
1194 // IMPROVE: use array_init
1195 // MAYBE return not option
1196 // TODO: improve from_iter
1197 // Some(Array::<T, LEN, S>::new())
1198
1199 if self.is_empty() || LEN > self.len() as usize || LEN == 0 {
1200 None
1201 } else {
1202 #[cfg(all(not(feature = "safe_data"), feature = "unsafe_array"))]
1203 let arr = {
1204 let mut unarr: [MaybeUninit<T>; LEN] =
1205 // SAFETY: we will initialize all the elements
1206 unsafe { MaybeUninit::uninit().assume_init() };
1207 for (n, i) in unarr.iter_mut().enumerate().take(LEN) {
1208 let index = (self.front as usize + n) % CAP;
1209 let _ = i.write(self.data[index].clone());
1210 }
1211 // SAFETY: we've initialized all the elements
1212 unsafe { transmute_copy::<_, [T; LEN]>(&unarr) }
1213 };
1214
1215 #[cfg(any(feature = "safe_data", not(feature = "unsafe_array")))]
1216 let arr = array_from_fn(|n| {
1217 let index = (self.front as usize + n) % CAP;
1218 self.data[index].clone()
1219 });
1220
1221 Some(arr)
1222 }
1223 }
1224
1225 /* dup */
1226
1227 /// Duplicates the back element at the back
1228 ///
1229 /// `( 1 2 -- 1 2 2 )`
1230 /// # Errors
1231 /// Returns [`NotEnoughElements`] if the destaque is empty
1232 /// or [`NotEnoughSpace`] if it is full.
1233 /// # Examples
1234 /// ```
1235 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1236 /// # fn main() -> devela::Result<(), Box<dyn devela::Error>> {
1237 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 4>::from([1, 2, 3]);"]
1238 /// q.dup_back()?;
1239 /// assert_eq![q.to_array(), Some([1, 2, 3, 3])];
1240 /// # Ok(()) }
1241 /// ```
1242 pub fn dup_back(&mut self) -> Result<(), DataNotEnough> {
1243 if self.is_empty() {
1244 Err(DataNotEnough::Elements(Some(1)))
1245 } else if self.is_full() {
1246 Err(DataNotEnough::Space(Some(1)))
1247 } else {
1248 self.push_back_unchecked(self.peek_back()?.clone());
1249 Ok(())
1250 }
1251 }
1252
1253 /// Duplicates the front element at the front.
1254 ///
1255 /// `( 1 2 -- 1 1 2 )`
1256 /// # Errors
1257 /// Returns [`NotEnoughElements`] if the destaque is empty
1258 /// or [`NotEnoughSpace`] if it is full.
1259 /// # Examples
1260 /// ```
1261 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1262 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1263 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 4>::from([1, 2, 3]);"]
1264 /// q.dup_front()?;
1265 /// assert_eq![q.to_array(), Some([1, 1, 2, 3])];
1266 /// # Ok(()) }
1267 /// ```
1268 pub fn dup_front(&mut self) -> Result<(), DataNotEnough> {
1269 if self.is_empty() {
1270 Err(DataNotEnough::Elements(Some(1)))
1271 } else if self.is_full() {
1272 Err(DataNotEnough::Space(Some(1)))
1273 } else {
1274 self.push_front_unchecked(self.peek_front()?.clone());
1275 Ok(())
1276 }
1277 }
1278
1279 /// Duplicates the back pair of elements, at the back.
1280 ///
1281 /// `( 1 2 3 4 -- 1 2 3 4 3 4)`
1282 /// # Errors
1283 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least 2 elements,
1284 /// or [`NotEnoughSpace`] if it doesn't have space for 2 additional elements.
1285 /// # Examples
1286 /// ```
1287 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1288 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1289 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 6>::from([1, 2, 3, 4]);"]
1290 /// q.dup2_back()?;
1291 /// assert_eq![q.to_array(), Some([1, 2, 3, 4, 3, 4])];
1292 /// # Ok(()) }
1293 /// ```
1294 pub fn dup2_back(&mut self) -> Result<(), DataNotEnough> {
1295 if self.len() < 2 {
1296 Err(DataNotEnough::Elements(Some(2)))
1297 } else if self.remaining_capacity() < 2 {
1298 Err(DataNotEnough::Space(Some(2)))
1299 } else {
1300 let b0 = self.peek_back()?.clone();
1301 let b1 = self.peek_nth_back(1)?.clone();
1302 self.push_back_unchecked(b1);
1303 self.push_back_unchecked(b0);
1304 Ok(())
1305 }
1306 }
1307
1308 /// Duplicates the front pair of elements, at the front.
1309 ///
1310 /// `( 1 2 3 4 -- 1 2 1 2 3 4)`
1311 /// # Errors
1312 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least 2 elements,
1313 /// or [`NotEnoughSpace`] if it doesn't have space for 2 additional elements.
1314 /// # Examples
1315 /// ```
1316 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1317 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1318 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 6>::from([1, 2, 3, 4]);"]
1319 /// q.dup2_front()?;
1320 /// assert_eq![q.to_array(), Some([1, 2, 1, 2, 3, 4])];
1321 /// # Ok(()) }
1322 /// ```
1323 pub fn dup2_front(&mut self) -> Result<(), DataNotEnough> {
1324 if self.len() < 2 {
1325 Err(DataNotEnough::Elements(Some(2)))
1326 } else if self.remaining_capacity() < 2 {
1327 Err(DataNotEnough::Space(Some(2)))
1328 } else {
1329 let f0 = self.peek_front()?.clone();
1330 let f1 = self.peek_nth_front(1)?.clone();
1331 self.push_front_unchecked(f1);
1332 self.push_front_unchecked(f0);
1333 Ok(())
1334 }
1335 }
1336
1337 /* over */
1338
1339 /// Duplicates the second back element, at the back.
1340 ///
1341 /// `( 1 2 3 4 -- 1 2 3 4 3 )`
1342 /// # Errors
1343 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least 2 elements,
1344 /// or [`NotEnoughSpace`] if it is full.
1345 /// # Examples
1346 /// ```
1347 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1348 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1349 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 7>::from([1, 2, 3, 4]);"]
1350 /// q.over_back()?;
1351 /// assert_eq![q.to_array(), Some([1, 2, 3, 4, 3])];
1352 /// # Ok(()) }
1353 /// ```
1354 pub fn over_back(&mut self) -> Result<(), DataNotEnough> {
1355 if self.len() < 2 {
1356 Err(DataNotEnough::Elements(Some(2)))
1357 } else if self.is_full() {
1358 Err(DataNotEnough::Space(Some(1)))
1359 } else {
1360 self.push_back_unchecked(self.peek_nth_back(1)?.clone());
1361 Ok(())
1362 }
1363 }
1364
1365 /// Duplicates the second front element, at the front.
1366 ///
1367 /// `( 1 2 3 4 -- 2 1 2 3 4 )`
1368 /// # Errors
1369 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least 2 elements,
1370 /// or [`NotEnoughSpace`] if it is full.
1371 /// # Examples
1372 /// ```
1373 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1374 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1375 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 7>::from([1, 2, 3, 4]);"]
1376 /// q.over_front()?;
1377 /// assert_eq![q.to_array(), Some([2, 1, 2, 3, 4])];
1378 /// # Ok(()) }
1379 /// ```
1380 pub fn over_front(&mut self) -> Result<(), DataNotEnough> {
1381 if self.len() < 2 {
1382 Err(DataNotEnough::Elements(Some(2)))
1383 } else if self.is_full() {
1384 Err(DataNotEnough::Space(Some(1)))
1385 } else {
1386 self.push_front_unchecked(self.peek_nth_front(1)?.clone());
1387 Ok(())
1388 }
1389 }
1390
1391 /// Duplicates the second back pair of elements, at the back.
1392 ///
1393 /// `( 1 2 3 4 5 6 7 8 -- 1 2 3 4 5 6 7 8 5 6 )`
1394 /// # Errors
1395 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least 4 elements,
1396 /// or [`NotEnoughSpace`] if it doesn't have space for 2 additional elements.
1397 /// # Examples
1398 /// ```
1399 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1400 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1401 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 8>::from([1, 2, 3, 4, 5, 6]);"]
1402 /// q.over2_back()?;
1403 /// assert_eq![q.to_array(), Some([1, 2, 3, 4, 5, 6, 3, 4])];
1404 /// # Ok(()) }
1405 /// ```
1406 pub fn over2_back(&mut self) -> Result<(), DataNotEnough> {
1407 if self.len() < 4 {
1408 Err(DataNotEnough::Elements(Some(4)))
1409 } else if self.remaining_capacity() < 2 {
1410 Err(DataNotEnough::Space(Some(2)))
1411 } else {
1412 let b2 = self.peek_nth_back(2)?.clone();
1413 let b3 = self.peek_nth_back(3)?.clone();
1414 self.push_back_unchecked(b3);
1415 self.push_back_unchecked(b2);
1416 Ok(())
1417 }
1418 }
1419
1420 /// Duplicates the second front pair of elements, at the front.
1421 ///
1422 /// `( 1 2 3 4 5 6 7 8 -- 3 4 1 2 3 4 5 6 7 8 )`
1423 /// # Errors
1424 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least 4 elements,
1425 /// or [`NotEnoughSpace`] if it doesn't have space for 2 additional elements.
1426 /// # Examples
1427 /// ```
1428 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1429 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1430 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 8>::from([1, 2, 3, 4, 5, 6]);"]
1431 /// q.over2_front()?;
1432 /// assert_eq![q.to_array(), Some([3, 4, 1, 2, 3, 4, 5, 6])];
1433 /// # Ok(()) }
1434 /// ```
1435 pub fn over2_front(&mut self) -> Result<(), DataNotEnough> {
1436 if self.len() < 4 {
1437 Err(DataNotEnough::Elements(Some(4)))
1438 } else if self.remaining_capacity() < 2 {
1439 Err(DataNotEnough::Space(Some(2)))
1440 } else {
1441 let f2 = self.peek_nth_front(2)?.clone();
1442 let f3 = self.peek_nth_front(3)?.clone();
1443 self.push_front_unchecked(f3);
1444 self.push_front_unchecked(f2);
1445 Ok(())
1446 }
1447 }
1448
1449 /* tuck */
1450
1451 /// Duplicates the back element, before the second back element.
1452 ///
1453 /// `( 1 2 3 4 -- 1 2 4 3 4 )`
1454 /// # Errors
1455 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least 2 elements,
1456 /// or [`NotEnoughSpace`] if it is full.
1457 /// # Examples
1458 /// ```
1459 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1460 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1461 ///
1462 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 7>::from([1, 2, 3, 4, 5]);"]
1463 /// q.tuck_back()?;
1464 /// assert_eq![q.to_array(), Some([1, 2, 3, 5, 4, 5])];
1465 /// # Ok(()) }
1466 /// ```
1467 pub fn tuck_back(&mut self) -> Result<(), DataNotEnough> {
1468 if self.len() < 2 {
1469 Err(DataNotEnough::Elements(Some(2)))
1470 } else if self.is_full() {
1471 Err(DataNotEnough::Space(Some(1)))
1472 } else {
1473 let b0 = self.peek_back()?.clone();
1474 self.swap_back_unchecked();
1475 self.push_back_unchecked(b0);
1476 Ok(())
1477 }
1478 }
1479
1480 /// Duplicates the front element, after the second front element.
1481 ///
1482 /// `( 1 2 3 4 -- 1 2 1 3 4 )`
1483 /// # Errors
1484 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least 2 elements,
1485 /// or [`NotEnoughSpace`] if it is full.
1486 /// # Examples
1487 /// ```
1488 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1489 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1490 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 7>::from([1, 2, 3, 4, 5]);"]
1491 /// q.tuck_front()?;
1492 /// assert_eq![q.to_array(), Some([1, 2, 1, 3, 4, 5])];
1493 /// # Ok(()) }
1494 /// ```
1495 pub fn tuck_front(&mut self) -> Result<(), DataNotEnough> {
1496 if self.len() < 2 {
1497 Err(DataNotEnough::Elements(Some(2)))
1498 } else if self.is_full() {
1499 Err(DataNotEnough::Space(Some(1)))
1500 } else {
1501 let f0 = self.peek_front()?.clone();
1502 self.swap_front_unchecked();
1503 self.push_front_unchecked(f0);
1504 Ok(())
1505 }
1506 }
1507
1508 /// Duplicates the back pair of elements,
1509 /// before the second back pair of elements.
1510 ///
1511 /// `( 1 2 3 4 5 6 7 8 -- 1 2 3 4 7 8 5 6 7 8 )`
1512 /// # Errors
1513 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least 4 elements,
1514 /// or [`NotEnoughSpace`] if it doesn't have space for 2 additional elements.
1515 /// # Examples
1516 /// ```
1517 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1518 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1519 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 7>::from([1, 2, 3, 4, 5]);"]
1520 /// q.tuck2_back()?;
1521 /// assert_eq![q.to_array(), Some([1, 4, 5, 2, 3, 4, 5])];
1522 /// # Ok(()) }
1523 /// ```
1524 pub fn tuck2_back(&mut self) -> Result<(), DataNotEnough> {
1525 if self.len() < 4 {
1526 Err(DataNotEnough::Elements(Some(4)))
1527 } else if self.len() < 2 {
1528 Err(DataNotEnough::Space(Some(2)))
1529 } else {
1530 let b0 = self.peek_nth_back(0)?.clone();
1531 let b1 = self.peek_nth_back(1)?.clone();
1532 self.swap2_back_unchecked();
1533 self.push_back_unchecked(b1);
1534 self.push_back_unchecked(b0);
1535 Ok(())
1536 }
1537 }
1538
1539 /// Duplicates the front pair of elements,
1540 /// after the second front pair of elements.
1541 ///
1542 /// `( 1 2 3 4 5 6 7 8 -- 1 2 3 4 1 2 5 6 7 8 )`
1543 /// # Errors
1544 /// Returns [`NotEnoughElements`] if the destaque doesn't have at least 4 elements,
1545 /// or [`NotEnoughSpace`] if it doesn't have space for 2 additional elements.
1546 /// # Examples
1547 /// ```
1548 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1549 /// # fn main() -> Result<(), Box<dyn devela::Error>> {
1550 #[doc = "let mut q = Destaque" $IDX:camel "::<u8, 7>::from([1, 2, 3, 4, 5]);"]
1551 /// q.tuck2_front()?;
1552 /// assert_eq![q.to_array(), Some([1, 2, 3, 4, 1, 2, 5])];
1553 /// # Ok(()) }
1554 /// ```
1555 pub fn tuck2_front(&mut self) -> Result<(), DataNotEnough> {
1556 if self.len() < 4 {
1557 Err(DataNotEnough::Elements(Some(4)))
1558 } else if self.len() < 2 {
1559 Err(DataNotEnough::Space(Some(2)))
1560 } else {
1561 let f0 = self.peek_nth_front(0)?.clone();
1562 let f1 = self.peek_nth_front(1)?.clone();
1563 self.swap2_front_unchecked();
1564 self.push_front_unchecked(f1);
1565 self.push_front_unchecked(f0);
1566 Ok(())
1567 }
1568 }
1569 }
1570
1571 /* iterators */
1572
1573 // T, S
1574 impl<T, const CAP: usize, S: Storage> Destaque<T, CAP, $IDX, S> {
1575 /// Returns an iterator.
1576 pub const fn iter(&self) -> DestaqueIter<'_, T, CAP, $IDX, S> {
1577 DestaqueIter {
1578 destaque: self,
1579 idx: 0,
1580 }
1581 }
1582
1583 /* extend */
1584
1585 /// Extends the back of the destaque from an iterator.
1586 ///
1587 /// `( 1 2 -- 1 2 3 4 5 6)` for `[3 4 5 6]`
1588 /// # Errors
1589 /// Returns [`NotEnoughSpace`] if the destaque becomes full before the iterator finishes.
1590 /// # Examples
1591 /// ```
1592 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1593 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 6>::from([1, 2, 3]);"]
1594 /// q.extend_back([4, 5, 6, 7, 8]);
1595 /// assert_eq![q.to_array(), Some([1, 2, 3, 4, 5, 6])];
1596 /// ```
1597 pub fn extend_back<I>(&mut self, iterator: I) -> Result<(), NotEnoughSpace>
1598 where
1599 I: IntoIterator<Item = T>,
1600 {
1601 let mut iter = iterator.into_iter();
1602 while !self.is_full() {
1603 if let Some(e) = iter.next() {
1604 self.push_back_unchecked(e);
1605 } else {
1606 return Ok(());
1607 }
1608 }
1609 Err(NotEnoughSpace(None))
1610 }
1611
1612 /// Extends the back of the destaque from an iterator,
1613 /// overriding elements from the front if the destaque is full.
1614 ///
1615 /// `( 1 2 3 -- 3 4 5 6)` for `[4 5 6]` and `CAP = 4`
1616 /// # Examples
1617 /// ```
1618 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1619 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 4>::from([1, 2, 3]);"]
1620 /// assert_eq![q.extend_back_override([4, 5, 6]), true];
1621 /// assert_eq![q.to_array(), Some([3, 4, 5, 6])];
1622 /// ```
1623 pub fn extend_back_override<I>(&mut self, iterator: I) -> bool
1624 where
1625 I: IntoIterator<Item = T>,
1626 {
1627 let mut overriden = false;
1628 for element in iterator.into_iter() {
1629 if self.is_full() {
1630 overriden = true;
1631 // drop_front
1632 self.front = (self.front + 1) % CAP as $IDX;
1633 self.len -= 1;
1634 }
1635 // push_back
1636 self.data[self.back as usize] = element;
1637 self.back = (self.back + 1) % CAP as $IDX;
1638 self.len += 1;
1639 }
1640 overriden
1641 }
1642
1643 /// Extends the front of the destaque from an iterator.
1644 ///
1645 /// `( 1 2 -- 6 5 4 3 1 2 )` for `[3 4 5 6]`
1646 /// # Errors
1647 /// Returns [`NotEnoughSpace`]
1648 /// if the destaque becomes full before the iterator finishes.
1649 /// # Examples
1650 /// ```
1651 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1652 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 6>::from([1, 2, 3]);"]
1653 /// q.extend_front([4, 5, 6, 7, 8]);
1654 /// assert_eq![q.to_array(), Some([6, 5, 4, 1, 2, 3])];
1655 /// ```
1656 pub fn extend_front<I>(&mut self, iterator: I) -> Result<(), NotEnoughSpace>
1657 where
1658 I: IntoIterator<Item = T>,
1659 {
1660 let mut iter = iterator.into_iter();
1661 while !self.is_full() {
1662 if let Some(e) = iter.next() {
1663 self.push_front_unchecked(e);
1664 } else {
1665 return Ok(());
1666 }
1667 }
1668 Err(NotEnoughSpace(None))
1669 }
1670
1671 /// Extends the front of the destaque from an iterator,
1672 /// overriding elements from the back if the destaque is full.
1673 ///
1674 /// `( 1 2 3 -- 6 5 4 1)` for `[4 5 6]` and `CAP = 4`
1675 /// # Examples
1676 /// ```
1677 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1678 #[doc = "let mut q = Destaque" $IDX:camel "::<_, 4>::from([1, 2, 3]);"]
1679 /// assert_eq![q.extend_front_override([4, 5, 6]), true];
1680 /// assert_eq![q.to_array(), Some([6, 5, 4, 1])];
1681 /// ```
1682 pub fn extend_front_override<I>(&mut self, iterator: I) -> bool
1683 where
1684 I: IntoIterator<Item = T>,
1685 {
1686 let mut overriden = false;
1687 for element in iterator.into_iter() {
1688 if self.is_full() {
1689 overriden = true;
1690 // drop_back
1691 self.back = (self.back + CAP as $IDX - 1) % CAP as $IDX;
1692 self.len -= 1;
1693 }
1694 // push_front
1695 self.front = (self.front + CAP as $IDX - 1) % CAP as $IDX;
1696 self.data[self.front as usize] = element;
1697 self.len += 1;
1698 }
1699 overriden
1700 }
1701
1702 }
1703
1704 // T: PartialEq, S
1705 impl<T: PartialEq, const CAP: usize, S: Storage> Destaque<T, CAP, $IDX, S> {
1706 /// Returns true if the destaque contains `element`.
1707 /// # Examples
1708 /// ```
1709 #[doc = "# use devela::Destaque" $IDX:camel ";"]
1710 #[doc = "let q = Destaque" $IDX:camel "::<_, 6>::from([5, 78, 42, 33, 9]);"]
1711 ///
1712 /// assert![q.contains(&9)];
1713 /// assert![!q.contains(&8)];
1714 /// ```
1715 pub fn contains(&self, element: &T) -> bool {
1716 self.iter().any(|n| n == element)
1717 }
1718 }
1719
1720 // TODO: drop_replace_default
1721
1722 /* private helpers */
1723
1724 // T, S
1725 impl<T, const CAP: usize, S: Storage> Destaque<T, CAP, $IDX, S> {
1726 // Returns the `nth` element's index counting from the back.
1727 #[must_use]
1728 pub(crate) const fn idx_back(&self, nth: $IDX) -> usize {
1729 (self.back as usize + CAP - nth as usize - 1) % CAP
1730 }
1731 // Returns the `nth` element's index counting from the front.
1732 #[must_use]
1733 pub(crate) const fn idx_front(&self, nth: $IDX) -> usize {
1734 (self.front as usize + nth as usize) % CAP
1735 }
1736 }
1737 }};
1738}
1739impl_destaque!();