---

yaml
---
r: 132030
b: refs/heads/dist-snap
c: c86873b
h: refs/heads/master
v: v3

Author: treeman

[refs]

@@ -6,7 +6,7 @@ refs/heads/try: 457a3c991d79b971be07fce75f9d0c12848fb37c
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: 147ecfdd8221e4a4d4e090486829a06da1e0ca3c
-refs/heads/dist-snap: ec70f2bb6e8cd3dd187abba351e6cf9eb14a37c1
+refs/heads/dist-snap: c86873bda4d0d32a595dbaf24745c1f7cd9b89da
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503
 refs/heads/try3: 9387340aab40a73e8424c48fd42f0c521a4875c0

branches/dist-snap/src/libcollections/lib.rs

@@ -327,33 +327,196 @@ pub trait MutableSet<T>: Set<T> + Mutable {
 
 /// A double-ended sequence that allows querying, insertion and deletion at both
 /// ends.
+///
+/// # Example
+///
+/// With a `Deque` we can simulate a stack:
+///
+/// ```
+/// use std::collections::{RingBuf, Deque};
+///
+/// let mut stack = RingBuf::new();
+/// stack.push_front(1i);
+/// stack.push_front(2i);
+/// stack.push_front(3i);
+///
+/// // Will print 3, 2, 1
+/// while !stack.is_empty() {
+///     let x = stack.pop_front().unwrap();
+///     println!("{}", x);
+/// }
+/// ```
+///
+/// We can simulate a queue:
+///
+/// ```
+/// use std::collections::{RingBuf, Deque};
+///
+/// let mut queue = RingBuf::new();
+/// queue.push_back(1i);
+/// queue.push_back(2i);
+/// queue.push_back(3i);
+///
+/// // Will print 1, 2, 3
+/// while !queue.is_empty() {
+///     let x = queue.pop_front().unwrap();
+///     println!("{}", x);
+/// }
+/// ```
+///
+/// And of course we can mix and match:
+///
+/// ```
+/// use std::collections::{DList, Deque};
+///
+/// let mut deque = DList::new();
+///
+/// // Init deque with 1, 2, 3, 4
+/// deque.push_front(2i);
+/// deque.push_front(1i);
+/// deque.push_back(3i);
+/// deque.push_back(4i);
+///
+/// // Will print (1, 4) and (2, 3)
+/// while !deque.is_empty() {
+///     let f = deque.pop_front().unwrap();
+///     let b = deque.pop_back().unwrap();
+///     println!("{}", (f, b));
+/// }
+/// ```
 pub trait Deque<T> : Mutable {
-    /// Provide a reference to the front element, or None if the sequence is
-    /// empty
+    /// Provide a reference to the front element, or `None` if the sequence is.
+    /// empty.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::{RingBuf, Deque};
+    ///
+    /// let mut d = RingBuf::new();
+    /// assert_eq!(d.front(), None);
+    ///
+    /// d.push_back(1i);
+    /// d.push_back(2i);
+    /// assert_eq!(d.front(), Some(&1i));
+    /// ```
     fn front<'a>(&'a self) -> Option<&'a T>;
 
-    /// Provide a mutable reference to the front element, or None if the
-    /// sequence is empty
+    /// Provide a mutable reference to the front element, or `None` if the
+    /// sequence is empty.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::{RingBuf, Deque};
+    ///
+    /// let mut d = RingBuf::new();
+    /// assert_eq!(d.front_mut(), None);
+    ///
+    /// d.push_back(1i);
+    /// d.push_back(2i);
+    /// match d.front_mut() {
+    ///     Some(x) => *x = 9i,
+    ///     None => (),
+    /// }
+    /// assert_eq!(d.front(), Some(&9i));
+    /// ```
     fn front_mut<'a>(&'a mut self) -> Option<&'a mut T>;
 
     /// Provide a reference to the back element, or None if the sequence is
-    /// empty
+    /// empty.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::{DList, Deque};
+    ///
+    /// let mut d = DList::new();
+    /// assert_eq!(d.back(), None);
+    ///
+    /// d.push_back(1i);
+    /// d.push_back(2i);
+    /// assert_eq!(d.back(), Some(&2i));
+    /// ```
     fn back<'a>(&'a self) -> Option<&'a T>;
 
     /// Provide a mutable reference to the back element, or None if the sequence
-    /// is empty
+    /// is empty.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::{DList, Deque};
+    ///
+    /// let mut d = DList::new();
+    /// assert_eq!(d.back(), None);
+    ///
+    /// d.push_back(1i);
+    /// d.push_back(2i);
+    /// match d.back_mut() {
+    ///     Some(x) => *x = 9i,
+    ///     None => (),
+    /// }
+    /// assert_eq!(d.back(), Some(&9i));
+    /// ```
     fn back_mut<'a>(&'a mut self) -> Option<&'a mut T>;
 
-    /// Insert an element first in the sequence
+    /// Insert an element first in the sequence.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::{DList, Deque};
+    ///
+    /// let mut d = DList::new();
+    /// d.push_front(1i);
+    /// d.push_front(2i);
+    /// assert_eq!(d.front(), Some(&2i));
     fn push_front(&mut self, elt: T);
 
-    /// Insert an element last in the sequence
+    /// Insert an element last in the sequence.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::{DList, Deque};
+    ///
+    /// let mut d = DList::new();
+    /// d.push_back(1i);
+    /// d.push_back(2i);
+    /// assert_eq!(d.front(), Some(&1i));
     fn push_back(&mut self, elt: T);
 
-    /// Remove the last element and return it, or None if the sequence is empty
+    /// Remove the last element and return it, or None if the sequence is empty.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::{RingBuf, Deque};
+    ///
+    /// let mut d = RingBuf::new();
+    /// d.push_back(1i);
+    /// d.push_back(2i);
+    ///
+    /// assert_eq!(d.pop_back(), Some(2i));
+    /// assert_eq!(d.pop_back(), Some(1i));
+    /// assert_eq!(d.pop_back(), None);
     fn pop_back(&mut self) -> Option<T>;
 
-    /// Remove the first element and return it, or None if the sequence is empty
+    /// Remove the first element and return it, or None if the sequence is empty.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::collections::{RingBuf, Deque};
+    ///
+    /// let mut d = RingBuf::new();
+    /// d.push_back(1i);
+    /// d.push_back(2i);
+    ///
+    /// assert_eq!(d.pop_front(), Some(1i));
+    /// assert_eq!(d.pop_front(), Some(2i));
+    /// assert_eq!(d.pop_front(), None);
     fn pop_front(&mut self) -> Option<T>;
 }