From e53aae47724fb6cb5cd1106c1edafeee5b4f96a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marvin=20L=C3=B6bel?= Date: Mon, 21 Oct 2013 21:41:32 +0200 Subject: [PATCH] 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 --- src/libstd/bool.rs | 590 +++++++++++++++++++++++------------------- src/libstd/mem.rs | 20 +- src/libstd/prelude.rs | 39 ++- 3 files changed, 347 insertions(+), 302 deletions(-) diff --git a/src/libstd/bool.rs b/src/libstd/bool.rs index 1d59e63e702f5..2eec6ff4cba43 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::(), 1u8); + /// assert_eq!(false.to_bit::(), 0u8); + /// ``` + fn to_bit(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(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`, because `str` may or may not actually be parseable. -* -* # Examples -* -* ```rust -* rusti> FromStr::from_str::("true") -* Some(true) -* ``` -* -* ```rust -* rusti> FromStr::from_str::("false") -* Some(false) -* ``` -* -* ```rust -* rusti> FromStr::from_str::("not even a boolean") -* None -* ``` -*/ impl FromStr for bool { + /// Parse a `bool` from a string. + /// + /// Yields an `Option`, because `s` may or may not actually be parseable. + /// + /// # Examples + /// + /// ```rust + /// assert_eq!(from_str::("true"), Some(true)); + /// assert_eq!(from_str::("false"), Some(false)); + /// assert_eq!(from_str::("not even a boolean"), None); + /// ``` + #[inline] fn from_str(s: &str) -> Option { 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 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 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 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 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::() < 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::().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] @@ -341,6 +320,77 @@ mod tests { use super::*; 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::("true"), Some(true)); + assert_eq!(from_str::("false"), Some(false)); + assert_eq!(from_str::("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::(), 1u8); + assert_eq!(false.to_bit::(), 0u8); + } + #[test] fn test_bool_from_str() { do all_values |v| { @@ -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::(), if v { 1u8 } else { 0u8 }); + assert_eq!(v.to_bit::(), if v { 1u } else { 0u }); + assert_eq!(v.to_bit::(), if v { 1i } else { 0i }); } } diff --git a/src/libstd/mem.rs b/src/libstd/mem.rs index 311bf5f6bc87c..c4a546f71c315 100644 --- a/src/libstd/mem.rs +++ b/src/libstd/mem.rs @@ -24,11 +24,9 @@ pub fn size_of_val(_val: &T) -> uint { size_of::() } -/** - * Returns the size of a type, or 1 if the actual size is zero. - * - * Useful for building structures containing variable-length arrays. - */ +/// Returns the size of a type, or 1 if the actual size is zero. +/// +/// Useful for building structures containing variable-length arrays. #[inline] pub fn nonzero_size_of() -> uint { let s = size_of::(); @@ -41,13 +39,10 @@ pub fn nonzero_size_of_val(_val: &T) -> uint { nonzero_size_of::() } - -/** - * Returns the ABI-required minimum alignment of a type - * - * This is the alignment used for struct fields. It may be smaller - * than the preferred alignment. - */ +/// Returns the ABI-required minimum alignment of a type +/// +/// This is the alignment used for struct fields. It may be smaller +/// than the preferred alignment. #[inline] pub fn min_align_of() -> uint { unsafe { intrinsics::min_align_of::() } @@ -75,7 +70,6 @@ pub fn pref_align_of_val(_val: &T) -> uint { #[cfg(test)] mod tests { - use cast; use mem::*; #[test] diff --git a/src/libstd/prelude.rs b/src/libstd/prelude.rs index 24327e57f8295..886ad9995a150 100644 --- a/src/libstd/prelude.rs +++ b/src/libstd/prelude.rs @@ -26,7 +26,6 @@ Rust's prelude has three main parts: */ - // Reexported core operators pub use either::{Either, Left, Right}; pub use kinds::Sized; @@ -39,48 +38,48 @@ pub use option::{Option, Some, None}; pub use result::{Result, Ok, Err}; // Reexported functions -pub use rt::io::stdio::{print, println}; -pub use iter::range; pub use from_str::from_str; +pub use iter::range; +pub use rt::io::stdio::{print, println}; // Reexported types and traits +pub use ascii::{Ascii, AsciiCast, OwnedAsciiCast, AsciiStr, ToBytesConsume}; +pub use bool::Bool; pub use c_str::ToCStr; +pub use char::Char; pub use clone::{Clone, DeepClone}; pub use cmp::{Eq, ApproxEq, Ord, TotalEq, TotalOrd, Ordering, Less, Equal, Greater, Equiv}; -pub use char::Char; pub use container::{Container, Mutable, Map, MutableMap, Set, MutableSet}; +pub use default::Default; +pub use from_str::FromStr; pub use hash::Hash; -pub use num::Times; +pub use io::{Reader, ReaderUtil, Writer, WriterUtil}; pub use iter::{FromIterator, Extendable}; pub use iter::{Iterator, DoubleEndedIterator, RandomAccessIterator, ClonableIterator}; pub use iter::{OrdIterator, MutableDoubleEndedIterator, ExactSize}; -pub use num::{Num, NumCast, CheckedAdd, CheckedSub, CheckedMul}; -pub use num::{Orderable, Signed, Unsigned, Round}; +pub use num::Times; pub use num::{Algebraic, Trigonometric, Exponential, Hyperbolic}; -pub use num::{Integer, Fractional, Real, RealExt}; pub use num::{Bitwise, BitCount, Bounded}; +pub use num::{Integer, Fractional, Real, RealExt}; +pub use num::{Num, NumCast, CheckedAdd, CheckedSub, CheckedMul}; +pub use num::{Orderable, Signed, Unsigned, Round}; pub use num::{Primitive, Int, Float, ToStrRadix, ToPrimitive, FromPrimitive}; pub use path::{GenericPath, Path, PosixPath, WindowsPath}; pub use ptr::RawPtr; -pub use ascii::{Ascii, AsciiCast, OwnedAsciiCast, AsciiStr, ToBytesConsume}; pub use send_str::{SendStr, SendStrOwned, SendStrStatic, IntoSendStr}; pub use str::{Str, StrVector, StrSlice, OwnedStr}; -pub use from_str::FromStr; pub use to_bytes::IterBytes; pub use to_str::{ToStr, ToStrConsume}; pub use tuple::{CopyableTuple, ImmutableTuple}; -pub use tuple::{Tuple1, ImmutableTuple1}; -pub use tuple::{Tuple2, Tuple3, Tuple4, Tuple5}; -pub use tuple::{Tuple6, Tuple7, Tuple8, Tuple9}; -pub use tuple::{Tuple10, Tuple11, Tuple12}; -pub use tuple::{ImmutableTuple2, ImmutableTuple3, ImmutableTuple4, ImmutableTuple5}; -pub use tuple::{ImmutableTuple6, ImmutableTuple7, ImmutableTuple8, ImmutableTuple9}; -pub use tuple::{ImmutableTuple10, ImmutableTuple11, ImmutableTuple12}; -pub use vec::{Vector, VectorVector, CopyableVector, ImmutableVector}; +pub use tuple::{ImmutableTuple1, ImmutableTuple2, ImmutableTuple3, ImmutableTuple4}; +pub use tuple::{ImmutableTuple5, ImmutableTuple6, ImmutableTuple7, ImmutableTuple8}; +pub use tuple::{ImmutableTuple9, ImmutableTuple10, ImmutableTuple11, ImmutableTuple12}; +pub use tuple::{Tuple1, Tuple2, Tuple3, Tuple4}; +pub use tuple::{Tuple5, Tuple6, Tuple7, Tuple8}; +pub use tuple::{Tuple9, Tuple10, Tuple11, Tuple12}; pub use vec::{ImmutableEqVector, ImmutableTotalOrdVector, ImmutableCopyableVector}; pub use vec::{OwnedVector, OwnedCopyableVector,OwnedEqVector, MutableVector}; -pub use io::{Reader, ReaderUtil, Writer, WriterUtil}; -pub use default::Default; +pub use vec::{Vector, VectorVector, CopyableVector, ImmutableVector}; // Reexported runtime types pub use comm::{stream, Port, Chan, GenericChan, GenericSmartChan, GenericPort, Peekable};