burritos/src/utility/list.rs

/// Data structure and definition of a genericsingle-linked LIFO list.
/// 
/// This is a 
#[derive(PartialEq)]
pub struct List<T: PartialEq> {
    head: Link<T>,
}


type Link<T> = Option<Box<Node<T>>>;

#[derive(PartialEq)]
struct Node<T> {
    elem: T,
    next: Link<T>,
}

impl<T: PartialEq> List<T> {

    /// Create an empty list
    pub fn new() -> Self {
        List { head: None }
    }

    /// Push an item at the end of the list
    pub fn push(&mut self, elem: T) {
        let new_node = Box::new(Node {
            elem: elem,
            next: self.head.take(),
        });

        self.head = Some(new_node);
    }

    /// Retrieve and remove the item at the end of the list.
    /// 
    /// Return None if list is empty
    pub fn pop(&mut self) -> Option<T> {
        self.head.take().map(|node| {
            self.head = node.next;
            node.elem
        })
    }

    /// Retrieve without removing the item at the end of the list
    /// 
    /// Return None if list is empty
    pub fn peek(&self) -> Option<&T> {
        self.head.as_ref().map(|node| {
            &node.elem
        })
    }

    /// Retrieve without removing the item at the end of the list as mutable
    /// 
    /// Return None if lsit is empty
    pub fn peek_mut(&mut self) -> Option<&mut T> {
        self.head.as_mut().map(|node| {
            &mut node.elem
        })
    }

    /// Search for an element in the list
    /// 
    /// Return **bool** true if the list contains the element, false otherwise
    /// 
    /// Worst case complexity of this function is O(n)
    pub fn contains(&self, elem: &T) -> bool {
        let mut iter = self.iter();
        let element = iter.next();
        while element.is_some() {
            if element.unwrap() == elem {
                return true;
            }
        }
        false
    }

    /// Remove the item from the list
    /// 
    /// Return true if the item has been found, otherwise return false
    /// 
    /// Worst-case complexity is O(n)
    pub fn remove(&mut self, item: T)-> bool {
        let mut found = false;
        let mut tmp_list: List<T> = List::new();
        while !self.is_empty() {
            let current = self.pop().unwrap();
            if current != item {
                tmp_list.push(current);
            } else {
                found = true;
                break;
            }
        }
        while !tmp_list.is_empty() {
            self.push(tmp_list.pop().unwrap());
        }
        found
    }

    /// Return true if the list is empty, false otherwise
    pub fn is_empty(&self) -> bool {
        self.head.is_none()
    }

    /// Turn the list into an iterator for use in a for loop per example.
    /// 
    /// When you iter using into_iter, elements are remove from the list
    pub fn into_iter(self) -> IntoIter<T> {
        IntoIter(self)
    }

    /// Turn the list into an iterator for use in a for loop
    /// 
    /// When you iter using this method, elements are dereferenced
    pub fn iter(&self) -> Iter<'_, T> {
        Iter { next: self.head.as_deref() }
    }

    /// Same as iter but make the iterator mutable
    pub fn iter_mut(&mut self) -> IterMut<'_, T> {
        IterMut { next: self.head.as_deref_mut() }
    }
}

impl<T: PartialEq> Drop for List<T> {
    fn drop(&mut self) {
        let mut cur_link = self.head.take();
        while let Some(mut boxed_node) = cur_link {
            cur_link = boxed_node.next.take();
        }
    }
}

/// Iterator structure for use in a for loop, pop elements before returning it
pub struct IntoIter<T: PartialEq>(List<T>);

impl<T: PartialEq> Iterator for IntoIter<T> {
    type Item = T;
    fn next(&mut self) -> Option<Self::Item> {
        // access fields of a tuple struct numerically
        self.0.pop()
    }
}

/// Iterator structure for use in a for loop, dereference before returning it 
pub struct Iter<'a, T> {
    next: Option<&'a Node<T>>,
}

impl<'a, T> Iterator for Iter<'a, T> {
    type Item = &'a T;
    fn next(&mut self) -> Option<Self::Item> {
        self.next.map(|node| {
            self.next = node.next.as_deref();
            &node.elem
        })
    }
}

/// Same as Iter structure, returned item are mutable
pub struct IterMut<'a, T> {
    next: Option<&'a mut Node<T>>,
}

impl<'a, T> Iterator for IterMut<'a, T> {
    type Item = &'a mut T;

    fn next(&mut self) -> Option<Self::Item> {
        self.next.take().map(|node| {
            self.next = node.next.as_deref_mut();
            &mut node.elem
        })
    }
}

#[cfg(test)]
mod test {
    use super::List;

    #[test]
    fn basics() {
        let mut list = List::new();

        // Check empty list behaves right
        assert_eq!(list.pop(), None);

        // Populate list
        list.push(1);
        list.push(2);
        list.push(3);

        // Check normal removal
        assert_eq!(list.pop(), Some(3));
        assert_eq!(list.pop(), Some(2));

        // Push some more just to make sure nothing's corrupted
        list.push(4);
        list.push(5);

        // Check normal removal
        assert_eq!(list.pop(), Some(5));
        assert_eq!(list.pop(), Some(4));

        // Check exhaustion
        assert_eq!(list.pop(), Some(1));
        assert_eq!(list.pop(), None);
    }

    #[test]
    fn peek() {
        let mut list = List::new();
        assert_eq!(list.peek(), None);
        assert_eq!(list.peek_mut(), None);
        list.push(1); list.push(2); list.push(3);

        assert_eq!(list.peek(), Some(&3));
        assert_eq!(list.peek_mut(), Some(&mut 3));

        list.peek_mut().map(|value| {
            *value = 42
        });

        assert_eq!(list.peek(), Some(&42));
        assert_eq!(list.pop(), Some(42));
    }

    #[test]
    fn into_iter() {
        let mut list = List::new();
        list.push(1); list.push(2); list.push(3);

        let mut iter = list.into_iter();
        assert_eq!(iter.next(), Some(3));
        assert_eq!(iter.next(), Some(2));
        assert_eq!(iter.next(), Some(1));
        assert_eq!(iter.next(), None);
    }

    #[test]
    fn iter() {
        let mut list = List::new();
        list.push(1); list.push(2); list.push(3);

        let mut iter = list.iter();
        assert_eq!(iter.next(), Some(&3));
        assert_eq!(iter.next(), Some(&2));
        assert_eq!(iter.next(), Some(&1));
    }

    #[test]
    fn iter_mut() {
        let mut list = List::new();
        list.push(1); list.push(2); list.push(3);

        let mut iter = list.iter_mut();
        assert_eq!(iter.next(), Some(&mut 3));
        assert_eq!(iter.next(), Some(&mut 2));
        assert_eq!(iter.next(), Some(&mut 1));
    }
}