agenda 0.0.1

Safe collections that can be mutated while being iterated through
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

//! Convenient collection that allows safe mutation during iteration
//!
//! `Agenda` offers queue-like functionality but has interior mutability to
//! permit pushing and popping inside a for-loop.
//!
//! ```rust
//! use agenda::Queue;
//!
//! fn iter(queue: Queue<String>) {
//!     for item in queue.iter() {
//!         match item.as_str() {
//!             "three" => queue.push(String::from("two")),
//!             "two" => queue.push(String::from("one")),
//!             "one" => queue.push(String::from("zero")),
//!             _ => {},
//!         }
//!     }
//! }
//!
//! ```
//!

use std::cell::RefCell;
use std::iter::FromIterator;
use std::collections::VecDeque;

#[cfg(test)] mod test;


/// A queue which can be modified while being iterated through.
///
/// A `Queue` uses a `VecDeque` under the hood, which means quick operations,
/// cache locality, and amortized allocations.
///
/// `push`ing an element adds it to the end of the queue, and `pop`ping removes
/// it from the front. To iterate through the most recently `push`ed elements
/// first, iterate through elements in `queue.iter().rev()`.
#[derive(Debug, Default)]
pub struct Queue<T>(RefCell<VecDeque<T>>);

impl<T> Queue<T> {
    /// Construct an empty with the default `VecDeque` capacity (currently 7)
    pub fn new() -> Queue<T> {
        Queue(RefCell::new(VecDeque::new()))
    }

    /// Specify the initial capacity
    pub fn with_capacity(n: usize) -> Queue<T> {
        Queue(RefCell::new(VecDeque::with_capacity(n)))
    }

    /// Append an element to the end of the queue. 
    pub fn push(&self, new: T) {
        let mut inner = self.0.borrow_mut();
        inner.push_back(new);
    }

    /// Pop the first element of the queue or return `None` if it's empty
    pub fn pop(&self) -> Option<T> {
        let mut inner = self.0.borrow_mut();
        inner.pop_front()
    }

    /// Pop the last element of the queue or return `None` if it's empty
    pub fn pop_back(&self) -> Option<T> {
        let mut inner = self.0.borrow_mut();
        inner.pop_back()
    }

    /// Iterate through the queue. 
    /// `for i in queue.iter()` is the same as `for i in &queue`
    pub fn iter(&self) -> &Self {
        self
    }
}

/// For ownership reasons, `Iterator` is implemented over `&Queue`.
impl<'a, T> Iterator for &'a Queue<T> {
    type Item = T;
    fn next(&mut self) -> Option<T> { self.pop() }
}

impl<'a, T> DoubleEndedIterator for &'a Queue<T> {
    fn next_back(&mut self) -> Option<T> {
        self.pop_back()
    }
}

impl<'a, T> ExactSizeIterator for &'a Queue<T> {
    fn len(&self) -> usize {
        self.0.borrow().len()
    }
}

impl<'a, T> Extend<T> for &'a Queue<T> {
    fn extend<S: IntoIterator<Item=T>>(&mut self, iter: S) {
        let mut inner = self.0.borrow_mut();
        inner.extend(iter);
    }
}

impl<'a, T> FromIterator<T> for Queue<T> {
    fn from_iter<S: IntoIterator<Item=T>>(iter: S) -> Queue<T> {
        let vd = VecDeque::from_iter(iter);
        Queue(RefCell::new(vd))
    }
}