Merge pull request #347 from SimonRohou/codac2_dev

[doc] BoolInterval + manual style

Author: SimonRohou

doc/manual/_static/css/custom.css

@@ -176,4 +176,19 @@ a .download:before {
       linear-gradient(-45deg, transparent 75%, #ddd 75%);
   background-size: var(--size) var(--size);
   background-position: 0 0, 0 calc(var(--size)/2), calc(var(--size)/2) calc(var(--size)/-2), calc(var(--size)/-2) 0;
+}
+
+/* Adding VIBes + IPE logos in the lateral menu */
+.sidebar-tree li.toctree-l1 > a.reference.internal:has(+ input#toctree-checkbox-8) {
+  background:url("../logos/logos_vibes_ipe.png") no-repeat center / contain;
+}
+
+.sidebar-tree li.toctree-l1 > a.reference.internal:has(+ input#toctree-checkbox-8):hover {
+  background: url("../logos/logos_vibes_ipe.png") no-repeat center / contain,
+              var(--color-sidebar-item-background--hover);
+}
+
+.sidebar-tree li.toctree-l1 > a.reference.internal.current:has(+ input#toctree-checkbox-8) {
+  background: url("../logos/logos_vibes_ipe.png") no-repeat center / contain,
+              var(--color-sidebar-item-background--current);
 }

doc/manual/_static/logos/logo_ipe.png

@@ -1,5 +1,5 @@
-Contractors
-===========
+Contractors, separators
+=======================
 
 .. toctree::
 

doc/manual/_static/logos/logo_vibes.png

@@ -0,0 +1,80 @@
+.. _sec-intervals-boolinterval-class:
+
+The BoolInterval enumeration
+============================
+
+  Main author: `Simon Rohou <https://www.simon-rohou.fr/research/>`_
+
+A :class:`~codac2.BoolInterval` (Boolean interval) is a compact representation of an
+uncertain truth value. It is primarily used as a **reliable return type** for predicates
+evaluated under uncertainties (interval inputs, rounding effects, geometric tolerances, etc.).
+
+Definition
+----------
+
+Let :math:`\mathbb{B}=\{\mathsf{false},\mathsf{true}\}`. A boolean interval represents a subset
+of :math:`\mathbb{B}`: :math:`[b]\subseteq\mathbb{B}`.
+
+In Codac, ``BoolInterval`` is an enumeration of four canonical values:
+
+.. tabs::
+
+  .. group-tab:: Python
+
+    .. literalinclude:: src.py
+      :language: py
+      :start-after: [boolinterval-class-1-beg]
+      :end-before: [boolinterval-class-1-end]
+      :dedent: 4
+
+  .. group-tab:: C++
+
+    .. literalinclude:: src.cpp
+      :language: c++
+      :start-after: [boolinterval-class-1-beg]
+      :end-before: [boolinterval-class-1-end]
+      :dedent: 4
+
+
+Two useful set values are:
+
+.. tabs::
+
+  .. group-tab:: Python
+
+    .. literalinclude:: src.py
+      :language: py
+      :start-after: [boolinterval-class-2-beg]
+      :end-before: [boolinterval-class-2-end]
+      :dedent: 4
+
+  .. group-tab:: C++
+
+    .. literalinclude:: src.cpp
+      :language: c++
+      :start-after: [boolinterval-class-2-beg]
+      :end-before: [boolinterval-class-2-end]
+      :dedent: 4
+
+
+Operations on ``BoolInterval`` are documented below:
+
+.. doxygenfunction:: codac2::operator&(BoolInterval x, BoolInterval y)
+  :project: codac
+
+.. doxygenfunction:: codac2::operator|(BoolInterval x, BoolInterval y)
+  :project: codac
+
+.. doxygenfunction:: codac2::operator&&(BoolInterval x, BoolInterval y)
+  :project: codac
+
+.. doxygenfunction:: codac2::operator||(BoolInterval x, BoolInterval y)
+  :project: codac
+
+.. doxygenfunction:: codac2::operator~(BoolInterval x)
+  :project: codac
+
+
+.. admonition:: Technical documentation
+
+  See the `C++ API documentation of the BoolInterval class <../../api/html/codac2___bool_interval_8h.html>`_.

doc/manual/_static/logos/logos_vibes_ipe.png

@@ -8,6 +8,7 @@ Codac provides data structures for handling basic interval sets. These structure
 - :ref:`The Interval class <sec-intervals-class>`: represents a real bounded interval :math:`[x^{-},x^{+}]`.
 - :ref:`The IntervalVector class <sec-intervals-intervalvector-class>` (or ``IntervalRow``): represents a vector (or row) where each component is an interval.
 - ``IntervalMatrix``: represents a matrix where each element is an interval.
+- :ref:`The BoolInterval class <sec-intervals-boolinterval-class>`: represents a Boolean interval.
 
 
 .. toctree::
@@ -16,6 +17,7 @@ Codac provides data structures for handling basic interval sets. These structure
    Interval_class.rst
    .. Vector_class.rst
    IntervalVector_class.rst
+   BoolInterval_class.rst
 
 ..    What is an interval? <http://codac.io>
    The Interval class <http://codac.io>

doc/manual/manual/contractors/index.rst

@@ -14,6 +14,26 @@
 using namespace std;
 using namespace codac2;
 
+TEST_CASE("BoolInterval class - manual")
+{
+  {
+    // [boolinterval-class-1-beg]
+    BoolInterval::FALSE;   // certainly false
+    BoolInterval::TRUE;    // certainly true
+    BoolInterval::UNKNOWN; // undetermined
+    BoolInterval::EMPTY;   // inconsistent / impossible
+    // [boolinterval-class-1-end]
+  }
+  /*
+  {
+    // [boolinterval-class-2-beg]
+    BoolInterval::UNKNOWN == BoolInterval::TRUE | BoolInterval::FALSE
+    BoolInterval::EMPTY   == BoolInterval::TRUE & BoolInterval::FALSE
+    // [boolinterval-class-2-end]
+  }
+  */
+}
+
 TEST_CASE("Interval class - manual")
 {
   #if 0

doc/manual/manual/intervals/BoolInterval_class.rst

@@ -14,6 +14,21 @@
 
 class TestIntervalManual(unittest.TestCase):
 
+  def tests_BoolInterval_manual(test):
+
+    # [boolinterval-class-1-beg]
+    BoolInterval.FALSE   # certainly false
+    BoolInterval.TRUE    # certainly true
+    BoolInterval.UNKNOWN # undetermined
+    BoolInterval.EMPTY   # inconsistent / impossible
+    # [boolinterval-class-1-end]
+
+    # [boolinterval-class-2-beg]
+    BoolInterval.UNKNOWN == BoolInterval.TRUE | BoolInterval.FALSE
+    BoolInterval.EMPTY   == BoolInterval.TRUE & BoolInterval.FALSE
+    # [boolinterval-class-2-end]
+
+
   def tests_Interval_manual(test):
 
     # [interval-class-1-beg]