Merge pull request #227 from final-hill:feature-iff-225

Implemented `iff` function

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## v0.22.0
 
 * Added `implies` function
+* Added `iff` function
 * Added topic tags to github repo
 * Updated `package.json` keywords
 

README.md

@@ -12,6 +12,7 @@
 - [Checked Mode](#checked-mode)
 - [Assertions](#assertions)
 - [Implies](#implies)
+- [Iff](#iff)
 - [Overrides](#overrides)
 - [Encapsulation](#encapsulation)
 - [Invariants](#invariants)
@@ -272,6 +273,31 @@ implies(
 
 This is logically equivalent to: `!p || q`
 
+## Iff
+
+When defining predicates it is a common use case to encode [if and only if](https://en.wikipedia.org/wiki/Logical_biconditional).
+Also referred to as a biconditional.
+
+The truth table is as follows:
+
+| *p* | *q* | *p* ↔ *q* |
+|-----|-----|----------------|
+|  T   |   T   |  T          |
+|  T   |   F   |  F          |
+|  F   |   T   |  F          |
+|  F   |   F   |  T          |
+
+An example of usage is the encoding of `You can ride the train if and only if you have a ticket`:
+
+```ts
+iff(
+    person.hasTicket,
+    person.ridesTrain
+)
+```
+
+This is logically equivalent to: `implies(p,q) && implies(q,p)`
+
 ## Overrides
 
 Class features implemented in a base class can be overridden in a subclass. The

package.json

@@ -43,13 +43,15 @@
     },
     "keywords": [
         "assertion",
+        "biconditional",
         "behavioral-subtyping",
         "code-contracts",
         "decorators",
         "demands",
         "design-by-contract",
         "encapsulation",
         "exception-handling",
+        "if-and-only-if",
         "invariant",
         "liskov-substitution-principle",
         "LSP",

src/iff.ts

@@ -0,0 +1,24 @@
+/*!
+ * @license
+ * Copyright (C) 2021 Final Hill LLC
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * @see <https://spdx.org/licenses/AGPL-3.0-only.html>
+ */
+
+/**
+ * Biconditional.
+ * p ↔ q.
+ * "P if and only if Q".
+ * An example of usage is the encoding of "You can ride the train if and only if you have a ticket"
+ * This is logically equivalent to: implies(p,q) && implies(q,p)
+ *
+ * @example
+ * iff(person.hasTicket, person.ridesTrain)
+ *
+ * @param {boolean} p - The antecedent
+ * @param {boolean} q - The consequent
+ * @returns {boolean} - The result
+ */
+export default function iff(p: boolean, q: boolean): boolean {
+    return (p && q) || (!p && !q);
+}

src/tests/iff.test.ts

@@ -0,0 +1,25 @@
+/*!
+ * @license
+ * Copyright (C) 2021 Final Hill LLC
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * @see <https://spdx.org/licenses/AGPL-3.0-only.html>
+ */
+import iff from '../iff';
+
+// https://github.com/final-hill/decorator-contracts/issues/225
+describe('Biconditional tests', () => {
+    test('Truth Table', () => {
+        /*
+            p    q    p ↔ q
+            ---------------
+            T    T      T
+            T    F      F
+            F    T      F
+            F    F      T
+        */
+        expect(iff(true,true)).toBe(true);
+        expect(iff(true,false)).toBe(false);
+        expect(iff(false,true)).toBe(false);
+        expect(iff(false,false)).toBe(true);
+    });
+});