scorpius 0.4.0

use std::collections::VecDeque;

/// Queue data structure
pub struct Queue<T> {
    data: VecDeque<T>,
}

impl<T> Queue<T> {
    /// Creates an empty queue
    /// # Examples
    /// ```
    /// use scorpius::data_structure::queue::Queue;
    /// let queue: Queue<i32> = Queue::new();
    /// ```
    pub fn new() -> Self {
        Queue {
            data: VecDeque::new(),
        }
    }

    /// Enqueue an item to the queue
    /// The function has a time complexity of O(1)
    ///
    /// # Arguments
    /// * `item` - The value to push
    /// # Example
    /// ```
    /// use scorpius::data_structure::queue::Queue;
    /// let mut queue = Queue::new();
    /// queue.enqueue(1);
    /// assert_eq!(queue.peek(), Some(&1));
    /// ```
    pub fn enqueue(&mut self, item: T) {
        self.data.push_back(item);
    }

    /// Dequeue an item from the queue
    /// The function has a time complexity of O(1)
    ///
    /// # Returns
    /// * `Option<T>` - The value popped off the queue
    /// # Example
    /// ```
    /// use scorpius::data_structure::queue::Queue;
    /// let mut queue = Queue::new();
    /// queue.enqueue(1);
    /// assert_eq!(queue.dequeue(), Some(1));
    /// assert_eq!(queue.dequeue(), None);
    /// ```
    pub fn dequeue(&mut self) -> Option<T> {
        self.data.pop_front()
    }

    /// Get the size of the queue
    /// The function has a time complexity of O(1)
    /// # Returns
    /// * `usize` - The size of the queue
    /// # Example
    /// ```
    /// use scorpius::data_structure::queue::Queue;
    /// let mut queue = Queue::new();
    /// queue.enqueue(1);
    /// queue.enqueue(2);
    /// assert_eq!(queue.size(), 2);
    /// ```
    pub fn size(&self) -> usize {
        self.data.len()
    }

    /// Get the first item in the queue
    /// The function has a time complexity of O(1)
    ///
    /// # Returns
    /// * `Option<&T>` - The value at the top of the queue
    /// # Example
    /// ```
    /// use scorpius::data_structure::queue::Queue;
    /// let mut queue = Queue::new();
    /// queue.enqueue(1);
    /// assert_eq!(queue.peek(), Some(&1));
    /// ```
    pub fn peek(&self) -> Option<&T> {
        self.data.front()
    }
}

/// Provide default implementation
/// # Examples
/// ```
/// use scorpius::data_structure::queue::Queue;
/// let queue: Queue<i32> = Queue::default();
/// assert_eq!(queue.peek(), None);
/// ```
impl<T> Default for Queue<T> {
    fn default() -> Self {
        Self::new()
    }
}

/// A queue that can be iterated over
/// Iteration is in FIFO order and has a time complexity of O(n)
///
/// # Example (iterating over a queue using for loop)
/// ```
/// use scorpius::data_structure::queue::Queue;
/// let mut queue = Queue::new();
/// queue.enqueue(1);
/// queue.enqueue(2);
/// queue.enqueue(3);
/// let mut i = 1;
/// for item in queue {
///    println!("{}", item);
///    assert_eq!(item, i);
///    i += 1;
/// }
/// ```
///
/// # Example (iterating over a queue using into_iter())
/// ```
/// use scorpius::data_structure::queue::Queue;
/// let mut queue = Queue::new();
/// queue.enqueue(1);
/// queue.enqueue(2);
/// queue.enqueue(3);
/// let mut i = 1;
/// for item in queue.into_iter() {
///   println!("{}", item);
///   assert_eq!(item, i);
///   i += 1;
/// }
/// ```
impl <T> Iterator for Queue<T> {
    type Item = T;

    fn next(&mut self) -> Option<Self::Item> {
        self.dequeue()
    }
}

// tests
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn create_queue() {
        let queue: Queue<i32> = Queue::new();
        assert_eq!(queue.data.len(), 0);
    }

    #[test]
    fn enqueue_to_queue() {
        let mut queue = Queue::new();
        queue.enqueue(1);
        assert_eq!(queue.data.len(), 1);
    }

    #[test]
    fn dequeue_from_queue() {
        let mut queue = Queue::new();
        queue.enqueue(1);
        queue.enqueue(2);
        assert_eq!(queue.data.len(), 2);
        assert_eq!(queue.dequeue(), Some(1));
        assert_eq!(queue.dequeue(), Some(2));
        assert_eq!(queue.dequeue(), None);
        assert_eq!(queue.dequeue(), None);
    }

    #[test]
    fn peek_from_queue() {
        let mut queue = Queue::new();
        queue.enqueue(1);
        queue.enqueue(2);
        assert_eq!(queue.data.len(), 2);
        assert_eq!(queue.peek(), Some(&1));
    }

    #[test]
    fn iterate_queue() {
        let mut queue = Queue::new();
        queue.enqueue(1);
        queue.enqueue(2);
        queue.enqueue(3);
        let mut iter = queue.into_iter();
        assert_eq!(iter.next(), Some(1));
        assert_eq!(iter.next(), Some(2));
        assert_eq!(iter.next(), Some(3));
        assert_eq!(iter.next(), None);
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn get_queue_size_when_has_items() {
        let mut queue = Queue::new();
        queue.enqueue(1);
        queue.enqueue(2);
        queue.enqueue(3);
        assert_eq!(queue.size(), 3);
    }

    #[test]
    fn get_queue_size_when_is_empty() {
        let queue: Queue<i32> = Queue::new();
        assert_eq!(queue.size(), 0);
    }
}