2018-05-12 18:39:29 +02:00
|
|
|
---
|
|
|
|
layout: "functions"
|
2018-12-20 05:35:11 +01:00
|
|
|
page_title: "element - Functions - Configuration Language"
|
2018-05-12 18:39:29 +02:00
|
|
|
sidebar_current: "docs-funcs-collection-element"
|
|
|
|
description: |-
|
|
|
|
The element function retrieves a single element from a list.
|
|
|
|
---
|
|
|
|
|
|
|
|
# `element` Function
|
|
|
|
|
2019-01-17 01:33:57 +01:00
|
|
|
-> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and
|
|
|
|
earlier, see
|
|
|
|
[0.11 Configuration Language: Interpolation Syntax](../../configuration-0-11/interpolation.html).
|
|
|
|
|
2018-05-12 18:39:29 +02:00
|
|
|
`element` retrieves a single element from a list.
|
|
|
|
|
|
|
|
```hcl
|
|
|
|
element(list, index)
|
|
|
|
```
|
|
|
|
|
|
|
|
The index is zero-based. This function produces an error if used with an
|
2020-10-31 01:42:40 +01:00
|
|
|
empty list. The index must be a non-negative integer.
|
2018-05-12 18:39:29 +02:00
|
|
|
|
|
|
|
Use the built-in index syntax `list[index]` in most cases. Use this function
|
|
|
|
only for the special additional "wrap-around" behavior described below.
|
|
|
|
|
|
|
|
## Examples
|
|
|
|
|
|
|
|
```
|
|
|
|
> element(["a", "b", "c"], 1)
|
|
|
|
b
|
|
|
|
```
|
|
|
|
|
|
|
|
If the given index is greater than the length of the list then the index is
|
|
|
|
"wrapped around" by taking the index modulo the length of the list:
|
|
|
|
|
|
|
|
```
|
|
|
|
> element(["a", "b", "c"], 3)
|
|
|
|
a
|
|
|
|
```
|
|
|
|
|
2020-10-22 20:03:27 +02:00
|
|
|
To get the last element from the list use [`length`](./length.html) to find
|
|
|
|
the size of the list (minus 1 as the list is zero-based) and then pick the
|
|
|
|
last element:
|
|
|
|
|
|
|
|
```
|
|
|
|
> element(["a", "b", "c"], length(["a", "b", "c"])-1)
|
|
|
|
c
|
|
|
|
```
|
|
|
|
|
2018-05-12 18:39:29 +02:00
|
|
|
## Related Functions
|
|
|
|
|
|
|
|
* [`index`](./index.html) finds the index for a particular element value.
|
2018-06-02 03:56:34 +02:00
|
|
|
* [`lookup`](./lookup.html) retrieves a value from a _map_ given its _key_.
|