Merge pull request #226583 from mumian/0206-lambda-toobject

add toObject lambda function

Author: Court72

articles/azure-resource-manager/bicep/bicep-functions-lambda.md

@@ -4,7 +4,7 @@ description: Describes the lambda functions to use in a Bicep file.
 author: mumian
 ms.topic: conceptual
 ms.author: jgao
-ms.date: 09/20/2022
+ms.date: 02/09/2023
 
 ---
 # Lambda functions for Bicep
@@ -22,7 +22,7 @@ This article describes the lambda functions to use in Bicep. [Lambda expressions
 
 Bicep lambda function has these limitations:
 
-- Lambda expression can only be specified directly as function arguments in these functions: [`filter()`](#filter), [`map()`](#map), [`reduce()`](#reduce), and [`sort()`](#sort).
+- Lambda expression can only be specified directly as function arguments in these functions: [`filter()`](#filter), [`map()`](#map), [`reduce()`](#reduce), [`sort()`](#sort), and [`toOrder()`](#toobject).
 - Using lambda variables (the temporary variables used in the lambda expressions) inside resource or module array access isn't currently supported.
 - Using lambda variables inside the [`listKeys`](./bicep-functions-resource.md#list) function isn't currently supported.
 - Using lambda variables inside the [reference](./bicep-functions-resource.md#reference) function isn't currently supported.
@@ -48,7 +48,7 @@ An array.
 
 ### Examples
 
-The following examples show how to use the filter function.
+The following examples show how to use the `filter` function.
 
 ```bicep
 var dogs = [
@@ -120,7 +120,7 @@ An array.
 
 ### Example
 
-The following example shows how to use the map function.
+The following example shows how to use the `map` function.
 
 ```bicep
 var dogs = [
@@ -187,7 +187,7 @@ Any.
 
 ### Example
 
-The following examples show how to use the reduce function.
+The following examples show how to use the `reduce` function.
 
 ```bicep
 var dogs = [
@@ -263,7 +263,7 @@ An array.
 
 ### Example
 
-The following example shows how to use the sort function.
+The following example shows how to use the `sort` function.
 
 ```bicep
 var dogs = [
@@ -298,6 +298,111 @@ The output from the preceding example sorts the dog objects from the youngest to
 | ---- | ---- | ----- |
 | dogsByAge | Array | [{"name":"Indy","age":2,"interests":["Butter"]},{"name":"Casper","age":3,"interests":["Other dogs"]},{"name":"Evie","age":5,"interests":["Ball","Frisbee"]},{"name":"Kira","age":8,"interests":["Rubs"]}] |
 
+## toObject
+
+`toObject(inputArray, lambda expression, [lambda expression])`
+
+Converts an array to an object with a custom key function and optional custom value function.
+
+Namespace: [sys](bicep-functions.md#namespaces-for-functions).
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| inputArray |Yes |array |The array used for creating an object.|
+| lambda expression |Yes |expression |The lambda expression used to provide the key predicate.|
+| lambda expression |No |expression |The lambda expression used to provide the value predicate.|
+
+### Return value
+
+An object.
+
+### Example
+
+The following example shows how to use the `toObject` function with the two required parameters:
+
+```Bicep
+var dogs = [
+  {
+    name: 'Evie'
+    age: 5
+    interests: [ 'Ball', 'Frisbee' ]
+  }
+  {
+    name: 'Casper'
+    age: 3
+    interests: [ 'Other dogs' ]
+  }
+  {
+    name: 'Indy'
+    age: 2
+    interests: [ 'Butter' ]
+  }
+  {
+    name: 'Kira'
+    age: 8
+    interests: [ 'Rubs' ]
+  }
+]
+
+output dogsObject object = toObject(dogs, entry => entry.name)
+```
+
+The preceding example generates an object based on an array.
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| dogsObject | Object | {"Evie":{"name":"Evie","age":5,"interests":["Ball","Frisbee"]},"Casper":{"name":"Casper","age":3,"interests":["Other dogs"]},"Indy":{"name":"Indy","age":2,"interests":["Butter"]},"Kira":{"name":"Kira","age":8,"interests":["Rubs"]}} |
+
+The following `toObject` function with the third parameter provides the same output.
+
+```Bicep
+output dogsObject object = toObject(dogs, entry => entry.name, entry => entry)
+```
+
+The following example shows how to use the `toObject` function with three parameters.
+
+```Bicep
+var dogs = [
+  {
+    name: 'Evie'
+    properties: {
+      age: 5
+      interests: [ 'Ball', 'Frisbee' ]
+    }
+  }
+  {
+    name: 'Casper'
+    properties: {
+      age: 3
+      interests: [ 'Other dogs' ]
+    }
+  }
+  {
+    name: 'Indy'
+    properties: {
+      age: 2
+      interests: [ 'Butter' ]
+    }
+  }
+  {
+    name: 'Kira'
+    properties: {
+      age: 8
+      interests: [ 'Rubs' ]
+    }
+  }
+]
+output dogsObject object = toObject(dogs, entry => entry.name, entry => entry.properties)
+```
+
+The preceding example generates an object based on an array.
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| dogsObject | Object | {"Evie":{"age":5,"interests":["Ball","Frisbee"]},"Casper":{"age":3,"interests":["Other dogs"]},"Indy":{"age":2,"interests":["Butter"]},"Kira":{"age":8,"interests":["Rubs"]}} |
+
 ## Next steps
 
 - See [Bicep functions - arrays](./bicep-functions-array.md) for additional array related Bicep functions.