devela/data/list/queue/destaque/
definitions.rs

Help
1// devela::data::list::queue::destaque::definitions
2//
3//! Double-ended queues are linear lists for which any accesses are made from
4//! either end.
5//
6
7use crate::{Array, Bare, Storage};
8// #[cfg(feature = "dep_rkyv")] // DEP_DISABLED
9// use rkyv::{Archive, Deserialize, Serialize};
10
11/* types */
12
13#[doc = crate::TAG_DATA_STRUCTURE!()]
14/// A static double-ended queue and stack backed by an [`Array`].
15///
16/// It is generic in respect to its
17/// elements (`T`),
18/// capacity (`CAP`),
19/// index size (`IDX`)
20/// and storage (`S`).
21///
22/// The index size will upper-bound the capacity to the maximum for that type,
23/// e.g. `u8::MAX` for [`DestaqueU8`].
24///
25/// The index size determines the maximum possible number of elements in the destaque,
26/// thereby upper-bounding the capacity to the maximum value representable by the
27/// index type. For example, `u8::MAX` for [`DestaqueU8`].
28///
29/// The total size in bytes of the stack may be influenced by the chosen index
30/// size, depending on the size and alignment of the elements. This difference
31/// could only be significant for small capacities, as only one index is stored.
32///
33/// See also the related aliases that specify `IDX`:
34#[cfg_attr(not(feature = "_destaque_all"), allow(rustdoc::broken_intra_doc_links))]
35/// [`DestaqueU8`], [`DestaqueU16`], [`DestaqueU32`], [`DestaqueUsize`],
36/// and the related traits:
37/// [`DataQueue`][crate::DataQueue], [`DataDeque`][crate::DataDeque],
38/// [`DataStack`][crate::DataStack], [`DataDesta`][crate::DataDesta].<br/>
39///
40/// ## Methods
41///
42/// It implements methods that operate from both the front and the back.
43/// Rememeber that a single-ended *stack* operates only from the back, while a
44/// single-ended *queue* pushes to the back and pops from the front.
45///
46/// - General methods:
47///   - [`new`][Self::new],
48/// [`len`][Self::len], [`is_empty`][Self::is_empty], [`is_full`][Self::is_full],
49/// [`clear`][Self::clear], [`contains`][Self::contains],
50/// [`capacity`][Self::capacity], [`remaining_capacity`][Self::remaining_capacity].
51///   - [`iter`][Self::iter],
52/// [`extend_back`][Self::extend_back], [`extend_front`][Self::extend_front],
53/// [`from_array`][Self::from_array]*([`copy`][Self::from_array_copy])*,
54/// [`to_array`][Self::to_array],
55/// [`to_vec`][Self::to_vec].
56///
57/// - Queue and stack methods:
58///   - push:
59/// [`push_back`][Self::push_back]*([uc][Self::push_back_unchecked])*
60///   **=** [`enqueue`][Self::enqueue],
61/// [`push_front`][Self::push_front]*([uc][Self::push_front_unchecked])*.
62///   - pop:
63/// [`pop_front`][Self::pop_front]
64///   **=** [`dequeue`][Self::dequeue],
65/// [`pop_back`][Self::pop_back].
66///   - peek:
67/// [`peek_back`][Self::peek_back]*([mut][Self::peek_back_mut])*
68/// [`peek_nth_back`][Self::peek_nth_back]*([mut][Self::peek_nth_back_mut])*,
69/// [`peek_front`][Self::peek_front]*([mut][Self::peek_front_mut])*,
70/// [`peek_nth_front`][Self::peek_nth_front]*([mut][Self::peek_nth_front_mut])*.
71///   - drop:
72/// [`drop_back`][Self::drop_back],
73/// [`drop_front`][Self::drop_front],
74/// [`drop_n_back`][Self::drop_n_back],
75/// [`drop_n_front`][Self::drop_n_front].
76///   - swap:
77/// [`swap_back`][Self::swap_back]*([uc][Self::swap_back_unchecked])*,
78/// [`swap_front`][Self::swap_front]*([uc][Self::swap_front_unchecked])*,
79/// [`swap2_back`][Self::swap2_back]*([uc][Self::swap2_back_unchecked])*,
80/// [`swap2_front`][Self::swap2_front]*([uc][Self::swap2_front_unchecked])*,
81/// [`swap_ends`][Self::swap_ends], [`swap2_ends`][Self::swap2_ends].
82///   - rot:
83/// [`rot_right`][Self::rot_right],
84/// [`rot_right_n`][Self::rot_right_n],
85/// [`rot_left`][Self::rot_left],
86/// [`rot_left_n`][Self::rot_left_n].
87///   - dup:
88/// [`dup_back`][Self::dup_back],
89/// [`dup_front`][Self::dup_front],
90/// [`dup2_back`][Self::dup2_back],
91/// [`dup2_front`][Self::dup2_front].
92///   - over:
93/// [`over_back`][Self::over_back],
94/// [`over_front`][Self::over_front],
95/// [`over2_back`][Self::over2_back],
96/// [`over2_front`][Self::over2_front].
97///   - tuck:
98/// [`tuck_back`][Self::tuck_back],
99/// [`tuck_front`][Self::tuck_front],
100/// [`tuck2_back`][Self::tuck2_back],
101/// [`tuck2_front`][Self::tuck2_front].
102// #[cfg_attr(feature = "dep_rkyv", derive(Archive, Serialize, Deserialize))]
103pub struct Destaque<T, const CAP: usize, IDX, S: Storage = Bare> {
104    pub(super) data: Array<T, CAP, S>,
105    pub(super) len: IDX,
106    pub(super) front: IDX,
107    pub(super) back: IDX,
108}
109
110#[doc = crate::TAG_DATA_STRUCTURE!()]
111/// A [`Destaque`] with an 8-bit index size.
112#[cfg(feature = "_destaque_u8")]
113#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "_destaque_u8")))]
114pub type DestaqueU8<T, const CAP: usize, S = Bare> = Destaque<T, CAP, u8, S>;
115
116#[doc = crate::TAG_DATA_STRUCTURE!()]
117/// A [`Destaque`] with a 16-bit index size.
118#[cfg(feature = "_destaque_u16")]
119#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "_destaque_u16")))]
120pub type DestaqueU16<T, const CAP: usize, S = Bare> = Destaque<T, CAP, u16, S>;
121
122#[doc = crate::TAG_DATA_STRUCTURE!()]
123/// A [`Destaque`] with a 32-bit index size.
124#[cfg(feature = "_destaque_u32")]
125#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "_destaque_u32")))]
126pub type DestaqueU32<T, const CAP: usize, S = Bare> = Destaque<T, CAP, u32, S>;
127
128#[doc = crate::TAG_DATA_STRUCTURE!()]
129/// A [`Destaque`] with a pointer-sized index size.
130#[cfg(feature = "_destaque_usize")]
131#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "_destaque_usize")))]
132pub type DestaqueUsize<T, const CAP: usize, S = Bare> = Destaque<T, CAP, usize, S>;
133
134/* iterators */
135
136#[doc = crate::TAG_ITERATOR!()]
137/// An iterator over [`Destaque`] elements.
138pub struct DestaqueIter<'s, T, const CAP: usize, IDX, S: Storage = Bare> {
139    pub(super) destaque: &'s Destaque<T, CAP, IDX, S>,
140    pub(super) idx: usize,
141}
devela/data/list/queue/destaque/definitions.rs

devela/data/list/queue/destaque/
definitions.rs
