src/libstd/bool.rs

   1 // Copyright 2013 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! The `bool` module contains useful code to help work with boolean values.
  12 //!
  13 //! A quick summary:
  14 //!
  15 //! ## Trait implementations for `bool`
  16 //!
  17 //! Implementations of the following traits:
  18 //!
  19 //! * `FromStr`
  20 //! * `ToStr`
  21 //! * `Not`
  22 //! * `Ord`
  23 //! * `TotalOrd`
  24 //! * `Eq`
  25 //! * `Default`
  26 //! * `Zero`
  27 //!
  28 //! ## Various functions to compare `bool`s
  29 //!
  30 //! All of the standard comparison functions one would expect: `and`, `eq`, `or`,
  31 //! and more.
  32 //!
  33 //! Also, a few conversion functions: `to_bit` and `to_str`.
  34
  35 use option::{None, Option, Some};
  36 use from_str::FromStr;
  37 use to_str::ToStr;
  38 use num::FromPrimitive;
  39
  40 #[cfg(not(test))] use cmp::{Eq, Ord, TotalOrd, Ordering};
  41 #[cfg(not(test))] use ops::{Not, BitAnd, BitOr, BitXor};
  42 #[cfg(not(test))] use default::Default;
  43 #[cfg(not(test))] use num::Zero;
  44
  45 /////////////////////////////////////////////////////////////////////////////
  46 // Freestanding functions
  47 /////////////////////////////////////////////////////////////////////////////
  48
  49 /// Iterates over all truth values, passing them to the given block.
  50 ///
  51 /// There are no guarantees about the order values will be given.
  52 ///
  53 /// # Examples
  54 ///
  55 /// ```
  56 /// std::bool::all_values(|x: bool| {
  57 ///     println(x.to_str());
  58 /// })
  59 /// ```
  60 #[inline]
  61 pub fn all_values(blk: |v: bool|) {
  62     blk(true);
  63     blk(false);
  64 }
  65
  66 /////////////////////////////////////////////////////////////////////////////
  67 // Methods on `bool`
  68 /////////////////////////////////////////////////////////////////////////////
  69
  70 /// Extension methods on a `bool`
  71 pub trait Bool {
  72     /// Conjunction of two boolean values.
  73     ///
  74     /// # Examples
  75     ///
  76     /// ```rust
  77     /// assert_eq!(true.and(true), true);
  78     /// assert_eq!(true.and(false), false);
  79     /// assert_eq!(false.and(true), false);
  80     /// assert_eq!(false.and(false), false);
  81     /// ```
  82     fn and(self, b: bool) -> bool;
  83
  84     /// Disjunction of two boolean values.
  85     ///
  86     /// # Examples
  87     ///
  88     /// ```rust
  89     /// assert_eq!(true.or(true), true);
  90     /// assert_eq!(true.or(false), true);
  91     /// assert_eq!(false.or(true), true);
  92     /// assert_eq!(false.or(false), false);
  93     /// ```
  94     fn or(self, b: bool) -> bool;
  95
  96     /// An 'exclusive or' of two boolean values.
  97     ///
  98     /// 'exclusive or' is identical to `or(and(a, not(b)), and(not(a), b))`.
  99     ///
 100     /// # Examples
 101     ///
 102     /// ```rust
 103     /// assert_eq!(true.xor(true), false);
 104     /// assert_eq!(true.xor(false), true);
 105     /// assert_eq!(false.xor(true), true);
 106     /// assert_eq!(false.xor(false), false);
 107     /// ```
 108     fn xor(self, b: bool) -> bool;
 109
 110     /// Implication between two boolean values.
 111     ///
 112     /// Implication is often phrased as 'if a then b.'
 113     ///
 114     /// 'if a then b' is equivalent to `!a || b`.
 115     ///
 116     /// # Examples
 117     ///
 118     /// ```rust
 119     /// assert_eq!(true.implies(true), true);
 120     /// assert_eq!(true.implies(false), false);
 121     /// assert_eq!(false.implies(true), true);
 122     /// assert_eq!(false.implies(false), true);
 123     /// ```
 124     fn implies(self, b: bool) -> bool;
 125
 126     /// Convert a `bool` to a `u8`.
 127     ///
 128     /// # Examples
 129     ///
 130     /// ```rust
 131     /// assert_eq!(true.to_bit::<u8>(), 1u8);
 132     /// assert_eq!(false.to_bit::<u8>(), 0u8);
 133     /// ```
 134     fn to_bit<N: FromPrimitive>(self) -> N;
 135 }
 136
 137 impl Bool for bool {
 138     #[inline]
 139     fn and(self, b: bool) -> bool { self && b }
 140
 141     #[inline]
 142     fn or(self, b: bool) -> bool { self || b }
 143
 144     #[inline]
 145     fn xor(self, b: bool) -> bool { self ^ b }
 146
 147     #[inline]
 148     fn implies(self, b: bool) -> bool { !self || b }
 149
 150     #[inline]
 151     fn to_bit<N: FromPrimitive>(self) -> N {
 152         if self { FromPrimitive::from_u8(1).unwrap() }
 153         else    { FromPrimitive::from_u8(0).unwrap() }
 154     }
 155 }
 156
 157 /////////////////////////////////////////////////////////////////////////////
 158 // Trait impls on `bool`
 159 /////////////////////////////////////////////////////////////////////////////
 160
 161 impl FromStr for bool {
 162     /// Parse a `bool` from a string.
 163     ///
 164     /// Yields an `Option<bool>`, because `s` may or may not actually be parseable.
 165     ///
 166     /// # Examples
 167     ///
 168     /// ```rust
 169     /// assert_eq!(from_str::<bool>("true"), Some(true));
 170     /// assert_eq!(from_str::<bool>("false"), Some(false));
 171     /// assert_eq!(from_str::<bool>("not even a boolean"), None);
 172     /// ```
 173     #[inline]
 174     fn from_str(s: &str) -> Option<bool> {
 175         match s {
 176             "true"  => Some(true),
 177             "false" => Some(false),
 178             _       => None,
 179         }
 180     }
 181 }
 182
 183 impl ToStr for bool {
 184     /// Convert a `bool` to a string.
 185     ///
 186     /// # Examples
 187     ///
 188     /// ```rust
 189     /// assert_eq!(true.to_str(), ~"true");
 190     /// assert_eq!(false.to_str(), ~"false");
 191     /// ```
 192     #[inline]
 193     fn to_str(&self) -> ~str {
 194         if *self { ~"true" } else { ~"false" }
 195     }
 196 }
 197
 198 #[cfg(not(test))]
 199 impl Not<bool> for bool {
 200     /// The logical complement of a boolean value.
 201     ///
 202     /// # Examples
 203     ///
 204     /// ```rust
 205     /// assert_eq!(!true, false);
 206     /// assert_eq!(!false, true);
 207     /// ```
 208     #[inline]
 209     fn not(&self) -> bool { !*self }
 210 }
 211
 212 #[cfg(not(test))]
 213 impl BitAnd<bool, bool> for bool {
 214     /// Conjunction of two boolean values.
 215     ///
 216     /// # Examples
 217     ///
 218     /// ```rust
 219     /// assert_eq!(false.bitand(&false), false);
 220     /// assert_eq!(true.bitand(&false), false);
 221     /// assert_eq!(false.bitand(&true), false);
 222     /// assert_eq!(true.bitand(&true), true);
 223     ///
 224     /// assert_eq!(false & false, false);
 225     /// assert_eq!(true & false, false);
 226     /// assert_eq!(false & true, false);
 227     /// assert_eq!(true & true, true);
 228     /// ```
 229     #[inline]
 230     fn bitand(&self, b: &bool) -> bool { *self & *b }
 231 }
 232
 233 #[cfg(not(test))]
 234 impl BitOr<bool, bool> for bool {
 235     /// Disjunction of two boolean values.
 236     ///
 237     /// # Examples
 238     ///
 239     /// ```rust
 240     /// assert_eq!(false.bitor(&false), false);
 241     /// assert_eq!(true.bitor(&false), true);
 242     /// assert_eq!(false.bitor(&true), true);
 243     /// assert_eq!(true.bitor(&true), true);
 244     ///
 245     /// assert_eq!(false | false, false);
 246     /// assert_eq!(true | false, true);
 247     /// assert_eq!(false | true, true);
 248     /// assert_eq!(true | true, true);
 249     /// ```
 250     #[inline]
 251     fn bitor(&self, b: &bool) -> bool { *self | *b }
 252 }
 253
 254 #[cfg(not(test))]
 255 impl BitXor<bool, bool> for bool {
 256     /// An 'exclusive or' of two boolean values.
 257     ///
 258     /// 'exclusive or' is identical to `or(and(a, not(b)), and(not(a), b))`.
 259     ///
 260     /// # Examples
 261     ///
 262     /// ```rust
 263     /// assert_eq!(false.bitxor(&false), false);
 264     /// assert_eq!(true.bitxor(&false), true);
 265     /// assert_eq!(false.bitxor(&true), true);
 266     /// assert_eq!(true.bitxor(&true), false);
 267     ///
 268     /// assert_eq!(false ^ false, false);
 269     /// assert_eq!(true ^ false, true);
 270     /// assert_eq!(false ^ true, true);
 271     /// assert_eq!(true ^ true, false);
 272     /// ```
 273     #[inline]
 274     fn bitxor(&self, b: &bool) -> bool { *self ^ *b }
 275 }
 276
 277 #[cfg(not(test))]
 278 impl Ord for bool {
 279     #[inline]
 280     fn lt(&self, other: &bool) -> bool { self.to_bit::<u8>() < other.to_bit() }
 281 }
 282
 283 #[cfg(not(test))]
 284 impl TotalOrd for bool {
 285     #[inline]
 286     fn cmp(&self, other: &bool) -> Ordering { self.to_bit::<u8>().cmp(&other.to_bit()) }
 287 }
 288
 289 /// Equality between two boolean values.
 290 ///
 291 /// Two booleans are equal if they have the same value.
 292 ///
 293 /// # Examples
 294 ///
 295 /// ```rust
 296 /// assert_eq!(false.eq(&true), false);
 297 /// assert_eq!(false == false, true);
 298 /// assert_eq!(false != true, true);
 299 /// assert_eq!(false.ne(&false), false);
 300 /// ```
 301 #[cfg(not(test))]
 302 impl Eq for bool {
 303     #[inline]
 304     fn eq(&self, other: &bool) -> bool { (*self) == (*other) }
 305 }
 306
 307 #[cfg(not(test))]
 308 impl Default for bool {
 309     fn default() -> bool { false }
 310 }
 311
 312 #[cfg(not(test))]
 313 impl Zero for bool {
 314     fn zero() -> bool { false }
 315     fn is_zero(&self) -> bool { *self == false }
 316 }
 317
 318 #[cfg(test)]
 319 mod tests {
 320     use cmp::{Equal, Greater, Less, Eq, TotalOrd};
 321     use ops::{BitAnd, BitXor, BitOr};
 322     use from_str::{FromStr, from_str};
 323     use option::{Some, None};
 324     use super::all_values;
 325
 326     #[test]
 327     fn test_bool() {
 328         assert_eq!(false.eq(&true), false);
 329         assert_eq!(false == false, true);
 330         assert_eq!(false != true, true);
 331         assert_eq!(false.ne(&false), false);
 332
 333         assert_eq!(false.bitand(&false), false);
 334         assert_eq!(true.bitand(&false), false);
 335         assert_eq!(false.bitand(&true), false);
 336         assert_eq!(true.bitand(&true), true);
 337
 338         assert_eq!(false & false, false);
 339         assert_eq!(true & false, false);
 340         assert_eq!(false & true, false);
 341         assert_eq!(true & true, true);
 342
 343         assert_eq!(false.bitor(&false), false);
 344         assert_eq!(true.bitor(&false), true);
 345         assert_eq!(false.bitor(&true), true);
 346         assert_eq!(true.bitor(&true), true);
 347
 348         assert_eq!(false | false, false);
 349         assert_eq!(true | false, true);
 350         assert_eq!(false | true, true);
 351         assert_eq!(true | true, true);
 352
 353         assert_eq!(false.bitxor(&false), false);
 354         assert_eq!(true.bitxor(&false), true);
 355         assert_eq!(false.bitxor(&true), true);
 356         assert_eq!(true.bitxor(&true), false);
 357
 358         assert_eq!(false ^ false, false);
 359         assert_eq!(true ^ false, true);
 360         assert_eq!(false ^ true, true);
 361         assert_eq!(true ^ true, false);
 362
 363         assert_eq!(!true, false);
 364         assert_eq!(!false, true);
 365
 366         assert_eq!(true.to_str(), ~"true");
 367         assert_eq!(false.to_str(), ~"false");
 368
 369         assert_eq!(from_str::<bool>("true"), Some(true));
 370         assert_eq!(from_str::<bool>("false"), Some(false));
 371         assert_eq!(from_str::<bool>("not even a boolean"), None);
 372
 373         assert_eq!(true.and(true), true);
 374         assert_eq!(true.and(false), false);
 375         assert_eq!(false.and(true), false);
 376         assert_eq!(false.and(false), false);
 377
 378         assert_eq!(true.or(true), true);
 379         assert_eq!(true.or(false), true);
 380         assert_eq!(false.or(true), true);
 381         assert_eq!(false.or(false), false);
 382
 383         assert_eq!(true.xor(true), false);
 384         assert_eq!(true.xor(false), true);
 385         assert_eq!(false.xor(true), true);
 386         assert_eq!(false.xor(false), false);
 387
 388         assert_eq!(true.implies(true), true);
 389         assert_eq!(true.implies(false), false);
 390         assert_eq!(false.implies(true), true);
 391         assert_eq!(false.implies(false), true);
 392
 393         assert_eq!(true.to_bit::<u8>(), 1u8);
 394         assert_eq!(false.to_bit::<u8>(), 0u8);
 395     }
 396
 397     #[test]
 398     fn test_bool_from_str() {
 399         all_values(|v| {
 400             assert!(Some(v) == FromStr::from_str(v.to_str()))
 401         });
 402     }
 403
 404     #[test]
 405     fn test_bool_to_str() {
 406         assert_eq!(false.to_str(), ~"false");
 407         assert_eq!(true.to_str(), ~"true");
 408     }
 409
 410     #[test]
 411     fn test_bool_to_bit() {
 412         all_values(|v| {
 413             assert_eq!(v.to_bit::<u8>(), if v { 1u8 } else { 0u8 });
 414             assert_eq!(v.to_bit::<uint>(), if v { 1u } else { 0u });
 415             assert_eq!(v.to_bit::<int>(), if v { 1i } else { 0i });
 416         });
 417     }
 418
 419     #[test]
 420     fn test_bool_ord() {
 421         assert!(true > false);
 422         assert!(!(false > true));
 423
 424         assert!(false < true);
 425         assert!(!(true < false));
 426
 427         assert!(false <= false);
 428         assert!(false >= false);
 429         assert!(true <= true);
 430         assert!(true >= true);
 431
 432         assert!(false <= true);
 433         assert!(!(false >= true));
 434         assert!(true >= false);
 435         assert!(!(true <= false));
 436     }
 437
 438     #[test]
 439     fn test_bool_totalord() {
 440         assert_eq!(true.cmp(&true), Equal);
 441         assert_eq!(false.cmp(&false), Equal);
 442         assert_eq!(true.cmp(&false), Greater);
 443         assert_eq!(false.cmp(&true), Less);
 444     }
 445 }