Skip to content

Commit

Permalink
Polish bitv docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@treeman @alexcrichton
treeman authored and alexcrichton committed Jul 21, 2014
1 parent 71afdc4 commit e68333a
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 56 deletions.
83 changes: 44 additions & 39 deletions src/libcollections/bitv.rs
View file
Expand Up @@ -25,6 +25,8 @@
//!
//! // Store the primes as a BitvSet
//! let primes = {
//! // Assume all numbers are prime to begin, and then we
//! // cross off non-primes progressively
//! let mut bv = Bitv::with_capacity(max_prime, true);
//!
//! // Neither 0 nor 1 are prime
Expand All @@ -33,8 +35,8 @@
//!
//! for i in range(2, max_prime) {
//! // if i is a prime
//! if bv.get(i) {
//! // mark all multiples of i as non-prime (any multiples below i * i
//! if bv[i] {
//! // Mark all multiples of i as non-prime (any multiples below i * i
//! // will have been marked as non-prime previously)
//! for j in iter::range_step(i * i, max_prime, i) { bv.set(j, false) }
//! }
Expand Down Expand Up @@ -252,6 +254,9 @@ impl Bitv {
/// let bv: Bitv = [false, true].iter().map(|n| *n).collect();
/// assert_eq!(bv.get(0), false);
/// assert_eq!(bv.get(1), true);
///
/// // Can also use array indexing
/// assert_eq!(bv[1], true);
/// ```
#[inline]
pub fn get(&self, i: uint) -> bool {
Expand All @@ -275,7 +280,7 @@ impl Bitv {
///
/// let mut bv = Bitv::with_capacity(5, false);
/// bv.set(3, true);
/// assert_eq!(bv.get(3), true);
/// assert_eq!(bv[3], true);
/// ```
#[inline]
pub fn set(&mut self, i: uint, x: bool) {
Expand Down Expand Up @@ -478,7 +483,7 @@ impl Bitv {
/// Organise the bits into bytes, such that the first bit in the
/// `Bitv` becomes the high-order bit of the first byte. If the
/// size of the `Bitv` is not a multiple of 8 then trailing bits
/// will be filled-in with false/0.
/// will be filled-in with `false`.
///
/// # Example
///
Expand Down Expand Up @@ -716,9 +721,9 @@ impl Bitv {
/// # Example
///
/// ```
/// use std::collections::bitv::from_bytes;
/// use std::collections::bitv;
///
/// let bv = from_bytes([0b10100000, 0b00010010]);
/// let bv = bitv::from_bytes([0b10100000, 0b00010010]);
/// assert!(bv.eq_vec([true, false, true, false,
/// false, false, false, false,
/// false, false, false, true,
Expand Down Expand Up @@ -898,7 +903,7 @@ impl<'a> RandomAccessIterator<bool> for Bits<'a> {
///
/// ```
/// use std::collections::{BitvSet, Bitv};
/// use std::collections::bitv::from_bytes;
/// use std::collections::bitv;
///
/// // It's a regular set
/// let mut s = BitvSet::new();
Expand All @@ -913,7 +918,7 @@ impl<'a> RandomAccessIterator<bool> for Bits<'a> {
/// }
///
/// // Can initialize from a `Bitv`
/// let other = BitvSet::from_bitv(from_bytes([0b11010000]));
/// let other = BitvSet::from_bitv(bitv::from_bytes([0b11010000]));
///
/// s.union_with(&other);
///
Expand Down Expand Up @@ -1048,7 +1053,7 @@ impl BitvSet {
/// s.insert(0);
///
/// let bv = s.get_ref();
/// assert_eq!(bv.get(0), true);
/// assert_eq!(bv[0], true);
/// ```
#[inline]
pub fn get_ref<'a>(&'a self) -> &'a Bitv {
Expand Down Expand Up @@ -1131,9 +1136,9 @@ impl BitvSet {
///
/// ```
/// use std::collections::BitvSet;
/// use std::collections::bitv::from_bytes;
/// use std::collections::bitv;
///
/// let s = BitvSet::from_bitv(from_bytes([0b01001010]));
/// let s = BitvSet::from_bitv(bitv::from_bytes([0b01001010]));
///
/// // Print 1, 4, 6 in arbitrary order
/// for x in s.iter() {
Expand All @@ -1152,10 +1157,10 @@ impl BitvSet {
///
/// ```
/// use std::collections::BitvSet;
/// use std::collections::bitv::from_bytes;
/// use std::collections::bitv;
///
/// let a = BitvSet::from_bitv(from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(from_bytes([0b10100000]));
/// let a = BitvSet::from_bitv(bitv::from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(bitv::from_bytes([0b10100000]));
///
/// // Print 0, 1, 2, 4 in arbitrary order
/// for x in a.union(&b) {
Expand All @@ -1180,10 +1185,10 @@ impl BitvSet {
///
/// ```
/// use std::collections::BitvSet;
/// use std::collections::bitv::from_bytes;
/// use std::collections::bitv;
///
/// let a = BitvSet::from_bitv(from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(from_bytes([0b10100000]));
/// let a = BitvSet::from_bitv(bitv::from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(bitv::from_bytes([0b10100000]));
///
/// // Print 2
/// for x in a.intersection(&b) {
Expand All @@ -1209,10 +1214,10 @@ impl BitvSet {
///
/// ```
/// use std::collections::BitvSet;
/// use std::collections::bitv::from_bytes;
/// use std::collections::bitv;
///
/// let a = BitvSet::from_bitv(from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(from_bytes([0b10100000]));
/// let a = BitvSet::from_bitv(bitv::from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(bitv::from_bytes([0b10100000]));
///
/// // Print 2, 4 in arbitrary order
/// for x in a.difference(&b) {
Expand Down Expand Up @@ -1245,10 +1250,10 @@ impl BitvSet {
///
/// ```
/// use std::collections::BitvSet;
/// use std::collections::bitv::from_bytes;
/// use std::collections::bitv;
///
/// let a = BitvSet::from_bitv(from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(from_bytes([0b10100000]));
/// let a = BitvSet::from_bitv(bitv::from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(bitv::from_bytes([0b10100000]));
///
/// // Print 0, 1, 4 in arbitrary order
/// for x in a.symmetric_difference(&b) {
Expand All @@ -1272,13 +1277,13 @@ impl BitvSet {
///
/// ```
/// use std::collections::BitvSet;
/// use std::collections::bitv::from_bytes;
/// use std::collections::bitv;
///
/// let mut a = BitvSet::from_bitv(from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(from_bytes([0b10100000]));
/// let mut a = BitvSet::from_bitv(bitv::from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(bitv::from_bytes([0b10100000]));
///
/// a.union_with(&b);
/// assert_eq!(a.unwrap(), from_bytes([0b11101000]));
/// assert_eq!(a.unwrap(), bitv::from_bytes([0b11101000]));
/// ```
#[inline]
pub fn union_with(&mut self, other: &BitvSet) {
Expand All @@ -1291,13 +1296,13 @@ impl BitvSet {
///
/// ```
/// use std::collections::BitvSet;
/// use std::collections::bitv::from_bytes;
/// use std::collections::bitv;
///
/// let mut a = BitvSet::from_bitv(from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(from_bytes([0b10100000]));
/// let mut a = BitvSet::from_bitv(bitv::from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(bitv::from_bytes([0b10100000]));
///
/// a.intersect_with(&b);
/// assert_eq!(a.unwrap(), from_bytes([0b00100000]));
/// assert_eq!(a.unwrap(), bitv::from_bytes([0b00100000]));
/// ```
#[inline]
pub fn intersect_with(&mut self, other: &BitvSet) {
Expand All @@ -1310,13 +1315,13 @@ impl BitvSet {
///
/// ```
/// use std::collections::BitvSet;
/// use std::collections::bitv::from_bytes;
/// use std::collections::bitv;
///
/// let mut a = BitvSet::from_bitv(from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(from_bytes([0b10100000]));
/// let mut a = BitvSet::from_bitv(bitv::from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(bitv::from_bytes([0b10100000]));
///
/// a.difference_with(&b);
/// assert_eq!(a.unwrap(), from_bytes([0b01001000]));
/// assert_eq!(a.unwrap(), bitv::from_bytes([0b01001000]));
/// ```
#[inline]
pub fn difference_with(&mut self, other: &BitvSet) {
Expand All @@ -1329,13 +1334,13 @@ impl BitvSet {
///
/// ```
/// use std::collections::BitvSet;
/// use std::collections::bitv::from_bytes;
/// use std::collections::bitv;
///
/// let mut a = BitvSet::from_bitv(from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(from_bytes([0b10100000]));
/// let mut a = BitvSet::from_bitv(bitv::from_bytes([0b01101000]));
/// let b = BitvSet::from_bitv(bitv::from_bytes([0b10100000]));
///
/// a.symmetric_difference_with(&b);
/// assert_eq!(a.unwrap(), from_bytes([0b11001000]));
/// assert_eq!(a.unwrap(), bitv::from_bytes([0b11001000]));
/// ```
#[inline]
pub fn symmetric_difference_with(&mut self, other: &BitvSet) {
Expand Down
38 changes: 21 additions & 17 deletions src/libcollections/lib.rs
View file
Expand Up @@ -330,36 +330,36 @@ pub trait MutableSet<T>: Set<T> + Mutable {
///
/// # Example
///
/// With a `Deque` we can simulate a stack:
/// With a `Deque` we can simulate a queue efficiently:
///
/// ```
/// use std::collections::{RingBuf, Deque};
///
/// let mut stack = RingBuf::new();
/// stack.push_front(1i);
/// stack.push_front(2i);
/// stack.push_front(3i);
/// let mut queue = RingBuf::new();
/// queue.push_back(1i);
/// queue.push_back(2i);
/// queue.push_back(3i);
///
/// // Will print 3, 2, 1
/// while !stack.is_empty() {
/// let x = stack.pop_front().unwrap();
/// // Will print 1, 2, 3
/// while !queue.is_empty() {
/// let x = queue.pop_front().unwrap();
/// println!("{}", x);
/// }
/// ```
///
/// We can simulate a queue:
/// We can also simulate a stack:
///
/// ```
/// use std::collections::{RingBuf, Deque};
///
/// let mut queue = RingBuf::new();
/// queue.push_back(1i);
/// queue.push_back(2i);
/// queue.push_back(3i);
/// let mut stack = RingBuf::new();
/// stack.push_front(1i);
/// stack.push_front(2i);
/// stack.push_front(3i);
///
/// // Will print 1, 2, 3
/// while !queue.is_empty() {
/// let x = queue.pop_front().unwrap();
/// // Will print 3, 2, 1
/// while !stack.is_empty() {
/// let x = stack.pop_front().unwrap();
/// println!("{}", x);
/// }
/// ```
Expand All @@ -385,7 +385,7 @@ pub trait MutableSet<T>: Set<T> + Mutable {
/// }
/// ```
pub trait Deque<T> : Mutable {
/// Provide a reference to the front element, or `None` if the sequence is.
/// Provide a reference to the front element, or `None` if the sequence is
/// empty.
///
/// # Example
Expand Down Expand Up @@ -472,6 +472,7 @@ pub trait Deque<T> : Mutable {
/// 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.
Expand All @@ -485,6 +486,7 @@ pub trait Deque<T> : Mutable {
/// 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.
Expand All @@ -501,6 +503,7 @@ pub trait Deque<T> : Mutable {
/// 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.
Expand All @@ -517,6 +520,7 @@ pub trait Deque<T> : Mutable {
/// 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>;
}

Expand Down

0 comments on commit e68333a

Please sign in to comment.