Merge pull request #302331 from mumian/0707-indexfromend

ARM functions indexFromEnd

Author: JamesJBarnett

articles/azure-resource-manager/bicep/data-types.md

@@ -2,7 +2,7 @@
 title: Data types in Bicep
 description: This article describes the data types that are available in Bicep.
 ms.topic: reference
-ms.date: 06/30/2025
+ms.date: 07/07/2025
 ms.custom: devx-track-bicep
 ---
 
@@ -437,6 +437,16 @@ The union type has some limitations:
 
 You can use the union type syntax in [user-defined data types](./user-defined-data-types.md).
 
+## Nullable types
+
+You can make any primitive or complex type nullable by appending a `?` to the type name. This allows the parameter, variable, or output to accept null as a valid value. For example:
+
+```bicep
+output description string? = null
+output config object? = null
+output optionalValue int? = null
+```
+
 ## Secure strings and objects
 
 Secure strings use the same format as string, and secure objects use the same format as object. With Bicep, you add the `@secure()` [decorator](./parameters.md#use-decorators) to a string or object.

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

@@ -3,7 +3,7 @@ title: Template functions - arrays
 description: Describes the functions to use in an Azure Resource Manager template (ARM template) for working with arrays.
 ms.topic: reference
 ms.custom: devx-track-arm-template
-ms.date: 02/12/2025
+ms.date: 07/07/2025
 ---
 
 # Array functions for ARM templates
@@ -223,6 +223,57 @@ The output from the preceding example with the default values is:
 | arrayOutput | String | one |
 | stringOutput | String | O |
 
+## indexFromEnd
+
+`indexFromEnd(sourceArray, reverseIndex)`
+
+Returns an element of the array by counting backwards from the end. This is useful when you want to reference elements starting from the end of a list, rather than the beginning. The [`tryIndexFromEnd`](#tryindexfromend) function is a safe version of `indexFromEnd`.
+
+In Bicep, use the [Reserved index accessor](../bicep/operators-access.md#reverse-index-accessor) operator.
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| sourceArray |Yes |array |The value to retrieve the element by counting backwards from the end. |
+| reverseIndex |Yes |integer |The one-based index from the end of the array. |
+
+### Return value
+
+A single element from an array, selected by counting backward from the end of the array.
+
+### Example
+
+The following example shows how to use the `indexFromEnd` function.
+
+```json
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "variables": {
+    "items": [
+      "apple",
+      "banana",
+      "orange",
+      "grape"
+    ]
+  },
+  "resources": [],
+  "outputs": {
+    "secondToLast": {
+      "type": "string",
+      "value": "[indexFromEnd(variables('items'), 2)]"
+    }
+  }
+}
+```
+
+The output from the preceding example with the default values is:
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| secondToLast | String | orange |
+
 ## indexOf
 
 `indexOf(arrayToSearch, itemToFind)`
@@ -693,6 +744,92 @@ The output from the preceding example with the default values is:
 | arrayOutput | Array | ["one", "two"] |
 | stringOutput | String | on |
 
+## tryIndexFromEnd
+
+`tryndexFromEnd(sourceArray, reverseIndex)`
+
+The `tryIndexFromEnd` function is a safe version of [`indexFromEnd`](#indexfromend). It retrieves a value from an array by counting backward from the end without throwing an error if the index is out of range.
+
+In Bicep, use the [Reserved index accessor](../bicep/operators-access.md#reverse-index-accessor) operator and the [Safe dereference](../bicep/operator-safe-dereference.md#safe-dereference) operator.
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| sourceArray |Yes |array |The value to retrieve the element by counting backwards from the end. |
+| reverseIndex |Yes |integer |The one-based index from the end of the array. |
+
+### Return value
+
+If the index is valid (within array bounds), returns the array element at that reverse index. If the index is out of range, returns null instead of throwing an error.
+
+### Example
+
+The following example shows how to use the `tryIndexFromEnd` function:
+
+```json
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "variables": {
+    "items": [
+      "apple",
+      "banana",
+      "orange",
+      "grape"
+    ]
+  },
+  "resources": [],
+  "outputs": {
+    "secondToLast": {
+      "type": "string",
+      "value": "[tryIndexFromEnd(variables('items'), 2)]"
+    }
+  }
+}
+```
+
+The output from the preceding example with the default values is:
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| secondToLast | String | orange |
+
+The following example shows an out-of-bound scenario:
+
+```json
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "languageVersion": "2.0",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "items": {
+      "type": "array",
+      "defaultValue": [
+        "apple",
+        "banana",
+        "orange",
+        "grape"
+      ]
+    }
+  },
+  "resources": {},
+  "outputs": {
+    "outOfBound": {
+      "type": "string",
+      "nullable": true,
+      "value": "[tryIndexFromEnd(parameters('items'), 5)]"
+    }
+  }
+}
+```
+
+The output from the preceding example with the default values is:
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| outOfBound | String | (null) |
+
 ## union
 
 `union(arg1, arg2, arg3, ...)`

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

@@ -3,7 +3,7 @@ title: Template functions
 description: Describes the functions to use in an Azure Resource Manager template (ARM template) to retrieve values, work with strings and numerics, and retrieve deployment information.
 ms.topic: reference
 ms.custom: devx-track-arm-template
-ms.date: 02/12/2025
+ms.date: 07/07/2025
 ---
 
 # ARM template functions
@@ -29,6 +29,7 @@ The [any function](../bicep/bicep-functions-any.md) is available in Bicep to hel
 <a id="createarray" aria-hidden="true"></a>
 <a id="empty" aria-hidden="true"></a>
 <a id="first" aria-hidden="true"></a>
+<a id="indexfromend" aria-hidden="true"></a>
 <a id="indexof" aria-hidden="true"></a>
 <a id="intersection" aria-hidden="true"></a>
 <a id="last" aria-hidden="true"></a>
@@ -39,6 +40,7 @@ The [any function](../bicep/bicep-functions-any.md) is available in Bicep to hel
 <a id="range" aria-hidden="true"></a>
 <a id="skip" aria-hidden="true"></a>
 <a id="take" aria-hidden="true"></a>
+<a id="tryindexfromend" aria-hidden="true"></a>
 <a id="union" aria-hidden="true"></a>
 
 ## Array functions
@@ -51,6 +53,7 @@ Resource Manager provides several functions for working with arrays.
 * [createArray](template-functions-array.md#createarray)
 * [empty](template-functions-array.md#empty)
 * [first](template-functions-array.md#first)
+* [indexFromEnd](template-functions-array.md#indexfromend)
 * [indexOf](template-functions-array.md#indexof)
 * [intersection](template-functions-array.md#intersection)
 * [last](template-functions-array.md#last)
@@ -61,6 +64,7 @@ Resource Manager provides several functions for working with arrays.
 * [range](template-functions-array.md#range)
 * [skip](template-functions-array.md#skip)
 * [take](template-functions-array.md#take)
+* [tryIndexFromEnd](template-functions-array.md#tryindexfromend)
 * [union](template-functions-array.md#union)
 
 For Bicep files, use the [array](../bicep/bicep-functions-array.md) functions.

articles/azure-resource-manager/templates/toc.yml

@@ -293,6 +293,7 @@ items:
   - name: Template best practices
     href: best-practices.md
   - name: Data types
+    displayName: nullable types,union type,secure strings,secure objects,data type assignability
     href: data-types.md
   - name: Frequently asked questions
     href: frequently-asked-questions.yml
@@ -469,7 +470,7 @@ items:
     - name: All functions
       href: template-functions.md
     - name: Array functions
-      displayName: array,concat,contains,createArray,empty,first,indexOf,intersection,last,lastIndexOf,length,max,min,range,skip,take,union
+      displayName: array,concat,contains,createArray,empty,first,indexFromEnd,indexOf,intersection,last,lastIndexOf,length,max,min,range,skip,take,tryIndexFromEdn,union
       href: template-functions-array.md
     - name: CIDR functions
       displayName: parseCidr,cidrSubnet,cidrHost