Invalid type passed!
Received:
{type}
Expected one of:
{asideVariants.join(", ")}
: <>
{title &&
{title}
}
{children}
}
;
};
Tolk supports `map` — a high‑level type that encapsulates TVM dictionaries:
* Any serializable keys and values.
* Natural syntax for iterating forwards, backwards, or starting from a specified key.
* Zero overhead compared to low-level approach.
## Create an empty map
```tolk theme={null}
var m: map = createEmptyMap();
// or
var m = createEmptyMap();
```
A map is a dedicated type, it may be used in parameters, fields, etc.:
```tolk theme={null}
struct Demo {
m: map
}
fun create(): Demo {
return {
m: createEmptyMap()
}
}
```
## Add values to a map
Use `m.set(k, v)` and other methods suggested by an IDE after a dot (a full list is available below):
```tolk theme={null}
var m: map = createEmptyMap();
m.set(1, 10);
m.addIfNotExists(2, -20);
m.replaceIfExists(2, 20);
m.delete(2); // now: [ 1 => 10 ]
m.exists(1); // true
m.exists(2); // false
```
## Get a value by key
`m.get(key)` returns `isFound + loadValue()`:
```tolk theme={null}
var r = m.get(1);
if (r.isFound) {
val v = r.loadValue(); // 10
}
```
Note: check **not `r == null`, but `r.isFound`**. In other words, `map.get(key)` returns not `V?`, but a special result.
Also use `m.mustGet(key)` that returns `V` and throws if the key is missing:
```tolk theme={null}
m.mustGet(1); // 10
m.mustGet(100500); // runtime error
```
## Iterate forward and backward
There is no dedicated `foreach` syntax. Iteration follows this pattern:
* define the starting key: `r = m.findFirst()` or `r = m.findLast()`
* while `r.isFound`:
* use `r.getKey()` and `r.loadValue()`
* move the cursor: `r = m.iterateNext(r)` or `r = m.iteratePrev(r)`
Example: iterate all keys forward
```tolk theme={null}
// suppose there is a map [ 1 => 10, 2 => 20, 3 => 30 ]
// this function will print "1 10 2 20 3 30"
fun iterateAndPrint(m: map) {
var r = m.findFirst();
while (r.isFound) {
debug.print(r.getKey());
debug.print(r.loadValue());
r = m.iterateNext(r);
}
}
```
Example: iterate backwards from keys ≤ 2
```tolk theme={null}
// suppose `m` is `[ int => address ]` and already populated
// for every key<=2, print addr.workchain
fun printWorkchainsBackwards(m: map) {
var r = m.findKeyLessOrEqual(2);
while (r.isFound) {
val a = r.loadValue(); // it's `address`
debug.print(a.getWorkchain());
r = m.iteratePrev(r);
}
}
```
## Check if a map is empty
```tolk theme={null}
m.isEmpty() // not `m == null`
```
## Allowed types for K and V
All the following key and value types are valid:
```tolk theme={null}
map
map
map>
map>
map
```
Some types are not allowed. General rules:
* Keys must be fixed-width and contain zero references
* Valid: `int32`, `address`, `bits256`, `Point`
* Invalid: `int`, `coins`, `cell`
* Values must be serializable
* Valid: `coins`, `AnyStruct`, `Cell`
* Invalid: `int`, `builder`
In practice, keys are most commonly `intN`, `uintN`, or `address`. Values can be any serializable type.
## Available methods for maps
An IDE suggests available methods after a dot. Most methods are self-explanatory.
* `createEmptyMap(): map`
Returns an empty typed map. Equivalent to `PUSHNULL` since TVM `NULL` represents an empty map.
* `createMapFromLowLevelDict(d: dict): map`
Converts a low-level TVM dictionary to a typed map. Accepts an optional cell and returns the same optional cell.
Mismatched key or value types result in failures when calling `map.get` or related methods.
* `m.toLowLevelDict(): dict`
Converts a high-level map to a low-level TVM dictionary. Returns the same optional cell.
* `m.isEmpty(): bool`
Checks whether a map is empty. Use `m.isEmpty()` instead of `m == null`.
* `m.exists(key: K): bool`
Checks whether a key exists in a map.
* `m.get(key: K): MapLookupResult`
Gets an element by key. Returns `isFound = false` if key does not exist.
* `m.mustGet(key: K, throwIfNotFound: int = 9): V`
Gets an element by key and throws if it does not exist.
* `m.set(key: K, value: V): self`
Sets an element by key. Since it returns `self`, calls may be chained.
* `m.setAndGetPrevious(key: K, value: V): MapLookupResult`
Sets an element and returns the previous element. If no previous element, `isFound = false`.
* `m.replaceIfExists(key: K, value: V): bool`
Sets an element only if the key exists. Returns whether an element was replaced.
* `m.replaceAndGetPrevious(key: K, value: V): MapLookupResult`
Sets an element only if the key exists and returns the previous element.
* `m.addIfNotExists(key: K, value: V): bool`
Sets an element only if the key does not exist. Returns true if added.
* `m.addOrGetExisting(key: K, value: V): MapLookupResult`
Sets an element only if the key does not exist. If exists, returns an old value.
* `m.delete(key: K): bool`
Deletes an element by key. Returns true if deleted.
* `m.deleteAndGetDeleted(key: K): MapLookupResult`
Deletes an element by key and returns the deleted element. If not found, `isFound = false`.
* `m.findFirst(): MapEntry`
* `m.findLast(): MapEntry`
Finds the first (minimal) or last (maximal) element.
For integer keys, returns minimal (maximal) integer.
For addresses or complex keys (represented as slices), returns lexicographically smallest (largest) key.
Returns `isFound = false` when the map is empty.
* `m.findKeyGreater(pivotKey: K): MapEntry`
* `m.findKeyGreaterOrEqual(pivotKey: K): MapEntry`
* `m.findKeyLess(pivotKey: K): MapEntry`
* `m.findKeyLessOrEqual(pivotKey: K): MapEntry`
Finds an element with key compared to pivotKey.
* `m.iterateNext(current: MapEntry): MapEntry`
* `m.iteratePrev(current: MapEntry): MapEntry`
Iterates over a map in ascending (descending) order.
## Augmented hashmaps and prefix dictionaries
These structures are rarely used and are not part of the Tolk type system.
* Prefix dictionaries: `import @stdlib/tvm-dicts` and use assembly functions.
* Augmented hashmaps and Merkle proofs: implement interaction manually.
## Keys are auto-serialized
At the TVM level, keys can be numbers or slices. Complex keys, such as `Point`, are automatically serialized and deserialized by the compiler.
```tolk theme={null}
struct Point {
x: int8
y: int8
}
fun demo(m: map) {
// a key is automatically packed to a 16-bit slice
m.set({x: 10, y: 20}, 123);
// and unpacked back to `Point`
return m.findFirst().key;
}
```
If a key is a struct with a single intN field, it behaves like a number.
```tolk theme={null}
struct UserId {
v: int32
}
struct Demo {
// equal to K=int32 without extra serialization
m: map
}
```
## How to emulate `Set` with maps
Use an "empty tensor" as a type for `V`:
```tolk theme={null}
type Set = map
```
It will work, a bit noisy.
Lots of methods for maps are just inapplicable to sets, so its "public interface" is wrong.
Sets have a much simpler API, literally 4 functions.
It's better to create a simple wrapper:
```tolk theme={null}
struct Set {
private m: map
}
fun Set.add(self, value: T) { /* ... */ }
// etc.
```
## Low-level: why "isFound" but not "optional value"?
There are two reasons for this design:
* Gas consumption (zero overhead)
* Nullable values can be supported, like `map` or `map`. Returning `V?`, makes it impossible to distinguish between "key exists but value is null" and "key does not exist".
TVM dictionaries store binary data. Having a `map` and doing `m.set(k, 10)`, this "10" is actually 0x0000000A (automatically packed by the compiler).
All TVM instructions for reading return slices, so at some point, those bits should be decoded back to "10".
TVM instructions put two values on a stack: `(slice -1)` or `(null 0)`. If a choice is to return `V?`, the compiler needs to do something like
```ansi theme={null}
IF stack[0] == -1:
decode stack[1] to V
transform V to V?
ELSE:
drop stack[1]
transform null to V?
```
Then, at usage, it's compared null:
```tolk theme={null}
val v = m.get(k); // internally, IF ELSE: for decoding
if (v != null) { // one more IF: for checking
...
}
```
So, it results in two runtime checks and three TVM continuations.
That's why instead of `V?`, a special struct is returned:
```tolk theme={null}
fun map.get(self, key: K): MapLookupResult;
struct MapLookupResult {
private readonly rawSlice: slice?
isFound: bool
}
fun MapLookupResult.loadValue(self): TValue {
return TValue.fromSlice(self.rawSlice!)
}
```
This struct directly maps onto the TVM stack: `(slice -1)` or `(null 0)`.
The condition `if (r.isFound)` naturally checks the top element (automatically popped).
Followed by auto-deserialization at `r.loadValue()` when `rawSlice` is left on the top.
Moreover, some other functions return the same struct. For example, `m.setAndGetPrevious`:
```tolk theme={null}
val prev = m.setAndGetPrevious(1, 100500);
// NOT `if (prev != null)`, but
if (prev.isFound) {
prev.loadValue() // 10
}
```
Overall, this provides zero overhead compared to plain dictionaries.
## Stack layout and serialization
An empty map is backed by TVM `NULL`, serialized as '0'. A non-empty map is TVM `CELL`, serialized as '1'+ref.
For details, follow [TVM representation](/languages/tolk/types/overall-tvm-stack) and [Serialization](/languages/tolk/types/overall-serialization).