Merge branch 'main' into virtual-function

Author: anton-trunov

pages/book/contracts.mdx

@@ -80,9 +80,6 @@ contract Example {
     const StateDelivered: Int = 2;
     const StateDisputed: Int = 3;
 
-    // no need to init constants
-    init() {}
-
     get fun sum(): Int {
         // access constants from anywhere
         return GlobalConst1 + self.ContractConst1 + self.StatePaid;
@@ -111,6 +108,14 @@ contract Example {
 }
 ```
 
+If a contract doesn't have any persistent state variables, or they all have their default value specified, it may omit the `init(){:tact}` function declaration altogether. That's because unless explicitly declared, the empty `init(){:tact}` function is present by default in all contracts.
+
+The following is an example of a valid empty contract:
+
+```tact
+contract IamEmptyAndIknowIt {}
+```
+
 <Callout>
 
   To obtain initial state of the target contract in [internal functions](#internal-functions), [receivers](#receiver-functions) or [getters](#getter-functions) use [`initOf{:tact}`](/book/expressions#initof) expression.
@@ -201,7 +206,6 @@ They can only be called from [receivers](#receiver-functions), [getters](#getter
 ```tact
 contract Functions {
     val: Int = 0;
-    init() {}
 
     // this contract method can only be called from within this contract and access its variables
     fun onlyZeros() {

pages/book/exit-codes.mdx

@@ -175,9 +175,7 @@ Example:
 1. First, define an empty contract like below:
 
 ```tact
-contract Fireworks {
-    init() {}
-}
+contract Fireworks {}
 ```
 
 2. Then, send a message to this contract. Because no suitable operation is found, you will get this exit code.
@@ -301,4 +299,4 @@ Example:
 // fun newAddress(chain: Int, hash: Int): Address;
 // creates a new address from chain and hash values.
 let zeroAddress: Address = newAddress(-1, 0); // masterchain zero address
-```
+```

pages/book/expressions.mdx

@@ -68,17 +68,69 @@ Read more about booleans and [`Bool{:tact}`](/book/types#booleans) type in the d
 A string literal is zero or more characters enclosed in double (`"`) quotation marks. All string literals are objects of [`String{:tact}`][p] type.
 
 ```tact
-"foo"
-"1234"
+"foo";
+"1234";
+```
+
+Tact strings support a range of [escape sequences](https://en.wikipedia.org/wiki/Escape_sequence) starting with a backslash `\\` character:
+
+* `\\{:tact}` — literal backslash
+* `\"{:tact}` — double quote
+* `\n{:tact}` — newline
+* `\r{:tact}` — carriage return
+* `\t{:tact}` — tab
+* `\v{:tact}` — vertical tab
+* `\b{:tact}` — backspace
+* `\f{:tact}` — form feed
+* `\x00{:tact}` through `\xFF{:tact}` — [code point](https://en.wikipedia.org/wiki/Code_point), must be exactly two hex digits long
+* `\u0000{:tact}` through `\uFFFF{:tact}` — [Unicode code point][unicode], must be exactly four hex digits long
+* `\u{0}{:tact}` through `\u{FFFFFF}{:tact}` — [Unicode code point][unicode], can be from $1$ to $6$ hex digits long
+
+[unicode]: https://en.wikipedia.org/wiki/Unicode#Codespace_and_code_points
+
+```tact
+// \\
+"escape \\ if \\ you \\ can \\";
+
+// \"
+"this \"literally\" works";
+
+// \n
+"line \n another line";
+
+// \r
+"Shutters \r Like \r This \r One";
 
-// Note, that at the moment Tact strings can't have escape characters in them:
-"line \n another"; // SYNTAX ERROR!, see: https://github.com/tact-lang/tact/issues/25
+// \t
+"spacing \t granted!";
 
-// This means, that double quotes inside strings are also prohibited:
-"this \"can't be!\""; // SYNTAX ERROR!
+// \v
+"those \v words \v are \v aligned";
+
+// \b
+"rm\b\bcreate!";
+
+// \f
+"form \f feed";
+
+// \x00 - \xFF
+"this \x22literally\x22 works"; // \x22 represents a double quote
+
+// \u0000 - \uFFFF
+"danger, \u26A1 high voltage \u26A1"; // \u26A1 represents the ⚡ emoji
+
+// \u{0} - \u{FFFFFF}
+"\u{1F602} LOL \u{1F602}"; // \u{1F602} represents the 😂 emoji
 ```
 
-Read more about strings and [`String{:tact}`][p] type there: [Primitive types][p].
+<Callout>
+
+  Read more about strings and [`String{:tact}`][p] type:\
+  [Primitive types in the Book][p]\
+  [Strings and StringBuilders in the Reference](/ref/api-strings)
+
+</Callout>
+
 
 ### `null` literal
 
@@ -156,7 +208,6 @@ Anywhere in the function body, a global [static function](/book/functions#global
 
 ```tact
 contract ExampleContract {
-    init() {}
     receive() {
         now(); // now() is a static function of stdlib
         let expiration: Int = now() + 1000; // operation and variable declaration

pages/book/functions.mdx

@@ -56,7 +56,7 @@ Extension functions allow you to implement extensions for any possible type.
 > The name of the first argument MUST be named `self` and the type of this argument is the type you are extending.
 
 ```tact
-extends fun pow(self: Int, c: Int) {
+extends fun pow(self: Int, c: Int): Int {
   let res: Int = 1;
   repeat(c) {
     res *= self;

pages/book/maps.mdx

@@ -30,7 +30,7 @@ Allowed value types:
 
 ## Operations
 
-### Declare
+### Declare, `emptyMap()` [#emptymap]
 
 As a [local variable](/book/statements#let), using `emptyMap(){:tact}` function of standard library:
 
@@ -93,9 +93,9 @@ if (gotButUnsure != null) {
 }
 ```
 
-### Delete entries [#del]
+### Delete entries, `.del()` [#del]
 
-To delete a single key-value pair (single entry), simply assign the `null{:tact}` value to the key when using the [`.set(){:tact}`](#set) [method](/book/functions#extension-function).
+To delete a single key-value pair (single entry), use the `.del(){:tact}` [method](/book/functions#extension-function). It returns `true{:tact}` in the case of successful deletion and `false{:tact}` otherwise.
 
 ```tact
 // Empty map
@@ -106,7 +106,13 @@ fizz.set(7, 123);
 fizz.set(42, 321);
 
 // Deleting one of the keys
-fizz.set(7, null); // the entry under key 7 is now deleted
+let deletionSuccess: Bool = fizz.del(7); // true, because map contained the entry under key 7
+fizz.del(7);                             // false, because map no longer has an entry under key 7
+
+// Note, that assigning the `null` value to the key when using the `.set()` method
+//   is equivalent to calling `.del()`, although such approach is much less descriptive
+//   and is generally discouraged:
+fizz.set(42, null); // the entry under key 42 is now deleted
 ```
 
 To delete all the entries from the map, re-assign the map using the `emptyMap(){:tact}` function:
@@ -126,7 +132,25 @@ fizz = null; // identical to the previous line, but less descriptive
 
 With this approach all previous entries of the map are completely discarded from the contract even if the map was declared as its persistent state variable. As a result, assigning maps to `emptyMap(){:tact}` **does not** inflict any hidden or sudden [storage fees](https://docs.ton.org/develop/smart-contracts/fees#storage-fee).
 
-### Convert to a `Cell`, `.asCell()` [#convert]
+### Check if empty, `.isEmpty()` [#isempty]
+
+The `.isEmpty(){:tact}` [method](/book/functions#extension-function) on maps returns `true{:tact}` if the map is empty and `false{:tact}` otherwise:
+
+```tact
+let fizz: map<Int, Int> = emptyMap();
+
+if (fizz.isEmpty()) {
+    dump("Empty maps are empty, duh!");
+}
+
+// Note, that comparing the map to `null` behaves the same as `.isEmpty()` method,
+// although such direct comparison is much less descriptive and is generally discouraged:
+if (fizz == null) {
+    dump("Empty maps are null, which isn't obvious");
+}
+```
+
+### Convert to a `Cell`, `.asCell()` [#ascell]
 
 Use `.asCell(){:tact}` [method](/book/functions#extension-function) on maps to convert all their values to a [`Cell{:tact}`][p] type. Be mindful, that [`Cell{:tact}`][p] type is able to store up to 1023 bits, so converting larger maps to the Cell will result in error.
 
@@ -157,7 +181,25 @@ contract Example {
 
 ### Traverse over entries [#traverse]
 
-At the moment Tact doesn't have a special syntax for iterating over maps. However, it's possible to use maps as a simple arrays if you define a `map<Int, v>{:tact}` with an [`Int{:tact}`][int] type for the keys and keep track of the number of items in the separate variable:
+To iterate over map entries there is a [`foreach{:tact}`](/book/statements#foreach-loop) loop statement:
+
+```tact
+// Empty map
+let fizz: map<Int, Int> = emptyMap();
+
+// Setting a couple of values under different keys
+fizz.set(42, 321);
+fizz.set(7, 123);
+
+// Iterating over in a sequential order: from the smallest keys to the biggest ones
+foreach (key, value in fizz) {
+    dump(key); // will dump 7 on the first iteration, then 42 on the second
+}
+```
+
+Read more about it: [`foreach{:tact}` loop in Book→Statements](/book/statements#foreach-loop).
+
+Note, that it's also possible to use maps as simple arrays if you define a `map<Int, V>{:tact}` with an [`Int{:tact}`][int] type for the keys, any allowed `V` type for values and keep track of the number of items in the separate variable:
 
 ```tact
 contract Iteration {
@@ -265,9 +307,6 @@ contract Example {
     arr: map<Int, Int>; // "array" of String values as a map
     arrLength: Int = 0;    // length of the "array", defaults to 0
 
-    // Constructor (initialization) function of the contract
-    init() {}
-
     // Internal function for pushing an item to the end of the "array"
     fun arrPush(item: String) {
         if (self.arrLength >= self.MaxMapSize) {

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.