From 9cd06757108877abef5c0a45c517b314e710966f Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Thu, 16 Jan 2025 15:48:38 +0100 Subject: [PATCH] docs: add signatures for map methods (#1352) Co-authored-by: Anton Trunov --- CHANGELOG.md | 1 + docs/src/content/docs/book/maps.mdx | 47 ++++++++++++++++++++++++++++- 2 files changed, 47 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 31ac64ef1..eb98dcba8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -78,6 +78,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added a note on 255 being the maximum number of messages that can be sent during action phase: PR [#1237](https://github.com/tact-lang/tact/pull/1237) - Added onchain metadata creation for NFTs and Jettons to the cookbook: PR [#1236](https://github.com/tact-lang/tact/pull/1236) - Document that identifiers cannot start with `__gen` or `__tact`, and cannot contain Unicode characters apart from the small subset `a-zA-Z0-9_`: PR [#1312](https://github.com/tact-lang/tact/pull/1312) +- Added signatures for map methods, such as `.get()`, `.exists()`, `.set()`, `.replace()`, `.replaceGet()`, `.del()`, `.isEmpty()`, `.deepEquals()`, `.asCell()`: PR [#1352](https://github.com/tact-lang/tact/pull/1352) ### Release contributors diff --git a/docs/src/content/docs/book/maps.mdx b/docs/src/content/docs/book/maps.mdx index 4183465de..dfd051b0e 100644 --- a/docs/src/content/docs/book/maps.mdx +++ b/docs/src/content/docs/book/maps.mdx @@ -75,6 +75,11 @@ Note, that [persistent state variables](/book/contracts#variables) of type `map< ### Set values, `.set()` {#set} +```tact +// K and V correspond to the key and value types of the given map +extends mutates fun set(self: map, key: K, val: V); +``` + To set or replace the value under a key call the `.set(){:tact}` [method](/book/functions#extension-function), which is accessible for all maps. ```tact @@ -91,7 +96,12 @@ fizz.set(7, 68); // key 7 now points to value 68 ### Get values, `.get()` {#get} -To check if a key is found in the map by calling the `.get(){:tact}` [method](/book/functions#extension-function), which is accessible for all maps. This will return `null{:tact}` if the key is missing, or the value if the key is found. +```tact +// K and V correspond to the key and value types of the given map +extends fun get(self: map, key: K): V?; +``` + +To check if a key is found in the map by calling the `.get(){:tact}` [method](/book/functions#extension-function), which is accessible for all maps. This will return [`null{:tact}`](/book/optionals) if the key is missing, or the value if the key is found. ```tact // Empty map @@ -118,6 +128,11 @@ if (gotButUnsure != null) {

+```tact +// K and V correspond to the key and value types of the given map +extends mutates fun replace(self: map, key: K, val: V): Bool; +``` + To replace the value under a key, if such a key exists, use the `.replace(){:tact}` [method](/book/functions#extension-function). It returns `true{:tact}` on successful replacement and `false{:tact}` otherwise. ```tact @@ -160,6 +175,11 @@ replaced2; // false

+```tact +// K and V correspond to the key and value types of the given map +extends mutates fun replaceGet(self: map, key: K, val: V): V?; +``` + Like [`.replace()`](#replace), but instead of returning a [`Bool{:tact}`](/book/types#booleans) it returns the old (pre-replacement) value on successful replacement and [`null{:tact}`](/book/optionals) otherwise. ```tact @@ -200,6 +220,11 @@ oldVal2; // null ### Delete entries, `.del()` {#del} +```tact +// K and V correspond to the key and value types of the given map +extends mutates fun del(self: map, key: K): Bool; +``` + 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 @@ -241,6 +266,11 @@ With this approach all previous entries of the map are completely discarded from

+```tact +// K and V correspond to the key and value types of the given map +extends fun exists(self: map, key: K): Bool; +``` + The `.exists(){:tact}` [method](/book/functions#extension-function) on maps returns `true{:tact}` if the value under the given key exists in the map and `false{:tact}` otherwise. ```tact @@ -268,6 +298,11 @@ if (fizz.get(1 / 2) != null) { // also true, but consumes more gas ### Check if empty, `.isEmpty()` {#isempty} +```tact +// K and V correspond to the key and value types of the given map +extends fun isEmpty(self: map): Bool; +``` + The `.isEmpty(){:tact}` [method](/book/functions#extension-function) on maps returns `true{:tact}` if the map is empty and `false{:tact}` otherwise: ```tact @@ -288,6 +323,11 @@ if (fizz == null) {

+```tact +// K and V correspond to the key and value types of the given map +extends fun deepEquals(self: map, other: map): Bool; +``` + The `.deepEquals(){:tact}` [method](/book/functions#extension-function) on maps returns `true{:tact}` if all entries of the map match corresponding entries of another map, ignoring possible differences in the [underlying serialization logic][hashmap]. Returns `false{:tact}` otherwise. ```tact @@ -331,6 +371,11 @@ There, both maps are formed manually and both contain the same key-value pair. I ### Convert to a `Cell`, `.asCell()` {#ascell} +```tact +// K and V correspond to the key and value types of the given map +extends fun asCell(self: map): Cell; +``` + On [TVM][tvm], maps are represented as a [`Cell{:tact}`][cell] type and it's possible to construct and parse them directly. However, doing so is highly error-prone and quite messy, which is why Tact provides maps as a standalone composite type with many of the helper methods mentioned above. To cast maps back to the underlying [`Cell{:tact}`][cell] type, use the `.asCell(){:tact}` [method](/book/functions#extension-function). Since maps are initialized to `null{:tact}`, calling `.asCell(){:tact}` on a map with no values assigned will return `null{:tact}` and **not** an empty [`Cell{:tact}`][cell].