Merge pull request #300082 from mumian/0519-array-caret

Document array[^index]

Author: prmerger-automator[bot]

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: 05/09/2025
+ms.date: 05/20/2025
 ms.custom: devx-track-bicep
 ---
 
@@ -12,7 +12,11 @@ This article describes the data types that are supported in [Bicep](./overview.m
 
 ## Arrays
 
-Arrays start with a left bracket (`[`) and end with a right bracket (`]`). In Bicep, you can declare an array in a single line or in multiple lines. Commas (`,`) are used between values in single-line declarations, but they aren't used in multiple-line declarations. You can mix and match single-line and multiple-line declarations. The multiple-line declaration requires [Bicep CLI](./install.md#visual-studio-code-and-bicep-extension) version 0.7.X or later.
+A **array** in Bicep is an ordered collection of values—such as strings, integers, objects, or even other arrays—commonly used to group related items like resource names, configuration settings, or parameters. Arrays are helpful for organizing deployment data, passing lists to resources, and iterating over multiple values.
+
+Arrays in Bicep are immutable. Once declared, their contents can't be changed. To "modify" an array, create a new array using functions like [`concat`](./bicep-functions-array.md#concat), [`map`](./bicep-functions-lambda.md#map), or [`filter`](./bicep-functions-lambda.md#filter).
+
+You can declare arrays in Bicep using either single-line or multi-line syntax. Multi-line array declarations require [Bicep CLI version 0.7.X or later](https://github.com/Azure/bicep/releases/tag/v0.7.4).
 
 ```bicep
 var multiLineArray = [
@@ -27,9 +31,9 @@ var mixedArray = ['abc', 'def'
     'ghi']
 ```
 
-Each array element can be of any type. You can have an array where each item is the same data type, or an array that holds different data types.
+**Single-line arrays** use commas (`,`) to separate values. **Multi-line arrays** don't use commas between values. You can mix single-line and multi-line declarations as needed.
 
-The following example shows an array of integers and an array of different types.
+Each array element can be of any type. You can have an array where each item is the same data type, or an array that holds different data types.
 
 ```bicep
 var integerArray = [
@@ -44,27 +48,40 @@ var mixedArray = [
   true
   'example string'
 ]
+
+var arrayOfObjects = [
+  { name: 'dev', size: 1 }
+  { name: 'prod', size: 2 }
+]
 ```
 
-Arrays in Bicep are based on zero. In the following example, the expression `exampleArray[0]` evaluates to 1 and `exampleArray[2]` evaluates to 3. The index of the indexer might be another expression. The expression `exampleArray[index]` evaluates to 2. Integer indexers are only allowed on the expression of array types.
+Arrays in Bicep are zero-based. You can access elements by index:
 
 ```bicep
+var exampleArray = [1, 2, 3]
+output firstElement int = exampleArray[0] // 1
+output thirdElement int = exampleArray[2] // 3
+
 var index = 1
+output secondElement int = exampleArray[index] // 2
+```
 
-var exampleArray = [
-  1
-  2
-  3
-]
+Starting with [Bicep CLI version 0.34.x](https://github.com/Azure/bicep/releases/tag/v0.34.1), you can use the `array[^index]` syntax to access elements from the end of an array — `^1` refers to the last element, `^2` to the second-to-last, and so on.
+
+```bicep
+var exampleArray = [1, 2, 3]
+
+output lastElement int = exampleArray[^1] // 3
+output secondToLastElement int = exampleArray[^2] // 2
 ```
 
-You get the following error when the index is out of bounds:
+If you access an index that is out of bounds, you get an error:
 
 ```error
 The language expression property array index 'x' is out of bounds
 ```
 
-To avoid this exception, use the [Or logical operator](./operators-logical.md#or-), as shown in the following example:
+To avoid out-of-bounds exception, use the [Or logical operator](./operators-logical.md#or-), as shown in the following example:
 
 ```bicep
 param emptyArray array = []
@@ -76,15 +93,15 @@ output bar bool = length(numberArray) <= 3 || numberArray[3] == 4
 
 ### Array-related operators
 
-* Use [Comparison operators](./operators-comparison.md) to compare two arrays.
-* Use [Index accessor](./operators-access.md#index-accessor) to get an element from an array.
-* Use [Safe-dereference operator](./operator-safe-dereference.md) to access elements of an array.
-* Use [Spread](./operator-spread.md) to merge arrays.
+- Use [Comparison operators](./operators-comparison.md) to compare two arrays.
+- Use [Index accessor](./operators-access.md#index-accessor) to get an element from an array.
+- Use [Safe-dereference operator](./operator-safe-dereference.md) to access elements of an array.
+- Use [Spread](./operator-spread.md) to merge arrays.
 
 ### Array-related functions
 
-* See [Array functions](./bicep-functions-array.md).
-* See [Lambda functions](./bicep-functions-lambda.md).
+- See [Array functions](./bicep-functions-array.md).
+- See [Lambda functions](./bicep-functions-lambda.md).
 
 ## Booleans
 
@@ -94,12 +111,12 @@ When you specify Boolean values, use `true` or `false`. Don't surround the value
 param exampleBool bool = true
 ```
 
-## Boolean-related operators
+### Boolean-related operators
 
-* Use [Comparison operators](./operators-comparison.md) to compare boolean values.
-* See [Logical operators](./operators-logical.md).
+- Use [Comparison operators](./operators-comparison.md) to compare boolean values.
+- See [Logical operators](./operators-logical.md).
 
-## Boolean-related functions
+### Boolean-related functions
 
 See [Logical function](./bicep-functions-logical.md)
 
@@ -140,8 +157,8 @@ Floating point, decimal, or binary formats aren't currently supported.
 
 ### Integer-related operators
 
-* See [Comparison operators](./operators-comparison.md).
-* See [Numeric operators](./operators-numeric.md).
+- See [Comparison operators](./operators-comparison.md).
+- See [Numeric operators](./operators-numeric.md).
 
 ### Integer-related functions
 
@@ -237,10 +254,10 @@ output bar bool = contains(objectToTest, 'four') && objectToTest.four == 4
 
 ### Object-related operators
 
-* Use [Comparison operators](./operators-comparison.md) to compare objects.
-* Use [Index accessor](./operators-access.md#index-accessor) to get a property from an object.
-* Use [Safe-dereference operator](./operator-safe-dereference.md) to access object members.
-* Use [Spread](./operator-spread.md) to merge objects.
+- Use [Comparison operators](./operators-comparison.md) to compare objects.
+- Use [Index accessor](./operators-access.md#index-accessor) to get a property from an object.
+- Use [Safe-dereference operator](./operator-safe-dereference.md) to access object members.
+- Use [Spread](./operator-spread.md) to merge objects.
 
 ### Object-related functions
 
@@ -348,10 +365,11 @@ is ${blocked}'''
 
 ### String-related operators
 
-* See [Comparison operators](./operators-comparison.md).
+- See [Comparison operators](./operators-comparison.md).
 
 ### String-related functions
 
+- See [String functions](./bicep-functions-string.md).
 
 ## Union types
 
@@ -408,14 +426,14 @@ The parameter value is validated based on the discriminated property value. For
 
 The union type has some limitations:
 
-  - Union types must be reducible to a single Azure Resource Manager type. The following definition is invalid:
-    
-    ```bicep
-    type foo = 'a' | 1
-    ```
+- Union types must be reducible to a single Azure Resource Manager type. The following definition is invalid:
+  
+  ```bicep
+  type foo = 'a' | 1
+  ```
 
-  - Only literals are permitted as members.
-  - All literals must be of the same primitive data type (for example, all strings or all integers).
+- Only literals are permitted as members.
+- All literals must be of the same primitive data type (for example, all strings or all integers).
 
 You can use the union type syntax in [user-defined data types](./user-defined-data-types.md).
 

articles/azure-resource-manager/bicep/operators-access.md

@@ -3,7 +3,7 @@ title: Bicep accessor operators
 description: Describes Bicep resource access operator and property access operator.
 ms.topic: reference
 ms.custom: devx-track-bicep
-ms.date: 02/12/2025
+ms.date: 05/20/2025
 ---
 
 # Bicep accessor operators
@@ -13,6 +13,7 @@ The accessor operators are used to access child resources, properties on objects
 | Operator | Name |
 | ---- | ---- |
 | `[]` | [Index accessor](#index-accessor) |
+| `[^index]` | [Reverse index accessor](#reverse-index-accessor) |
 | `.`  | [Function accessor](#function-accessor) |
 | `::` | [Nested resource accessor](#nested-resource-accessor) |
 | `.`  | [Property accessor](#property-accessor) |
@@ -68,6 +69,35 @@ Output from the example:
 | ---- | ---- | ---- |
 | accessorResult | string | 'Development' |
 
+## Reverse index accessor
+
+Beginning with [Bicep CLI version 0.34.x](https://github.com/Azure/bicep/releases/tag/v0.34.1), the reverse index accessor operator (`^`) allows you to retrieve an element from an array by counting from the end. This one-based index means `^1` returns the last item, `^2` the second-to-last, and so on. The index must be a positive integer greater than zero and can be specified as a literal or an expression that evaluates to an integer.
+
+`array[^index]`
+
+If the index exceeds the length of the array, a compilation error occurs for static indices, or a runtime error occurs for dynamic indices.
+
+For constant arrays, the operator is evaluated at compile time. For dynamic inputs, such as [parameters](./parameters.md), evaluation occurs at deployment time.
+
+### Example
+
+```bicep
+var items = [
+  'apple'
+  'banana'
+  'orange'
+  'grape'
+]
+
+output secondToLast string = items[^2]
+```
+
+Output from the example:
+
+| Name | Type | Value |
+| ---- | ---- | ---- |
+| secondToLast | string | 'orange' |
+
 ## Function accessor
 
 `resourceName.functionName()`

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

@@ -3,7 +3,7 @@ title: Bicep operators
 description: Describes the Bicep operators available for Azure Resource Manager deployments.
 ms.topic: reference
 ms.custom: devx-track-bicep, devx-track-arm-template
-ms.date: 02/12/2025
+ms.date: 05/20/2025
 ---
 
 # Bicep operators
@@ -46,6 +46,7 @@ The accessor operators are used to access nested resources and properties on obj
 | Operator | Name | Description |
 | ---- | ---- | ---- |
 | `[]` | [Index accessor](./operators-access.md#index-accessor) | Access an element of an array or property on an object. |
+| `[^index]` | [Reverse index accessor](./operators-access.md#reverse-index-accessor) | Accesses an array element by index, counting from the end of the array (1-based from the end). |
 | `.` | [Function accessor](./operators-access.md#function-accessor) | Call a function on a resource. |
 | `::` | [Nested resource accessor](./operators-access.md#nested-resource-accessor) | Access a nested resource from outside of the parent resource. |
 | `.` | [Property accessor](./operators-access.md#property-accessor) | Access properties of an object. |