Document new infix operators from PR #232

docs/documentation/rust-differences.md

@@ -24,21 +24,7 @@ fn increment(x: u8){
 }
 ```
 
-* **No infix and unary operators**: Currently, SimplicityHL does not support common infix and unary operators such as `!=`, `==`, `<=`, `>=`, `+`, `-`, `*`, `/`, `&`, `|`, `^`, `!`, and others that are found in Rust and in other languages whose syntax descends from C's. Instead, each of these operations requires an explicit call to an appropriate <a href="/documentation/jets">jet</a> to perform the comparison. (It may be possible for a future version of the SimplicityHL compiler to support these notations as syntactic sugar for the corresponding jet calls.) For example, code that might look like
-
-```rust
-if (counter3 != threshold) {
-    assert!(0);
-}
-```
-
-in other languages is written in current versions of SimplicityHL as
-
-```rust
-assert!(jet::eq_8(counter3, threshold));
-```
-
-Code that might look like
+* **No arithmetic operators**: Currently, SimplicityHL does not support the common arithmetic operators `+`, `-`, `*`, `/`, and `%` due to issues related to safe handling of arithmetic overflow and underflow conditions. Instead, each of these operations requires an explicit call to an appropriate [jet](../jets.md) to perform the comparison. (It may be possible for a future version of the SimplicityHL compiler to support these operator notations.) For example, code that might look like
 
 ```rust
 let x: u8 = 17;
@@ -52,7 +38,9 @@ let x: u8 = 17;
 let (carry, y): (bool, u8) = jet::add_8(x, 1);
 ```
 
-(as the `add_8` jet returns an explicit carry flag indicating whether the addition caused an integer overflow; the carry flag value is required to be assigned somewhere).
+since the `add_8` jet returns an explicit carry flag indicating whether the addition caused an integer overflow.
+
+[Other operators](../simplicityhl-reference/operators.md) are available since SimplicityHL *nnnn*. These include Boolean (`&&`, `||`, `!`) and bitwise (`&`, `|`, `~`, `^`) logic operators, as well as integer comparison operators (`<`, `<=`, `==`, `>=`, `>`, `!=`).
 
 * **No unbounded loops or recursion**: Simplicity is intentionally not Turing-complete, and SimplicityHL accordingly does not have a `while` loop or a `for` loop in its native syntax. Nor is a function permitted to call itself recursively. For bounded loops, there is a built-in function called `for_while` which can execute a code block up to a specified maximum number of times (limited to 65536 iterations per `for_while` loop). SimplicityHL also offers `fold` and `array_fold` functions to help with some tasks that could traditionally be performed with iteration or recursion in other languages.
 

docs/simplicityhl-reference/operators.md

@@ -0,0 +1,60 @@
+# Operators
+
+Since version *nnnn*, SimplicityHL supports some common *operators* in expressions. Their notations and meanings are similar to languages like Rust and C.
+
+## Logic operators
+
+The Boolean logic operators (operating on `bool`s and returning a `bool`) are:
+
+| Operator | Description |
+| -------- | ----------- |
+| `&&` | Boolean AND (infix) |
+| `||` | Boolean OR (infix) |
+| `!` | Boolean NOT (unary) |
+
+For example, `true || false` evaluates to `true`.
+
+The bitwise logic operators (operating on the bits within an integer type) are:
+
+| Operator | Description |
+| -------- | ----------- |
+| `&` | Bitwise AND (infix) |
+| `|` | Bitwise OR (infix) |
+| `^` | Bitwise XOR (infix) |
+| `~` | Bitwise NOT (unary) |
+
+For example, `0xb1 | 0x04` evaluates to `0xb5`.
+
+Both sides of the bitwise operator must be interpretable as *the same* integer type.
+
+## Comparison operators
+
+The comparison operators (infix) can be used to compare integer types. They return `bool`.
+
+| Operator | Description |
+| -------- | ----------- |
+| `<` | Integer less than |
+| `<=` | Integer less than or equal to |
+| `>` | Integer greater than |
+| `>=` | Integer greater than or equal to |
+| `==` | Integer equality |
+| `!=` | Integer inequality |
+
+For example, `3 <= 20` evaluates to `true`.
+
+Both sides of the comparison operator must be interpretable as *the same* integer type.
+
+## Not yet implemented
+
+These operators have not yet been implemented because of difficulties related to safely handling arithmetic overflow or underflow. In each case, [jets](../../documentation/jets) are available as an alternative.
+
+| Operator | Description | Alternative |
+| -------- | ----------- | ----------- |
+| `+` | Integer addition | `jet::add_`*nn* |
+| `-` | Integer subtraction | `jet::subtract_`*nn* |
+| `-` | Unary integer negation | Currently there is no negative number type. |
+| `*` | Integer multiplication | `jet::multiply_`*nn* |
+| `/` | Integer division | `jet::divide_`*nn* or `jet::div_mod_`*nn* |
+| `%` | Integer modulo | `jet::modulo_`*nn* or `jet::div_mod_`*nn* |
+| `<<` | Left shift | Numerous jets are available with variant behaviors.<br>Search `left_shift` and `left_rotate` in the jets list. |
+| `>>` | Right shift | Numerous jets are available with variant behaviors.<br>Search `right_shift` and `right_rotate` in the jets list. |

mkdocs.yml

@@ -173,6 +173,7 @@ nav:
       - simplicityhl-reference/index.md
       - Jets Reference: documentation/jets.md
       - Toolchain Reference: documentation/toolchain.md
+      - Operator Notations: simplicityhl-reference/operators.md
       - Environment: simplicityhl-reference/environment.md
       - Translation: simplicityhl-reference/translation.md
       - Whitepaper: https://blockstream.com/simplicity.pdf