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
• Truth tables
• Reference
  • Header <boost/tribool.hpp> synopsis
  • Class tribool
  • Indeterminate value
  • Equality comparisons
  • Logical operators

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)

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

  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

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

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

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

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

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

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

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.