OpenE2K
/
rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

auto merge of #10007 : Kimundi/rust/add_docs_01, r=cmr 

Additionally:
- Sorted the prelude reexports
- Removed unused import warning in std::mem and cleaned it up too

(I was bored 👻 )
This commit is contained in:
bors 2013-10-24 13:01:18 -07:00
parent 7075eb3625 e53aae4772
commit 61f8c059c4
3 changed files with 342 additions and 297 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

580
src/libstd/bool.rs
View File

@ -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`.
Finally, some inquiries into the nature of truth: `is_true` and `is_false`.
*/
//! 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`.
use option::{None, Option, Some};
use from_str::FromStr;
use to_str::ToStr;
use num::FromPrimitive;
#[cfg(not(test))] use cmp::{Eq, Ord, TotalOrd, Ordering};
#[cfg(not(test))] use ops::Not;
#[cfg(not(test))] use ops::{Not, BitAnd, BitOr, BitXor};
#[cfg(not(test))] use default::Default;
#[cfg(not(test))] use num::Zero;
/**
* 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 }
/////////////////////////////////////////////////////////////////////////////
// Freestanding functions
/////////////////////////////////////////////////////////////////////////////
/**
* 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 }
/// 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);
}
/**
* 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 }
/////////////////////////////////////////////////////////////////////////////
// Methods on `bool`
/////////////////////////////////////////////////////////////////////////////
/**
* 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) }
/// 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;
/**
* 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 }
/// 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;
/**
* 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 }
/// 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;
/**
* 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 }
/// 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;
}
impl Bool for bool {
#[inline]
fn and(self, b: bool) -> bool { self && b }
#[inline]
fn or(self, b: bool) -> bool { self || b }
#[inline]
fn xor(self, b: bool) -> bool { self ^ b }
#[inline]
fn implies(self, b: bool) -> bool { !self || b }
#[inline]
fn to_bit<N: FromPrimitive>(self) -> N {
if self { FromPrimitive::from_u8(1).unwrap() }
else { FromPrimitive::from_u8(0).unwrap() }
}
}
/////////////////////////////////////////////////////////////////////////////
// Trait impls on `bool`
/////////////////////////////////////////////////////////////////////////////
/**
* 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]
@ -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::<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| {
@ -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 });
}
}

20
src/libstd/mem.rs
View File

@ -24,11 +24,9 @@ pub fn size_of_val<T>(_val: &T) -> uint {
size_of::<T>()
}
/**
* 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<T>() -> uint {
let s = size_of::<T>();
@ -41,13 +39,10 @@ pub fn nonzero_size_of_val<T>(_val: &T) -> uint {
nonzero_size_of::<T>()
}
/**
* 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<T>() -> uint {
unsafe { intrinsics::min_align_of::<T>() }
@ -75,7 +70,6 @@ pub fn pref_align_of_val<T>(_val: &T) -> uint {
#[cfg(test)]
mod tests {
use cast;
use mem::*;
#[test]

39
src/libstd/prelude.rs
View File

@ -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::Times;
pub use num::{Algebraic, Trigonometric, Exponential, Hyperbolic};
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::{Algebraic, Trigonometric, Exponential, Hyperbolic};
pub use num::{Integer, Fractional, Real, RealExt};
pub use num::{Bitwise, BitCount, Bounded};
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};