devela/data/list/queue/
adt.rs

Help
1// devela::data::list::queue::adt
2//
3//! Defines the [`DataQueue`] & [`DataDeque`] abstract data types.
4//
5// TOC
6// - define traits DataQueue, DataDeque
7// - impl for:
8//   - VecDeque
9
10use crate::{DataCollection, NotEnoughElements, NotEnoughSpace};
11
12#[doc = crate::TAG_DATA_STRUCTURE!()]
13/// An abstract *queue* data type.
14pub trait DataQueue: DataCollection {
15    /// Remove an element from the (front of the) queue.
16    /// # Errors
17    /// Returns [`NotEnoughElements`] if there are not enough elements in the queue.
18    fn queue_pop(&mut self) -> Result<<Self as DataCollection>::Element, NotEnoughElements>;
19    /// Add an element to the (back of the) queue.
20    /// # Errors
21    /// Returns [`NotEnoughSpace`] if there is not enough free space in the queue.
22    fn queue_push(
23        &mut self,
24        element: <Self as DataCollection>::Element,
25    ) -> Result<(), NotEnoughSpace>;
26}
27
28#[doc = crate::TAG_DATA_STRUCTURE!()]
29/// An abstract *double-ended queue* data type.
30pub trait DataDeque: DataQueue {
31    /// Remove an element from the back of the queue.
32    /// # Errors
33    /// Returns [`NotEnoughElements`] if there are not enough elements in the queue.
34    fn queue_pop_back(&mut self) -> Result<<Self as DataCollection>::Element, NotEnoughElements>;
35    /// Add an element to the front of the queue.
36    /// # Errors
37    /// Returns [`NotEnoughSpace`] if there is not enough free space in the queue.
38    fn queue_push_front(
39        &mut self,
40        element: <Self as DataCollection>::Element,
41    ) -> Result<(), NotEnoughSpace>;
42
43    /// Remove an element from the front of the queue (calls [`queue_pop`][DataQueue::queue_pop]).
44    /// # Errors
45    /// Returns [`NotEnoughElements`] if there are not enough elements in the queue.
46    fn queue_pop_front(&mut self) -> Result<<Self as DataCollection>::Element, NotEnoughElements> {
47        self.queue_pop()
48    }
49    /// Remove an element from the back of the queue (calls [`queue_push`][DataQueue::queue_push]).
50    /// # Errors
51    /// Returns [`NotEnoughSpace`] if there is not enough free space in the queue.
52    fn queue_push_back(
53        &mut self,
54        element: <Self as DataCollection>::Element,
55    ) -> Result<(), NotEnoughSpace> {
56        self.queue_push(element)
57    }
58}
59
60/* impls */
61
62#[cfg(feature = "alloc")]
63impl<T> DataQueue for crate::VecDeque<T> {
64    fn queue_pop(&mut self) -> Result<<Self as DataCollection>::Element, NotEnoughElements> {
65        self.pop_front().ok_or(NotEnoughElements(Some(1)))
66    }
67    fn queue_push(
68        &mut self,
69        element: <Self as DataCollection>::Element,
70    ) -> Result<(), NotEnoughSpace> {
71        self.push_back(element);
72        Ok(())
73    }
74}
75#[cfg(feature = "alloc")]
76impl<T> DataDeque for crate::VecDeque<T> {
77    fn queue_pop_back(&mut self) -> Result<<Self as DataCollection>::Element, NotEnoughElements> {
78        self.pop_back().ok_or(NotEnoughElements(Some(1)))
79    }
80    fn queue_push_front(
81        &mut self,
82        element: <Self as DataCollection>::Element,
83    ) -> Result<(), NotEnoughSpace> {
84        self.push_front(element);
85        Ok(())
86    }
87}
devela/data/list/queue/adt.rs

devela/data/list/queue/
adt.rs
