feat: Update of the Book→Operators page (#205)

novusnota · web-flow · commit 9bba642d3297 · 2024-05-06T09:24:26.000+04:00
* feat: Update of the Book→Operators page

* All precedences match Tact 1.3.0
* Added bitwise XOR operator `^`
* Fixed minor typos and corrected some descriptions
* Added a table of operators in decreasing order of their precedences

Note, that the only link leading to Language section now has a proper link to the Reference section.
This is intentional, as the Lang-&gt;Ref rename is almost there :)

* chore: reset alignment

* chore: corrected highlighting

* fix/feat: applied suggestions from a code review

* Property of division rounding down (division of real numbers without rounding them down won't have such property)
* Rounding towards -∞ mentioned and explained
* Bit masking example reference
diff --git a/pages/book/message-mode.mdx b/pages/book/message-mode.mdx
@@ -25,7 +25,7 @@ $+32$      | `SendDestroyIfZero{:tact}`      | Current account must be destroyed
 
 ## Combining modes with flags
 
-To make the [`Int{:tact}`][int] value for `mode` field of SendParameters, you just have to combine base modes with optional flags by applying the [`bitwise OR{:tact}`](/book/operators#binary-bitwise-or) operation.
+To make the [`Int{:tact}`][int] value for `mode` field of `SendParameters{:tact}`, you just have to combine base modes with optional flags by applying the [`bitwise OR{:tact}`](/book/operators#binary-bitwise-or) operation.
 
 For example, if you want to send a regular message and pay transfer fees separately, use the mode $0$ (default) and a flag $+1$ to get `mode` $= 1$, which is equal to using `SendPayGasSeparately{:tact}` constant.
 
diff --git a/pages/book/operators.mdx b/pages/book/operators.mdx
@@ -8,10 +8,67 @@ This page lists all the operators in Tact in decreasing order of their [preceden
 
 <Callout>
 
-  Note, that there are no implicit type conversions in Tact, so operators can't be used to, say, add values of different type or compare them in terms of equality without explicitly casting to the same type. That's done with certain functions from the standard library. See [`Int.toString(){:tact}`](/language/ref/strings#inttostring) for an example of such function.
+  Note, that there are no implicit type conversions in Tact, so operators can't be used to, say, add values of different type or compare them in terms of equality without explicitly casting to the same type. That's done with certain functions from the standard library. See [`Int.toString(){:tact}`](/ref/api-strings#inttostring) for an example of such function.
 
 </Callout>
 
+## Table of operators [#table]
+
+The following table lists operators in order of decreasing [precedence](#precedence): from highest to lowest.
+
+Brief description | Operators
+:---------------- | :--------------------------------------------------------------------
+Parentheses       | [`(){:tact}`][paren]
+Unary postfix     | [`!!{:tact}`][nna]
+Unary prefix      | [`+{:tact}`][plus] &nbsp; [`-{:tact}`][neg] &nbsp; [`!{:tact}`][inv]
+Multiplicative    | [`*{:tact}`][mul] &nbsp; [`/{:tact}`][div] &nbsp; [`%{:tact}`][mod]
+Additive          | [`+{:tact}`][add] &nbsp; [`-{:tact}`][sub]
+Shift             | [`>>{:tact}`][shr] &nbsp; [`<<{:tact}`][shl]
+Relation          | [`>{:tact}`][gt] &nbsp; [`>={:tact}`][ge] &nbsp; [`<{:tact}`][lt] &nbsp; [`<={:tact}`][le]
+Equality          | [`=={:tact}`][eq] &nbsp; [`!={:tact}`][eq]
+Bitwise AND       | [`&{:tact}`][b-and]
+Bitwise XOR       | [`^{:tact}`][b-xor]
+Bitwise OR        | [`\|{:tact}`][b-or]
+Logical AND       | [`&&{:tact}`][l-and]
+Logical OR        | [`\|\|{:tact}`][l-or]
+Ternary           | [`?:{:tact}`][ternary]
+Assignment        | [`={:tact}`][assign]
+
+[paren]: #parentheses
+
+[nna]: #unary-non-null-assert
+[plus]: #unary-plus
+[neg]: #unary-negate
+[inv]: #unary-inverse
+
+[mul]: #binary-multiply
+[div]: #binary-divide
+[mod]: #binary-modulo
+
+[add]: #binary-add
+[sub]: #binary-subtract
+
+[shr]: #binary-bitwise-shift-right
+[shl]: #binary-bitwise-shift-left
+
+[gt]: #binary-greater
+[ge]: #binary-greater-equal
+[lt]: #binary-less
+[le]: #binary-less-equal
+
+[eq]: #binary-equality
+
+[b-and]: #binary-bitwise-and
+[b-xor]: #binary-bitwise-xor
+[b-or]: #binary-bitwise-or
+
+[l-and]: #binary-logical-and
+[l-or]: #binary-logical-or
+
+[ternary]: #ternary
+
+[assign]: #assignment
+
 ## Precedence
 
 All operators on this page are given in order of decreasing precedence, from highest to lowest. Precedence is used to choose which operator would be considered in a particular situation. Whenever any ambiguity arises, Tact would prefer operators with higher precedence over those with lower.
@@ -27,7 +84,7 @@ Consider the following code:
 
 Even though this example may be simple, neglection of precedence rules can often lead to confusing situations with operators. The correct order of operations can be ensured by wrapping every operation in [parentheses](#parentheses), since parentheses have the highest precedence of all expressions and operators there is.
 
-## Parentheses, `()`
+## Parentheses, `()` [#parentheses]
 
 Parentheses (also can be called round brackets, `(){:tact}`) are more of a punctuation symbols than actual operators, but their [precedence](#precedence) is higher than precedence of any other operator. Use parentheses to override order of operations:
 
@@ -107,17 +164,36 @@ pow(2, 255) * pow(2, 255); // build error: integer overflow!
 
 #### Divide, `/` [#binary-divide]
 
-Binary slash (_division_) operator `/{:tact}` is used for integer division of two values, which truncates towards zero. An attempt to divide by zero would result in an error with [exit code 4](/book/exit-codes#4): `Integer overflow`.
+Binary slash (_division_) operator `/{:tact}` is used for integer division of two values, which truncates towards zero if result is positive, and away from zero if result is negative. This is also called [rounding down](https://en.wikipedia.org/wiki/Rounding#Rounding_down) (or rounding towards $-∞$).
+
+An attempt to divide by zero would result in an error with [exit code 4](/book/exit-codes#4): `Integer overflow`.
 
 Can only be applied to values of type [`Int{:tact}`][int]:
 
 ```tact
 let two: Int = 2;
 two / 2; // 1
-two / 1; // 2
+two / 1; // 0
 -1 / 5;  // -1
+-1 / -5; // 0
+1 / -5;  // -1
+1 / 5;   // 0
+6 / 5;   // 1, rounding down
+-6 / 5;  // -2, rounding down (towards -∞)
 ```
 
+<Callout>
+
+  Note that the following relationship between the division and modulo operators always holds for `Int{:tact}` type:
+
+  ```tact
+  a / b * b + a % b == a; // true for any Int values of `a` and `b`,
+                          //   except when `b` is equal to 0 and we divide `a` by 0,
+                          //   which is an attempt to divide by zero resulting in an error
+  ```
+
+</Callout>
+
 #### Modulo, `%` [#binary-modulo]
 
 Binary percent sign (_modulo_) operator `%{:tact}` is used for getting the modulo of an integer division, which must not be confused with getting a remainder. For two values of the same sign, modulo and remainder operations are equivalent, but when the operands are of different signs, the modulo result always has the same sign as the _divisor_ (value on the right), while the remainder has the same sign as the _dividend_ (value on the left), which can make them differ by one unit of the _divisor_.
@@ -127,15 +203,15 @@ Can only be applied to values of type [`Int{:tact}`][int]:
 ```tact
 let two: Int = 2;
 two % 2; // 0
-1 % two; // 1
+two % 1; // 1
 
 1 % 5;   // 1
 -1 % 5;  // 4
 1 % -5;  // -4
 -1 % -5; // -1
 ```
 
-The simplest way to avoid confusion between the two is to prefer using positive values via [`abs(x: Int){:tact}`](/language/ref/math#abs):
+The simplest way to avoid confusion between the two is to prefer using positive values via [`abs(x: Int){:tact}`](/ref/api-math#abs):
 
 ```tact
 abs(-1) % abs(-5); // 1
@@ -185,9 +261,9 @@ pow(2, 255) - pow(2, 255); // 0
 pow(2, 256) - pow(2, 256); // build error: integer overflow!
 ```
 
-### Bitwise [#binary-bitwise]
+### Bitwise shifts [#binary-bitwise-shifts]
 
-Manipulate individual bits.
+Shift bits to the left or to the right.
 
 #### Shift right, `>>` [#binary-bitwise-shift-right]
 
@@ -213,7 +289,7 @@ pow(2, 254) >> 254; // 1
 
 #### Shift left, `<<` [#binary-bitwise-shift-left]
 
-Binary double greater than (_bitwise shift right_) operator `<<{:tact}` returns an integer which binary representation is the _left operand_ value shifted by the _right operand_ number of bits to the left. Excess bits shifted off to the left are discarded, and zero bits are shifted in from the right. This is a more effective way to multiply the _left operand_ by $2^n$, where $n$ is equal to the _right operand_. Going beyond the maximum value of an [`Int{:tact}`][int] will result in an error with [exit code 4](/book/exit-codes#4): `Integer overflow`.
+Binary double greater than (_bitwise shift left_) operator `<<{:tact}` returns an integer which binary representation is the _left operand_ value shifted by the _right operand_ number of bits to the left. Excess bits shifted off to the left are discarded, and zero bits are shifted in from the right. This is a more effective way to multiply the _left operand_ by $2^n$, where $n$ is equal to the _right operand_. Going beyond the maximum value of an [`Int{:tact}`][int] will result in an error with [exit code 4](/book/exit-codes#4): `Integer overflow`.
 
 Can only be applied to values of type [`Int{:tact}`][int]:
 
@@ -235,57 +311,51 @@ pow(2, 255) == 1 << 255; // true, but we're very close to overflow here!
 
 </Callout>
 
-#### Bitwise AND, `&` [#binary-bitwise-and]
+### Relation [#binary-relation]
 
-Binary ampersand (_bitwise and_) operator `&{:tact}` applies a [bitwise AND](https://en.wikipedia.org/wiki/Bitwise_operation#AND), which performs the [logical AND](#binary-logical-and) operation on each pair of the corresponding bits of operands. This is useful when we want to clear selected bits off a number, where each bit represents an individual flag or a boolean state, which makes it possible to "store" up to $257$ boolean values per integer, as all integers in Tact are $257$-bit signed.
+Find bigger, smaller or equal values.
 
-Can only be applied to values of type [`Int{:tact}`][int]:
+#### Greater than, `>` [#binary-greater]
+
+Binary _greater than_ operator `>{:tact}` returns `true{:tact}` if the left operand is greater than the right operand, and `false{:tact}` otherwise. Can only be applied to values of type [`Int{:tact}`][int]:
 
 ```tact
 let two: Int = 2;
-two & 1;          // 0
-4 & 1;            // 0
-3 & 1;            // 1
-1 & 1;            // 1
-255 & 0b00001111; // 15
+two > 2; // false
+-1 > -3; // true
 ```
 
-<Callout>
-
-  [Bitwise AND - Wikipedia](https://en.wikipedia.org/wiki/Bitwise_operation#AND)\
-  [Bit manipulation - Wikipedia](https://en.wikipedia.org/wiki/Bit_manipulation)
+#### Greater than or equal to, `>=` [#binary-greater-equal]
 
-</Callout>
+Binary _greater than or equal to_ operator `>={:tact}` returns `true{:tact}` if the left operand is greater than or to the right operand, and `false{:tact}` otherwise. Can only be applied to values of type [`Int{:tact}`][int]:
 
-#### Bitwise OR, `|` [#binary-bitwise-or]
+```tact
+let two: Int = 2;
+two >= 2; // true
+-1 >= -3; // true
+```
 
-Binary bar (_bitwise or_) operator `|{:tact}` applies a [bitwise OR](https://en.wikipedia.org/wiki/Bitwise_operation#OR), which performs the [logical OR](#binary-logical-or) operation on each pair of the corresponding bits of operands. This is useful when we want to apply a specific [bitmask](https://en.wikipedia.org/wiki/Mask_(computing)).
+#### Less than, `<` [#binary-less]
 
-Can only be applied to values of type [`Int{:tact}`][int]:
+Binary _less than_ operator `<{:tact}` returns `true{:tact}` if the left operand is less than the right operand, and `false{:tact}` otherwise. Can only be applied to values of type [`Int{:tact}`][int]:
 
 ```tact
 let two: Int = 2;
-two | 1; // 3
-4 | 1;   // 5
-3 | 1;   // 3
-1 | 1;   // 1
-
-255 | 0b00001111;        // 255
-0b11110000 | 0b00001111; // 255
+two < 2; // false
+-1 < -3; // false
 ```
 
-<Callout>
-
-  [Bitwise OR - Wikipedia](https://en.wikipedia.org/wiki/Bitwise_operation#OR)\
-  [Bit manipulation - Wikipedia](https://en.wikipedia.org/wiki/Bit_manipulation)
-
-</Callout>
+#### Less than or equal to, `<=` [#binary-less-equal]
 
-### Comparison [#binary-comparison]
+Binary _less than or equal to_ operator `<={:tact}` returns `true{:tact}` if the left operand is less than or equal to the right operand, and `false{:tact}` otherwise. Can only be applied to values of type [`Int{:tact}`][int]:
 
-Perform inequality and equality checks, find bigger, smaller or equal values.
+```tact
+let two: Int = 2;
+two <= 2; // true
+-1 <= -3; // false
+```
 
-#### Equal and not equal, `==` `!=` [#binary-equality]
+### Equality and inequality, `==` `!=` [#binary-equality]
 
 Binary equality (_equal_) operator `=={:tact}` checks whether its two operands are _equal_, returning a result of type [`Bool{:tact}`][bool].
 
@@ -347,46 +417,82 @@ nullable == anotherNullable; // false
 nullable != anotherNullable; // true
 ```
 
-#### Greater than, `>` [#binary-greater]
+### Bitwise AND, `&` [#binary-bitwise-and]
 
-Binary _greater than_ operator `>{:tact}` returns `true{:tact}` if the left operand is greater than the right operand, and `false{:tact}` otherwise. Can only be applied to values of type [`Int{:tact}`][int]:
+Binary ampersand (_bitwise AND_) operator `&{:tact}` applies a [bitwise AND](https://en.wikipedia.org/wiki/Bitwise_operation#AND), which performs the [logical AND](#binary-logical-and) operation on each pair of the corresponding bits of operands. This is useful when we want to clear selected bits off a number, where each bit represents an individual flag or a boolean state, which makes it possible to "store" up to $257$ boolean values per integer, as all integers in Tact are $257$-bit signed.
+
+Can only be applied to values of type [`Int{:tact}`][int]:
 
 ```tact
 let two: Int = 2;
-two > 2; // false
--1 > -3; // true
+two & 1; // 0
+4 & 1;   // 0
+3 & 1;   // 1
+1 & 1;   // 1
+
+255 & 0b00001111;        // 15
+0b11110000 & 0b00001111; // 15
 ```
 
-#### Greater than or equal to, `>=` [#binary-greater-equal]
+<Callout>
 
-Binary _greater than or equal to_ operator `>={:tact}` returns `true{:tact}` if the left operand is greater than or to the right operand, and `false{:tact}` otherwise. Can only be applied to values of type [`Int{:tact}`][int]:
+  [Bitwise AND - Wikipedia](https://en.wikipedia.org/wiki/Bitwise_operation#AND)\
+  [Bit manipulation - Wikipedia](https://en.wikipedia.org/wiki/Bit_manipulation)
 
-```tact
-let two: Int = 2;
-two >= 2; // true
--1 >= -3; // true
-```
+</Callout>
 
-#### Less than, `<` [#binary-less]
+### Bitwise XOR, `^` [#binary-bitwise-xor]
 
-Binary _less than_ operator `<{:tact}` returns `true{:tact}` if the left operand is less than the right operand, and `false{:tact}` otherwise. Can only be applied to values of type [`Int{:tact}`][int]:
+Binary caret (_bitwise XOR_) operator `^{:tact}` applies a [bitwise XOR](https://en.wikipedia.org/wiki/Bitwise_operation#XOR), which performs the [logical exclusive OR](https://en.wikipedia.org/wiki/Exclusive_or) operation on each pair of the corresponding bits of operands. The result in each position is $1$ if only one of the bits is $1$, but will be $0$ if both are $0$ or both are $1$. In this it performs the comparison of two bits, giving $1$ if the two bits are different, and $0$ if they are the same.
+
+It is useful for inverting selected bits of an operand (also called toggle or flip), as any bit may be toggled by "XORing" it with $1$.
+
+Can only be applied to values of type [`Int{:tact}`][int]:
 
 ```tact
 let two: Int = 2;
-two < 2; // false
--1 < -3; // false
+two ^ 3; // 1
+4 ^ 1;   // 0
+3 ^ 1;   // 3
+1 ^ 1;   // 0
+
+255 ^ 0b00001111;        // 240
+0b11110000 ^ 0b00001111; // 240
 ```
 
-#### Less than or equal to, `<=` [#binary-less-equal]
+<Callout>
 
-Binary _less than or equal to_ operator `<={:tact}` returns `true{:tact}` if the left operand is less than or equal to the right operand, and `false{:tact}` otherwise. Can only be applied to values of type [`Int{:tact}`][int]:
+  [Bitwise XOR - Wikipedia](https://en.wikipedia.org/wiki/Bitwise_operation#XOR)\
+  [Bit manipulation - Wikipedia](https://en.wikipedia.org/wiki/Bit_manipulation)
+
+</Callout>
+
+### Bitwise OR, `|` [#binary-bitwise-or]
+
+Binary bar (_bitwise OR_) operator `|{:tact}` applies a [bitwise OR](https://en.wikipedia.org/wiki/Bitwise_operation#OR), which performs the [logical OR](#binary-logical-or) operation on each pair of the corresponding bits of operands. This is useful when we want to apply a specific [bitmask](https://en.wikipedia.org/wiki/Mask_(computing)).
+
+For example, _bitwise OR_ is commonly used in Tact to [combine base modes with optional flags](http://localhost:3000/book/message-mode#combining-modes-with-flags) by masking specific bits to $1$ in order to construct a target [message `mode`](/book/message-mode).
+
+Can only be applied to values of type [`Int{:tact}`][int]:
 
 ```tact
 let two: Int = 2;
-two <= 2; // true
--1 <= -3; // false
+two | 1; // 3
+4 | 1;   // 5
+3 | 1;   // 3
+1 | 1;   // 1
+
+255 | 0b00001111;        // 255
+0b11110000 | 0b00001111; // 255
 ```
 
+<Callout>
+
+  [Bitwise OR - Wikipedia](https://en.wikipedia.org/wiki/Bitwise_operation#OR)\
+  [Bit manipulation - Wikipedia](https://en.wikipedia.org/wiki/Bit_manipulation)
+
+</Callout>
+
 ### Logical AND, `&&` [#binary-logical-and]
 
 Binary logical AND ([logical conjunction](https://en.wikipedia.org/wiki/Logical_conjunction)) operator `&&{:tact}` returns `true{:tact}` if both operands are `true{:tact}`, and `false{:tact}` otherwise. It's short-circuited, meaning that it would immediately evaluate the whole expression as `false{:tact}` if the left operand is `false{:tact}`, without evaluating the right one.
@@ -395,7 +501,7 @@ Can only be applied to values of type [`Bool{:tact}`][bool]:
 
 ```tact
 let iLikeTact: Bool = true;
-iLikeTact && true;  // true
+iLikeTact && true;  // true, evaluated both operands
 iLikeTact && false; // false, evaluated both operands
 false && iLikeTact; // false, didn't evaluate iLikeTact
 ```
@@ -408,9 +514,9 @@ Can only be applied to values of type [`Bool{:tact}`][bool]:
 
 ```tact
 let iLikeSnails: Bool = false;
-iLikeSnails && true;  // true
-iLikeSnails && false; // false, evaluated both operands
-true && iLikeSnails;  // true, didn't evaluate iLikeSnails
+iLikeSnails || true;  // true, evaluated both operands
+iLikeSnails || false; // false, evaluated both operands
+true || iLikeSnails;  // true, didn't evaluate iLikeSnails
 ```
 
 ## Ternary, `?:` [#ternary]
@@ -443,7 +549,7 @@ false ? 1 : true ? 2 : 3;    // 2
 // need additional parentheses for consequence cases (parts in-between ? and :)
 false ? (false ? 1 : 2) : 3; // 3
 false ? false ? 1 : 2 : 3;   // SYNTAX ERROR!
-true ? (false ? 1 : 2) : 3;  // 2
+true  ? (false ? 1 : 2) : 3; // 2
 ```
 
 ## Assignment, `=` [#assignment]
