Cleaned, documented, wrote tests for up std::bool

Removed unused import warning in std::mem and cleaned it up too

Removed is_true and is_false from std::bool

Removed freestanding functions in std::bool

1 files changed, 321 insertions, 269 deletions

diff --git a/src/libstd/bool.rs b/src/libstd/bool.rs
index 1d59e63e702..2eec6ff4cba 100644
--- a/src/libstd/bool.rs
+++ b/src/libstd/bool.rs
@@ -1,4 +1,4 @@
-// Copyright 2012 The Rust Project Developers. See the COPYRIGHT
+// Copyright 2013 The Rust Project Developers. See the COPYRIGHT
 // file at the top-level directory of this distribution and at
 // http://rust-lang.org/COPYRIGHT.
 //
@@ -8,193 +8,169 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-/*!
+//! The `bool` module contains useful code to help work with boolean values.
+//!
+//! A quick summary:
+//!
+//! ## Trait implementations for `bool`
+//!
+//! Implementations of the following traits:
+//!
+//! * `FromStr`
+//! * `ToStr`
+//! * `Not`
+//! * `Ord`
+//! * `TotalOrd`
+//! * `Eq`
+//! * `Default`
+//! * `Zero`
+//!
+//! ## Various functions to compare `bool`s
+//!
+//! All of the standard comparison functions one would expect: `and`, `eq`, `or`,
+//! and more.
+//!
+//! Also, a few conversion functions: `to_bit` and `to_str`.
 
-The `bool` module contains useful code to help work with boolean values.
-
-A quick summary:
-
-## Trait implementations for `bool`
+use option::{None, Option, Some};
+use from_str::FromStr;
+use to_str::ToStr;
+use num::FromPrimitive;
 
-Implementations of the following traits:
+#[cfg(not(test))] use cmp::{Eq, Ord, TotalOrd, Ordering};
+#[cfg(not(test))] use ops::{Not, BitAnd, BitOr, BitXor};
+#[cfg(not(test))] use default::Default;
+#[cfg(not(test))] use num::Zero;
 
-* `FromStr`
-* `ToStr`
-* `Not`
-* `Ord`
-* `TotalOrd`
-* `Eq`
-* `Default`
-* `Zero`
+/////////////////////////////////////////////////////////////////////////////
+// Freestanding functions
+/////////////////////////////////////////////////////////////////////////////
+
+/// Iterates over all truth values, passing them to the given block.
+///
+/// There are no guarantees about the order values will be given.
+///
+/// # Examples
+///
+/// ```
+/// do std::bool::all_values |x: bool| {
+///     println(x.to_str());
+/// }
+/// ```
+#[inline]
+pub fn all_values(blk: &fn(v: bool)) {
+    blk(true);
+    blk(false);
+}
 
-## Various functions to compare `bool`s
+/////////////////////////////////////////////////////////////////////////////
+// Methods on `bool`
+/////////////////////////////////////////////////////////////////////////////
+
+/// Extension methods on a `bool`
+pub trait Bool {
+    /// Conjunction of two boolean values.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// assert_eq!(true.and(true), true);
+    /// assert_eq!(true.and(false), false);
+    /// assert_eq!(false.and(true), false);
+    /// assert_eq!(false.and(false), false);
+    /// ```
+    fn and(self, b: bool) -> bool;
+
+    /// Disjunction of two boolean values.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// assert_eq!(true.or(true), true);
+    /// assert_eq!(true.or(false), true);
+    /// assert_eq!(false.or(true), true);
+    /// assert_eq!(false.or(false), false);
+    /// ```
+    fn or(self, b: bool) -> bool;
+
+    /// An 'exclusive or' of two boolean values.
+    ///
+    /// 'exclusive or' is identical to `or(and(a, not(b)), and(not(a), b))`.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// assert_eq!(true.xor(true), false);
+    /// assert_eq!(true.xor(false), true);
+    /// assert_eq!(false.xor(true), true);
+    /// assert_eq!(false.xor(false), false);
+    /// ```
+    fn xor(self, b: bool) -> bool;
+
+    /// Implication between two boolean values.
+    ///
+    /// Implication is often phrased as 'if a then b.'
+    ///
+    /// 'if a then b' is equivalent to `!a || b`.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// assert_eq!(true.implies(true), true);
+    /// assert_eq!(true.implies(false), false);
+    /// assert_eq!(false.implies(true), true);
+    /// assert_eq!(false.implies(false), true);
+    /// ```
+    fn implies(self, b: bool) -> bool;
+
+    /// Convert a `bool` to a `u8`.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// assert_eq!(true.to_bit::<u8>(), 1u8);
+    /// assert_eq!(false.to_bit::<u8>(), 0u8);
+    /// ```
+    fn to_bit<N: FromPrimitive>(self) -> N;
+}
 
-All of the standard comparison functions one would expect: `and`, `eq`, `or`,
-and more.
+impl Bool for bool {
+    #[inline]
+    fn and(self, b: bool) -> bool { self && b }
 
-Also, a few conversion functions: `to_bit` and `to_str`.
+    #[inline]
+    fn or(self, b: bool) -> bool { self || b }
 
-Finally, some inquiries into the nature of truth: `is_true` and `is_false`.
+    #[inline]
+    fn xor(self, b: bool) -> bool { self ^ b }
 
-*/
+    #[inline]
+    fn implies(self, b: bool) -> bool { !self || b }
 
