From 515cc287b432f9c38e2fba8d46cdf8635914fe35 Mon Sep 17 00:00:00 2001 From: Douglas Gregor Date: Mon, 22 Sep 2003 01:26:29 +0000 Subject: [PATCH] Useless now that we have BoostBook documentation [SVN r1585] --- doc/tribool.html | 541 ----------------------------------------------- 1 file changed, 541 deletions(-) delete mode 100644 doc/tribool.html diff --git a/doc/tribool.html b/doc/tribool.html deleted file mode 100644 index aa6e2de..0000000 --- a/doc/tribool.html +++ /dev/null @@ -1,541 +0,0 @@ - - - - 3-State Boolean Library - - - -

3-State Boolean Library

- -

The 3-state boolean library contains a single class, tribool, along with support functions and operator overloads that implement 3-state boolean logic. - -

Table of Contents

- - -

Usage

 -

The tribool class acts like the built-in bool type, but for 3-state boolean logic. The three states are true, false, and indeterminate, where the first two states are equivalent to those of the C++ bool type and the last state represents an unknown boolean value (that may be true or false, we don't know). - -

The tribool class supports conversion from bool values and literals along with its own indeterminate keyword: -

-  tribool b(true);
-  b = false;
-  b = indeterminate;
-  tribool b2(b);
-
- -

tribool supports conversions to bool for use in conditional statements. The conversion to bool will be true when the value of the tribool is always true, and false otherwise. -

-  tribool b = some_operation();
-  if (b) {
-    // b is true
-  }
-  else if (!b) {
-    // b is false
-  }
-  else {
-    // b is indeterminate
-  }
-
- -

tribool supports the 3-state logic operators ! (negation), && (AND), and || (OR), with bool and tribool values. For instance: -

-  tribool x = some_op();
-  tribool y = some_other_op();
-  if (x && y) {
-    // both x and y are true
-  }
-  else if (!(x && y)) {
-    // either x or y is false
-  }
-  else {
-    // neither x nor y is false, but we don't know that both are true
-
-    if (x || y) {
-      // either x or y is true, or both
-    }
-  }
-
- -

Similarly, tribool supports 3-state equality comparisons via the operators == and !=. These operators differ from "normal" equality operators in C++ because they return a tribool, because potentially we might not know the result of a comparison (try to compare true and indeterminate). For example: -

-  tribool x(true);
-  tribool y(indeterminate);
-
-  assert(x == x); // okay, x == x returns true
-  assert(!(y == y)); // okay, because y == y is indeterminate 
-  assert(x == true); // okay, can compare tribools and bools
-
- -

See the set of truth tables or the reference documentation for the exact semantics of these operators. - -

The indeterminate keyword (representing the indeterminate tribool value) doubles as a function to check if the value of a tribool is indeterminate, e.g., -

-  tribool x = try_to_do_something_tricky();
-  if (indeterminate(x)) {
-    // value of x is indeterminate
-  }
-  else {
-    // report success or failure of x
-  }
-
- -

Users may introduce additional keywords for the indeterminate value in addition to the implementation-supplied indeterminate using the BOOST_TRIBOOL_THIRD_STATE macro. For instance, the following macro instantiation (at the global scope) will introduce the keyword maybe as a synonym for indeterminate (also residing in the boost namespace): -

-  BOOST_TRIBOOL_THIRD_STATE(maybe)
-
- -

Truth Tables

 -

- - - - - - - - - - - - -
- - - - - - - - -
p!p
false
true
true
false
indeterminate
indeterminate
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
==
false
true
indeterminate
false
true
false
indeterminate
true
false
true
indeterminate
indeterminate
indeterminate
indeterminate
indeterminate
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
!=
false
true
indeterminate
false
false
true
indeterminate
true
true
false
indeterminate
indeterminate
indeterminate
indeterminate
indeterminate
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
&&
false
true
indeterminate
false
false
false
false
true
false
true
indeterminate
indeterminate
false
indeterminate
indeterminate
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
||
false
true
indeterminate
false
false
true
indeterminate
true
true
true
true
indeterminate
indeterminate
true
indeterminate
-
- -

Reference

-

Header <boost/tribool.hpp> synopsis

 -
-  namespace boost {
-    class tribool;
-
-    // Indeterminate value
-    struct indeterminate_t;
-    typedef bool (*indeterminate_keyword_t)(tribool, indeterminate_t);
-    bool indeterminate(tribool, indeterminate_t = indeterminate_t());
-
-    // Equality comparisons
-    tribool operator==(tribool, bool);
-    tribool operator==(bool, tribool);
-    tribool operator==(indeterminate_keyword_t, tribool);
-    tribool operator==(tribool, indeterminate_keyword_t);
-    tribool operator==(tribool, tribool);
-
-    tribool operator!=(tribool, bool);
-    tribool operator!=(bool, tribool);
-    tribool operator!=(indeterminate_keyword_t, tribool);
-    tribool operator!=(tribool, indeterminate_keyword_t);
-    tribool operator!=(tribool, tribool);   
-
-    // Logical operators
-    tribool operator&&(tribool, bool);
-    tribool operator&&(bool, tribool);
-    tribool operator&&(indeterminate_keyword_t, tribool);
-    tribool operator&&(tribool, indeterminate_keyword_t);
-    tribool operator&&(tribool, tribool);
-
-    tribool operator||(tribool, bool);
-    tribool operator||(bool, tribool);
-    tribool operator||(indeterminate_keyword_t, tribool);
-    tribool operator||(tribool, indeterminate_keyword_t);
-    tribool operator||(tribool, tribool);
-  } // end namespace boost
-
- -

Class tribool

 -

The tribool class is a 3-state boolean value type that emulates the syntax and, to some extent, the semantics of the built-in bool type. -

-  namespace boost {
-    class tribool {
-      typedef implementation-defined safe_bool; // See tribool conversions
-
-    public:
-      // Constructors
-      tribool();
-      tribool(bool);
-      tribool(indeterminate_keyword_t);
-
-      // Boolean conversion
-      operator safe_bool() const;
-      
-      // Logical negation
-      tribool operator!();
-
-      // Value
-      enum { false_value, true_value, indeterminate_value } value;
-    };
-  } // end namespace boost
-
- -

tribool constructors

 -
    -
  1. tribool(); -
      -
    • Postconditions: value == false_value
      • -
    • Throws: will not throw
      • -
    - -
  2. tribool(bool x); -
      -
    • Postconditions: value == x? true_value : false_value
      • -
    • Throws: will not throw
      • -
    - -
  3. tribool(indeterminate_keyword_t); -
      -
    • Postconditions: value == indeterminate_value
      • -
    • Throws: will not throw
      • -
    -
- -

tribool conversions

 -
    -
  1. operator safe_bool(); -
      -
    • Returns: a value that will evaluate true in a boolean context if value == true_value or that will evaluate false in a boolean context if value != true_value.
      • -
    • Throws: will not throw
      • -
    -
- -

tribool logical negation

 -
    -
  1. tribool operator!() const; -
      -
    • Returns: the logical negation of the 3-state boolean value, according to the following negation table: - - - - - - - - -
      p!p
      false
      true
      true
      false
      indeterminate
      indeterminate
      -
      • -
    • Throws: will not throw
      • -
    -
- -

Indeterminate value

 -
    -
  1. The indeterminate function has a dual purpose: it determines whether or not a tribool has an indeterminate value but also acts as a keyword for the indeterminate value.
    -[Example - -
    -  tribool x;
-  x = true; // okay, x is true
-  x = indeterminate; // okay, x has an indeterminate value
-
    - end example] - -
  2. The indeterminate_t type is a tag that makes the signature of the indeterminate function unique.
    - struct indeterminate_t {}; - -
  3. The type of the indeterminate function is used to recognize indeterminate as a value.
    - typedef bool (*indeterminate_keyword_t)(tribool, indeterminate_t); - -
  4. bool indeterminate(tribool x, indeterminate_t = indeterminate_t()); -
      -
    • Returns: x.value == tribool::indeterminate_value
      • -
    • Throws: will not throw
      • -
    -
- -

Equality Comparisons

 -
    -
  1. -
    -tribool operator==(tribool x, bool y);
-tribool operator==(bool x, tribool y);
-tribool operator==(indeterminate_keyword_t x, tribool y);
-tribool operator==(tribool x, indeterminate_keyword_t y);
-tribool operator==(tribool x, tribool y);
-
    -
      -
    • Returns: the result of comparing two 3-state boolean values, according to the following table: - - - - - - - - - - - - - - - - - - - - - - - - - -
      ==
      false
      true
      indeterminate
      false
      true
      false
      indeterminate
      true
      false
      true
      indeterminate
      indeterminate
      indeterminate
      indeterminate
      indeterminate
      -
    • Throws: will not throw
      • -
    - -
  2. -
    -tribool operator!=(tribool x, bool y);
-tribool operator!=(bool x, tribool y);
-tribool operator!=(indeterminate_keyword_t x, tribool y);
-tribool operator!=(tribool x, indeterminate_keyword_t y);
-tribool operator!=(tribool x, tribool y);
-
    -
      -
    • Returns: the negated result of comparing two 3-state boolean values, according to the following table: - - - - - - - - - - - - - - - - - - - - - - - - - -
      !=
      false
      true
      indeterminate
      false
      false
      true
      indeterminate
      true
      true
      false
      indeterminate
      indeterminate
      indeterminate
      indeterminate
      indeterminate
      -
    • Throws: will not throw
      • -
    -
- -

Logical Operators

 -
    -
  1. -
    -tribool operator&&(tribool x, bool y);
-tribool operator&&(bool x, tribool y);
-tribool operator&&(indeterminate_keyword_t x, tribool y);
-tribool operator&&(tribool x, indeterminate_keyword_t y);
-tribool operator&&(tribool x, tribool y);
-
    -
      -
    • Returns: the result of a logical AND of two 3-state boolean values, according to the following table: - - - - - - - - - - - - - - - - - - - - - - - - - -
      &&
      false
      true
      indeterminate
      false
      false
      false
      false
      true
      false
      true
      indeterminate
      indeterminate
      false
      indeterminate
      indeterminate
      -
    • Throws: will not throw
      • -
    - -
  2. -
    -tribool operator||(tribool x, bool y);
-tribool operator||(bool x, tribool y);
-tribool operator||(indeterminate_keyword_t x, tribool y);
-tribool operator||(tribool x, indeterminate_keyword_t y);
-tribool operator||(tribool x, tribool y);
-
    -
      -
    • Returns: the result of the logical OR of two 3-state boolean values, according to the following table: - - - - - - - - - - - - - - - - - - - - - - - - - -
      ||
      false
      true
      indeterminate
      false
      false
      true
      indeterminate
      true
      true
      true
      true
      indeterminate
      indeterminate
      true
      indeterminate
      -
    • Throws: will not throw
      • -
    -
-
-

© Copyright Douglas Gregor 2002. Permission to copy, - use, modify, sell and distribute this document is granted provided this - copyright notice appears in all copies. This document is provided "as is" - without express or implied warranty, and with no claim as to its - suitability for any purpose. -

- - -Last modified: Fri Aug 2 13:08:52 EDT 2002 - - -