diff options
author | bors <bors@rust-lang.org> | 2013-05-26 10:32:02 -0700 |
---|---|---|
committer | bors <bors@rust-lang.org> | 2013-05-26 10:32:02 -0700 |
commit | f5d4ea84f5f38c230235a2bab142bfb55d6febdc (patch) | |
tree | 7e07bc48a67da2dce34dcdd2e2f0c5ed2db1dc1d | |
parent | 1f8c4b096da8d7c6436038730fa4a862e1ac91f5 (diff) | |
parent | 9bb8077c1816853527fdb1bc6333e266d7ae80a6 (diff) | |
download | rust-f5d4ea84f5f38c230235a2bab142bfb55d6febdc.tar.gz |
auto merge of #6748 : steveklabnik/rust/bool_docs, r=thestinger
There was some before, but now we have a big header, as well as
lots of individual bits of documentation.
-rw-r--r-- | src/libstd/bool.rs | 213 |
1 files changed, 194 insertions, 19 deletions
diff --git a/src/libstd/bool.rs b/src/libstd/bool.rs index 5ab7f838a57..532e470e595 100644 --- a/src/libstd/bool.rs +++ b/src/libstd/bool.rs @@ -8,45 +8,190 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Boolean logic +/*! + +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` +* `Ord` +* `TotalOrd` +* `Eq` + +## 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 inquries into the nature of truth: `is_true` and `is_false`. + +*/ #[cfg(not(test))] use cmp::{Eq, Ord, TotalOrd, Ordering}; use option::{None, Option, Some}; use from_str::FromStr; -/// Negation / inverse +/** +* Negation of a boolean value. +* +* # Examples +* ~~~ +* rusti> core::bool::not(true) +* false +* ~~~ +* rusti> core::bool::not(false) +* true +* ~~~ +*/ pub fn not(v: bool) -> bool { !v } -/// Conjunction +/** +* Conjunction of two boolean values. +* +* # Examples +* ~~~ +* rusti> core::bool::and(true, false) +* false +* ~~~ +* rusti> core::bool::and(true, true) +* true +* ~~~ +*/ pub fn and(a: bool, b: bool) -> bool { a && b } -/// Disjunction +/** +* Disjunction of two boolean values. +* +* # Examples +* ~~~ +* rusti> core::bool::or(true, false) +* true +* ~~~ +* rusti> core::bool::or(false, false) +* false +* ~~~ +*/ pub fn or(a: bool, b: bool) -> bool { a || b } /** - * Exclusive or - * - * Identical to `or(and(a, not(b)), and(not(a), b))` - */ +* An 'exclusive or' of two boolean values. +* +* 'exclusive or' is identical to `or(and(a, not(b)), and(not(a), b))`. +* +* # Examples +* ~~~ +* rusti> core::bool::xor(true, false) +* true +* ~~~ +* rusti> core::bool::xor(true, true) +* false +* ~~~ +*/ pub fn xor(a: bool, b: bool) -> bool { (a && !b) || (!a && b) } -/// Implication in the logic, i.e. from `a` follows `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 +* ~~~ +* rusti> core::bool::implies(true, true) +* true +* ~~~ +* rusti> core::bool::implies(true, false) +* false +* ~~~ +*/ pub fn implies(a: bool, b: bool) -> bool { !a || b } -/// true if truth values `a` and `b` are indistinguishable in the logic +/** +* Equality between two boolean values. +* +* Two booleans are equal if they have the same value. +* +* # Examples +* ~~~ +* rusti> core::bool::eq(false, true) +* false +* ~~~ +* rusti> core::bool::eq(false, false) +* true +* ~~~ +*/ pub fn eq(a: bool, b: bool) -> bool { a == b } -/// true if truth values `a` and `b` are distinguishable in the logic +/** +* Non-equality between two boolean values. +* +* Two booleans are not equal if they have different values. +* +* # Examples +* ~~~ +* rusti> core::bool::ne(false, true) +* true +* ~~~ +* rusti> core::bool::ne(false, false) +* false +* ~~~ +*/ pub fn ne(a: bool, b: bool) -> bool { a != b } -/// true if `v` represents truth in the logic +/** +* Is a given boolean value true? +* +* # Examples +* ~~~ +* rusti> core::bool::is_true(true) +* true +* ~~~ +* rusti> core::bool::is_true(false) +* false +* ~~~ +*/ pub fn is_true(v: bool) -> bool { v } -/// true if `v` represents falsehood in the logic +/** +* Is a given boolean value false? +* +* # Examples +* ~~~ +* rusti> core::bool::is_false(false) +* true +* ~~~ +* rusti> core::bool::is_false(true) +* false +* ~~~ +*/ pub fn is_false(v: bool) -> bool { !v } -/// Parse logic value from `s` +/** +* Parse a `bool` from a `str`. +* +* Yields an `Option<bool>`, because `str` may or may not actually be parseable. +* +* # Examples +* ~~~ +* rusti> FromStr::from_str::<bool>("true") +* Some(true) +* ~~~ +* rusti> FromStr::from_str::<bool>("false") +* Some(false) +* ~~~ +* rusti> FromStr::from_str::<bool>("not even a boolean") +* None +* ~~~ +*/ impl FromStr for bool { fn from_str(s: &str) -> Option<bool> { match s { @@ -57,19 +202,49 @@ impl FromStr for bool { } } -/// Convert `v` into a string +/** +* Convert a `bool` to a `str`. +* +* # Examples +* ~~~ +* rusti> std::bool::to_str(true) +* "true" +* ~~~ +* rusti> std::bool::to_str(false) +* "false" +* ~~~ +*/ pub fn to_str(v: bool) -> ~str { if v { ~"true" } else { ~"false" } } /** - * Iterates over all truth values by passing them to `blk` in an unspecified - * order - */ +* Iterates over all truth values, passing them to the given block. +* +* There are no guarantees about the order values will be given. +* +* # Examples +* ~~~ +* do core::bool::all_values |x: bool| { +* println(core::bool::to_str(x)); +* } +* ~~~ +*/ pub fn all_values(blk: &fn(v: bool)) { blk(true); blk(false); } -/// converts truth value to an 8 bit byte +/** +* Convert a `bool` to a `u8`. +* +* # Examples +* ~~~ +* rusti> std::bool::to_bit(true) +* 1 +* ~~~ +* rusti> std::bool::to_bit(false) +* 0 +* ~~~ +*/ #[inline(always)] pub fn to_bit(v: bool) -> u8 { if v { 1u8 } else { 0u8 } } |