-use option::{None, Option, Some};
-use from_str::FromStr;
-use to_str::ToStr;
+    #[inline]
+    fn to_bit<N: FromPrimitive>(self) -> N {
+        if self { FromPrimitive::from_u8(1).unwrap() }
+        else    { FromPrimitive::from_u8(0).unwrap() }
+    }
+}
 
-#[cfg(not(test))] use cmp::{Eq, Ord, TotalOrd, Ordering};
-#[cfg(not(test))] use ops::Not;
-#[cfg(not(test))] use default::Default;
-#[cfg(not(test))] use num::Zero;
+/////////////////////////////////////////////////////////////////////////////
+// Trait impls on `bool`
+/////////////////////////////////////////////////////////////////////////////
 
-/**
-* Negation of a boolean value.
-*
-* # Examples
-*
-* ```rust
-* rusti> std::bool::not(true)
-* false
-* ```
-*
-* ```rust
-* rusti> std::bool::not(false)
-* true
-* ```
-*/
-pub fn not(v: bool) -> bool { !v }
-
-/**
-* Conjunction of two boolean values.
-*
-* # Examples
-*
-* ```rust
-* rusti> std::bool::and(true, false)
-* false
-* ```
-*
-* ```rust
-* rusti> std::bool::and(true, true)
-* true
-* ```
-*/
-pub fn and(a: bool, b: bool) -> bool { a && b }
-
-/**
-* Disjunction of two boolean values.
-*
-* # Examples
-*
-* ```rust
-* rusti> std::bool::or(true, false)
-* true
-* ```
-*
-* ```rust
-* rusti> std::bool::or(false, false)
-* false
-* ```
-*/
-pub fn or(a: bool, b: bool) -> bool { a || b }
-
-/**
-* An 'exclusive or' of two boolean values.
-*
-* 'exclusive or' is identical to `or(and(a, not(b)), and(not(a), b))`.
-*
-* # Examples
-*
-* ```rust
-* rusti> std::bool::xor(true, false)
-* true
-* ```
-*
-* ```rust
-* rusti> std::bool::xor(true, true)
-* false
-* ```
-*/
-pub fn xor(a: bool, b: bool) -> bool { (a && !b) || (!a && b) }
-
-/**
-* Implication between two boolean values.
-*
-* Implication is often phrased as 'if a then b.'
-*
-* 'if a then b' is equivalent to `!a || b`.
-*
-* # Examples
-*
-* ```rust
-* rusti> std::bool::implies(true, true)
-* true
-* ```
-*
-* ```rust
-* rusti> std::bool::implies(true, false)
-* false
-* ```
-*/
-pub fn implies(a: bool, b: bool) -> bool { !a || b }
-
-/**
-* Is a given boolean value true?
-*
-* # Examples
-*
-* ```rust
-* rusti> std::bool::is_true(true)
-* true
-* ```
-*
-* ```rust
-* rusti> std::bool::is_true(false)
-* false
-* ```
-*/
-pub fn is_true(v: bool) -> bool { v }
-
-/**
-* Is a given boolean value false?
-*
-* # Examples
-*
-* ```rust
-* rusti> std::bool::is_false(false)
-* true
-* ```
-*
-* ```rust
-* rusti> std::bool::is_false(true)
-* false
-* ```
-*/
-pub fn is_false(v: bool) -> bool { !v }
-
-/**
-* Parse a `bool` from a `str`.
-*
-* Yields an `Option<bool>`, because `str` may or may not actually be parseable.
-*
-* # Examples
-*
-* ```rust
-* rusti> FromStr::from_str::<bool>("true")
-* Some(true)
-* ```
-*
-* ```rust
-* rusti> FromStr::from_str::<bool>("false")
-* Some(false)
-* ```
-*
-* ```rust
-* rusti> FromStr::from_str::<bool>("not even a boolean")
-* None
-* ```
-*/
 impl FromStr for bool {
+    /// Parse a `bool` from a string.
+    ///
+    /// Yields an `Option<bool>`, because `s` may or may not actually be parseable.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// assert_eq!(from_str::<bool>("true"), Some(true));
+    /// assert_eq!(from_str::<bool>("false"), Some(false));
+    /// assert_eq!(from_str::<bool>("not even a boolean"), None);
+    /// ```
+    #[inline]
     fn from_str(s: &str) -> Option<bool> {
         match s {
             "true"  => Some(true),
@@ -204,121 +180,124 @@ impl FromStr for bool {
     }
 }
 
-/**
-* Convert a `bool` to a `str`.
-*
-* # Examples
-*
-* ```rust
-* rusti> true.to_str()
-* "true"
-* ```
-*
-* ```rust
-* rusti> false.to_str()
-* "false"
-* ```
-*/
 impl ToStr for bool {
+    /// Convert a `bool` to a string.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// assert_eq!(true.to_str(), ~"true");
+    /// assert_eq!(false.to_str(), ~"false");
+    /// ```
     #[inline]
     fn to_str(&self) -> ~str {
         if *self { ~"true" } else { ~"false" }
     }
 }
 
-/**
-* Iterates over all truth values, passing them to the given block.
-*
-* There are no guarantees about the order values will be given.
-*
-* # Examples
-* ```
-* do std::bool::all_values |x: bool| {
-*     println(x.to_str())
-* }
-* ```
-*/
-pub fn all_values(blk: &fn(v: bool)) {
-    blk(true);
-    blk(false);
-}
-
-/**
-* Convert a `bool` to a `u8`.
-*
-* # Examples
-*
-* ```rust
-* rusti> std::bool::to_bit(true)
-* 1
-* ```
-*
-* ```rust
-* rusti> std::bool::to_bit(false)
-* 0
-* ```
-*/
-#[inline]
-pub fn to_bit(v: bool) -> u8 { if v { 1u8 } else { 0u8 } }
-
-/**
-* The logical complement of a boolean value.
-*
-* # Examples
-*
-* ~~~rust
-* rusti> !true
-* false
-* ```
-*
-* ~~~rust
-* rusti> !false
-* true
-* ```
-*/
 #[cfg(not(test))]
 impl Not<bool> for bool {
+    /// The logical complement of a boolean value.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// assert_eq!(!true, false);
+    /// assert_eq!(!false, true);
+    /// ```
     #[inline]
     fn not(&self) -> bool { !*self }
 }
 
 #[cfg(not(test))]
+impl BitAnd<bool, bool> for bool {
+    /// Conjunction of two boolean values.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// assert_eq!(false.bitand(&false), false);
+    /// assert_eq!(true.bitand(&false), false);
+    /// assert_eq!(false.bitand(&true), false);
+    /// assert_eq!(true.bitand(&true), true);
+    ///
+    /// assert_eq!(false & false, false);
+    /// assert_eq!(true & false, false);
+    /// assert_eq!(false & true, false);
+    /// assert_eq!(true & true, true);
+    /// ```
+    #[inline]
+    fn bitand(&self, b: &bool) -> bool { *self & *b }
+}
+
+#[cfg(not(test))]
+impl BitOr<bool, bool> for bool {
+    /// Disjunction of two boolean values.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// assert_eq!(false.bitor(&false), false);
+    /// assert_eq!(true.bitor(&false), true);
+    /// assert_eq!(false.bitor(&true), true);
+    /// assert_eq!(true.bitor(&true), true);
+    ///
+    /// assert_eq!(false | false, false);
+    /// assert_eq!(true | false, true);
+    /// assert_eq!(false | true, true);
+    /// assert_eq!(true | true, true);
+    /// ```
+    #[inline]
+    fn bitor(&self, b: &bool) -> bool { *self | *b }
+}
+
+#[cfg(not(test))]
+impl BitXor<bool, bool> for bool {
+    /// An 'exclusive or' of two boolean values.
+    ///
+    /// 'exclusive or' is identical to `or(and(a, not(b)), and(not(a), b))`.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// assert_eq!(false.bitxor(&false), false);
+    /// assert_eq!(true.bitxor(&false), true);
+    /// assert_eq!(false.bitxor(&true), true);
+    /// assert_eq!(true.bitxor(&true), false);
+    ///
+    /// assert_eq!(false ^ false, false);
+    /// assert_eq!(true ^ false, true);
+    /// assert_eq!(false ^ true, true);
+    /// assert_eq!(true ^ true, false);
+    /// ```
+    #[inline]
+    fn bitxor(&self, b: &bool) -> bool { *self ^ *b }
+}
+
+#[cfg(not(test))]
 impl Ord for bool {
     #[inline]
-    fn lt(&self, other: &bool) -> bool { to_bit(*self) < to_bit(*other) }
+    fn lt(&self, other: &bool) -> bool { self.to_bit::<u8>() < other.to_bit() }
 }
 
 #[cfg(not(test))]
 impl TotalOrd for bool {
     #[inline]
-    fn cmp(&self, other: &bool) -> Ordering { to_bit(*self).cmp(&to_bit(*other)) }
+    fn cmp(&self, other: &bool) -> Ordering { self.to_bit::<u8>().cmp(&other.to_bit()) }
 }
 
-/**
-* Equality between two boolean values.
-*
-* Two booleans are equal if they have the same value.
-*
-* ```rust
-* rusti> false.eq(&true)
-* false
-* ```
-*
-* ```rust
-* rusti> false == false
-* true
-* ```
-*
-* ```rust
-* rusti> false != true
-* true
-* ```
-*
-* ```rust
-* rusti> false.ne(&false)
-* false
-* ```
-*/
+/// Equality between two boolean values.
+///
+/// Two booleans are equal if they have the same value.
+///
+/// # Examples
+///
+/// ```rust
+/// assert_eq!(false.eq(&true), false);
+/// assert_eq!(false == false, true);
+/// assert_eq!(false != true, true);
+/// assert_eq!(false.ne(&false), false);
+/// ```
 #[cfg(not(test))]
 impl Eq for bool {
     #[inline]
@@ -342,6 +321,77 @@ mod tests {
     use prelude::*;
 
     #[test]
+    fn test_bool() {
+        assert_eq!(false.eq(&true), false);
+        assert_eq!(false == false, true);
+        assert_eq!(false != true, true);
+        assert_eq!(false.ne(&false), false);
+
+        assert_eq!(false.bitand(&false), false);
+        assert_eq!(true.bitand(&false), false);
+        assert_eq!(false.bitand(&true), false);
+        assert_eq!(true.bitand(&true), true);
+
+        assert_eq!(false & false, false);
+        assert_eq!(true & false, false);
+        assert_eq!(false & true, false);
+        assert_eq!(true & true, true);
+
+        assert_eq!(false.bitor(&false), false);
+        assert_eq!(true.bitor(&false), true);
+        assert_eq!(false.bitor(&true), true);
+        assert_eq!(true.bitor(&true), true);
+
+        assert_eq!(false | false, false);
+        assert_eq!(true | false, true);
+        assert_eq!(false | true, true);
+        assert_eq!(true | true, true);
+
+        assert_eq!(false.bitxor(&false), false);
+        assert_eq!(true.bitxor(&false), true);
+        assert_eq!(false.bitxor(&true), true);
+        assert_eq!(true.bitxor(&true), false);
+
+        assert_eq!(false ^ false, false);
+        assert_eq!(true ^ false, true);
+        assert_eq!(false ^ true, true);
+        assert_eq!(true ^ true, false);
+
+        assert_eq!(!true, false);
+        assert_eq!(!false, true);
+
+        assert_eq!(true.to_str(), ~"true");
+        assert_eq!(false.to_str(), ~"false");
+
+        assert_eq!(from_str::<bool>("true"), Some(true));
+        assert_eq!(from_str::<bool>("false"), Some(false));
+        assert_eq!(from_str::<bool>("not even a boolean"), None);
+
+        assert_eq!(true.and(true), true);
+        assert_eq!(true.and(false), false);
+        assert_eq!(false.and(true), false);
+        assert_eq!(false.and(false), false);
+
+        assert_eq!(true.or(true), true);
+        assert_eq!(true.or(false), true);
+        assert_eq!(false.or(true), true);
+        assert_eq!(false.or(false), false);
+
+        assert_eq!(true.xor(true), false);
+        assert_eq!(true.xor(false), true);
+        assert_eq!(false.xor(true), true);
+        assert_eq!(false.xor(false), false);
+
+        assert_eq!(true.implies(true), true);
+        assert_eq!(true.implies(false), false);
+        assert_eq!(false.implies(true), true);
+        assert_eq!(false.implies(false), true);
+
+        assert_eq!(true.to_bit::<u8>(), 1u8);
+        assert_eq!(false.to_bit::<u8>(), 0u8);
+    }
+
+    #[test]
     fn test_bool_from_str() {
         do all_values |v| {
             assert!(Some(v) == FromStr::from_str(v.to_str()))
@@ -357,7 +407,9 @@ mod tests {
     #[test]
     fn test_bool_to_bit() {
         do all_values |v| {
-            assert_eq!(to_bit(v), if is_true(v) { 1u8 } else { 0u8 });
+            assert_eq!(v.to_bit::<u8>(), if v { 1u8 } else { 0u8 });
+            assert_eq!(v.to_bit::<uint>(), if v { 1u } else { 0u });
+            assert_eq!(v.to_bit::<int>(), if v { 1i } else { 0i });
         }
     }