Merge pull request #275008 from mumian/0510-function-shallowMerge

arm/bicep shallowMerge function

Author: JamesJBarnett

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

@@ -385,6 +385,47 @@ The output from the preceding example with the default values is:
 | stringLength | Int | 13 |
 | objectLength | Int | 4 |
 
+## shallowMerge
+
+`shallowMerge(inputArray)`
+
+Combines an array of objects, where only the top-level objects are merged. This means that if the objects being merged contain nested objects, those nested object aren't deeply merged; instead, they're replaced entirely by the corresponding property from the merging object.
+
+Namespace: [sys](bicep-functions.md#namespaces-for-functions).
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| inputArray |Yes |array |An array of objects. |
+
+### Return value
+
+An object.
+
+### Example
+
+The following example shows how to use `shallowMerge`:
+
+```bicep
+var firstArray = [{ one: 'a' }, { two: 'b' }, { two: 'c'}]
+var secondArray = [{ one: 'a', nested: {a: 1, nested: {c: 3}} }, { two: 'b', nested: {b: 2}}]
+
+output firstOutput object = shallowMerge(firstArray)
+output secondOutput object = shallowMerge(secondArray)
+```
+
+The output from the preceding example with the default values is:
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| firstOutput | object | {"one":"a","two":"c"}|
+| secondOutput | object | {"one":"a","nested":{"b":2},"two":"b"} |
+
+**firstOutput** shows the properties from the merging objects are combined into a new object. If there are conflicting properties (i.e., properties with the same name), the property from the last object being merged usually takes precedence.
+
+**secondOutput** shows the shallow merge doesn't recursively merge these nested objects. Instead, the entire nested object is replaced by the corresponding property from the merging object.
+
 ## union
 
 `union(arg1, arg2, arg3, ...)`
@@ -413,7 +454,7 @@ For arrays, the function iterates through each element in the first parameter an
 
 For objects, property names and values from the first parameter are added to the result. For later parameters, any new names are added to the result. If a later parameter has a property with the same name, that value overwrites the existing value. The order of the properties isn't guaranteed.
 
-The union function merges not only the top-level elements but also recursively merges any nested objects within them. Nested array values are not merged. See the second example in the following section.
+The union function merges not only the top-level elements but also recursively merges any nested objects within them. Nested array values aren't merged. See the second example in the following section.
 
 ### Example
 

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

@@ -120,6 +120,7 @@ The following functions are available for working with objects. All of these fun
 * [items](./bicep-functions-object.md#items)
 * [json](./bicep-functions-object.md#json)
 * [length](./bicep-functions-object.md#length)
+* [shallowMerge](./bicep-functions-object.md#shallowmerge)
 * [union](./bicep-functions-object.md#union)
 
 ## Parameters file functions

articles/azure-resource-manager/templates/template-functions-object.md

@@ -409,6 +409,87 @@ The output from the preceding example is:
 | ---- | ---- | ----- |
 | emptyOutput | Bool | True |
 
+## shallowMerge
+
+`shallowMerge(inputArray)`
+
+Combines an array of objects, where only the top-level objects are merged. This means that if the objects being merged contain nested objects, those nested object aren't deeply merged; instead, they're replaced entirely by the corresponding property from the merging object.
+
+In Bicep, use the [shallowMerge](../bicep/bicep-functions-object.md#shallowmerge) function.
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| inputArray |Yes |array |An array of objects. |
+
+### Return value
+
+An object.
+
+### Example
+
+The following example shows how to use `shallowMerge`:
+
+```json
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "variables": {
+    "firstArray": [
+      {
+        "one": "a"
+      },
+      {
+        "two": "b"
+      },
+      {
+        "two": "c"
+      }
+    ],
+    "secondArray": [
+      {
+        "one": "a",
+        "nested": {
+          "a": 1,
+          "nested": {
+            "c": 3
+          }
+        }
+      },
+      {
+        "two": "b",
+        "nested": {
+          "b": 2
+        }
+      }
+    ]
+  },
+  "resources": [],
+  "outputs": {
+    "firstOutput": {
+      "type": "object",
+      "value": "[shallowMerge(variables('firstArray'))]"
+    },
+    "secondOutput": {
+      "type": "object",
+      "value": "[shallowMerge(variables('secondArray'))]"
+    }
+  }
+}
+```
+
+The output from the preceding example with the default values is:
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| firstOutput | object | {"one":"a","two":"c"}|
+| secondOutput | object | {"one":"a","nested":{"b":2},"two":"b"} |
+
+**firstOutput** shows the properties from the merging objects are combined into a new object. If there are conflicting properties (i.e., properties with the same name), the property from the last object being merged usually takes precedence.
+
+**secondOutput** shows the shallow merge doesn't recursively merge these nested objects. Instead, the entire nested object is replaced by the corresponding property from the merging object.
+
 ## union
 
 `union(arg1, arg2, arg3, ...)`

articles/azure-resource-manager/templates/template-functions.md

@@ -217,6 +217,7 @@ Resource Manager provides several functions for working with objects.
 * [json](template-functions-object.md#json)
 * [length](template-functions-object.md#length)
 * [null](template-functions-object.md#null)
+* [shallowMerge](template-functions-object.md#shallowmerge)
 * [union](template-functions-object.md#union)
 
 For Bicep files, use the [object](../bicep/bicep-functions-object.md) functions.