feat: Maps page update

[novusnota]

Added or refined:

• .get()
• .set()
• .asCell()
• Deletion of individual or all entries
• Iteration over maps
• Mention of issues with large maps and how to mitigate them:
  1. With upper-bounds
  2. Or with contract sharding

And everything with examples of Tact code, except for contract sharding, which will be added later as per tact-lang/tact#1151.

As a bonus, added two neat examples of using maps as arrays to Cookbook (with handy comments): one from @howardpen9 🔥, another from tact-by-example and @talkol 🔥

Closes #135
Closes #133

[novusnota]

Left to do:

And the same for arrPop() function just introduces.

[novusnota]

@anton-trunov It seems like the gas usage with packing the map into structure with methods (with one persistent state variable array: Array, see below) is the same as in the previous example (with using two: arr and arrLength). Or this is the case for the Sandbox.

Code of the new example (works, tested :)

import "@stdlib/deploy";

struct Array {
    map: map<Int, Int>; // «array» of Int values as a map
    length: Int = 0;    // length of the «array», defaults to 0
}

extends mutates fun push(self: Array, item: Int) {
    self.map.set(self.length, item);
    self.length = self.length + 1;
}

extends mutates fun pop(self: Array): Int {
    require(self.length > 0, "No items in the array to delete!");

    // Note, that we use !! operator as we know for sure that the value would be there
    let lastItem: Int = self.map.get(self.length - 1)!!;
    self.map.set(self.length - 1, null); // delete the entry
    self.length = self.length - 1;       // decrease the length

    return lastItem;
}

extends fun getLast(self: Array): Int {
    require(self.length > 0, "No items in the array!");

    // Note, that we use !! operator as we know for sure that the value would be there
    return self.map.get(self.length - 1)!!;
}

contract MapsAsArrays with Deployable {
    // Persistent state variables
    array: Array; // structure defined above

    // Constructor (initialization) function of the contract
    init() {
        self.array = Array{map: emptyMap()}; // length defaults to 0
    }

    // Internal message receiver, which responds to a String message "push"
    receive("push") {
        // Add a new item and increase the counter
        self.array.push(42);
    }

    // Internal message receiver, which responds to a String message "pop"
    receive("pop") {
        // Remove the last item and decrease the counter
        self.array.pop();
    }

    // Internal message receiver, which responds to a String message "get_last"
    receive("get_last") {
        // Reply back with the latest item in the map if it exists, or raise an error
        self.reply(self.array.getLast().toCoinsString().asComment());
    }

    // Getter function for obtaining the «array»
    get fun map(): map<Int, Int> {
        return self.array.map;
    }

    // Getter function for obtaining the current length of the «array»
    get fun length(): Int {
        return self.array.length;
    }
}

Added that example to the Cookbook + added a note discussing potential issues of the current one.

[anton-trunov]

I really like what you did for array emulation with maps packed in structs.
(btw, that example shows we need generic data structures in Tact)

[novusnota]

Ready for review. Added more examples and refined previous ones — Map emulating: Arrays, Stacks, CircularBuffers.

[anton-trunov]

Awesome