From cfc58068a86aae31ddaed12f99e6cbbacb91f3e8 Mon Sep 17 00:00:00 2001 From: Seth Schoen Date: Mon, 23 Mar 2026 14:37:09 -0700 Subject: [PATCH] Document new infix operators --- docs/documentation/rust-differences.md | 20 ++------ docs/simplicityhl-reference/operators.md | 60 ++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 65 insertions(+), 16 deletions(-) create mode 100644 docs/simplicityhl-reference/operators.md diff --git a/docs/documentation/rust-differences.md b/docs/documentation/rust-differences.md index a90459f..b51582a 100644 --- a/docs/documentation/rust-differences.md +++ b/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 jet 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. diff --git a/docs/simplicityhl-reference/operators.md b/docs/simplicityhl-reference/operators.md new file mode 100644 index 0000000..4a024c0 --- /dev/null +++ b/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.
Search `left_shift` and `left_rotate` in the jets list. | +| `>>` | Right shift | Numerous jets are available with variant behaviors.
Search `right_shift` and `right_rotate` in the jets list. | diff --git a/mkdocs.yml b/mkdocs.yml index 89dd9d0..20df318 100644 --- a/mkdocs.yml +++ b/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