feat(docs): map.exists() (#938)

CHANGELOG.md

@@ -59,7 +59,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- The `exists` method for the `Map` type: PR [#581](https://github.com/tact-lang/tact/pull/581)
+- The `exists` method for the `Map` type: PR [#581](https://github.com/tact-lang/tact/pull/581), PR [#938](https://github.com/tact-lang/tact/pull/938)
 - The `storeBit` method for `Builder` type and the `loadBit` method for `Slice` type: PR [#699](https://github.com/tact-lang/tact/pull/699), PR [#936](https://github.com/tact-lang/tact/pull/936)
 - The `toSlice` method for structs and messages: PR [#630](https://github.com/tact-lang/tact/pull/630), PR [#936](https://github.com/tact-lang/tact/pull/936)
 - Wider range of serialization options for integers — `uint1` through `uint256` and `int1` through `int257`: PR [#558](https://github.com/tact-lang/tact/pull/558), PR [#937](https://github.com/tact-lang/tact/pull/937)

docs/src/content/docs/book/maps.mdx

@@ -3,6 +3,8 @@ title: Maps
 description: "The composite type map is used as a way to associate keys with corresponding values of various types"
 ---
 
+import { Badge } from '@astrojs/starlight/components';
+
 The [composite type](/book/types#composite-types) `map<K, V>{:tact}` is used as a way to associate keys of type `K{:tact}` with corresponding values of type `V{:tact}`.
 
 For example, `map<Int, Int>{:tact}` uses [`Int{:tact}`][int] type for its keys and values:
@@ -133,6 +135,35 @@ 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).
 
+### Check if entry exists, `.exists()` {#exists}
+
+<Badge text="Available since Tact 1.5" variant="tip" size="medium"/><p/>
+
+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
+let fizz: map<Int, Int> = emptyMap();
+fizz.set(0, 0);
+
+if (fizz.exists(2 + 2)) { // false
+    dump("Something doesn't add up!");
+}
+
+if (fizz.exists(1 / 2)) { // true
+    dump("I told a fraction joke once. It was half funny.");
+}
+
+if (fizz.get(1 / 2) != null) { // also true, but consumes more gas
+    dump("Gotta pump more!");
+}
+```
+
+:::note
+
+  Calling `m.exists(key){:tact}` is more gas-efficient than executing `m.get(key) != null{:tact}`, although both approaches yield the same results.
+
+:::
+
 ### 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: