From 32999aca84e9a421674217cb7125c7b4939d0aca Mon Sep 17 00:00:00 2001
From: darkdrag00nv2 <122124396+darkdrag00nv2@users.noreply.github.com>
Date: Thu, 31 Aug 2023 00:40:09 +0530
Subject: [PATCH] Document `map` function in array types (#221)

* Document map function in array types

* Add description before section on fixed-sized arrays

Co-authored-by: Supun Setunga <supun.setunga@gmail.com>

* Update docs/cadence/language/values-and-types.mdx

---------

Co-authored-by: Supun Setunga <supun.setunga@gmail.com>
---
 docs/cadence/language/values-and-types.mdx | 63 ++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/docs/cadence/language/values-and-types.mdx b/docs/cadence/language/values-and-types.mdx
index c924fd1a66..5d80c99122 100644
--- a/docs/cadence/language/values-and-types.mdx
+++ b/docs/cadence/language/values-and-types.mdx
@@ -1252,6 +1252,69 @@ are available for both variable-sized and fixed-sized or variable-sized arrays.
     // `fixedArrayReversedExample` is now `["PQR", "XYZ", "ABC"]`
     ```
 
+-
+    ```cadence
+    access(all)
+    fun map(_ f: (T: U)): [U]
+    ```
+
+    Returns a new array whose elements are produced by applying the mapper function on each element
+    of the original array.
+    Available if `T` is not resource-kinded.
+
+    ```cadence
+    let example = [1, 2, 3]
+    let trueForEven =
+        fun (_ x: Int): Bool {
+            return x % 2 == 0
+        }
+
+    let mappedExample: [Bool] = example.map(trueForEven)
+    // `mappedExample` is `[False, True, False]`
+    // `example` still remains as `[1, 2, 3]`
+
+    // Invalid: Map using a function which accepts a different type.
+    // This results in a type error, as the array contains `Int` values while function accepts 
+    // `Int64`.
+    let functionAcceptingInt64 =
+        fun (_ x: Int64): Bool {
+            return x % 2 == 0
+        }
+    let invalidMapFunctionExample = example.map(functionAcceptingInt64)
+    ```
+
+    `map` function is also available for fixed-sized arrays:
+
+    ```cadence
+    access(all)
+    fun map(_ f: (T: U)): [U; N]
+    ```
+
+    Returns a new fixed-sized array whose elements are produced by applying the mapper function on
+    each element of the original array.
+    Available if `T` is not resource-kinded.
+
+    ```cadence
+    let fixedSizedExample: [String; 3] = ["ABC", "XYZYX", "PQR"]
+    let lengthOfString =
+        fun (_ x: String): Int {
+            return x.length
+        }
+
+    let fixedArrayMappedExample = fixedSizedExample.map(lengthOfString)
+    // `fixedArrayMappedExample` is now `[3, 5, 3]`
+    // `fixedSizedExample` still remains as ["ABC", "XYZYX", "PQR"]
+
+    // Invalid: Map using a function which accepts a different type.
+    // This results in a type error, as the array contains `String` values while function accepts 
+    // `Bool`.
+    let functionAcceptingBool =
+        fun (_ x: Bool): Int {
+            return 0
+        }
+    let invalidMapFunctionExample = fixedSizedExample.map(functionAcceptingBool)
+    ```
+
 #### Variable-size Array Functions
 
 The following functions can only be used on variable-sized arrays.