github.com/hugorut/terraform@v1.1.3/website/docs/language/functions/one.mdx (about)

     1  ---
     2  page_title: one - Functions - Configuration Language
     3  description: |-
     4    The 'one' function transforms a list with either zero or one elements into
     5    either a null value or the value of the first element.
     6  ---
     7  
     8  # `one` Function
     9  
    10  -> **Note:** This function is available only in Terraform v0.15 and later.
    11  
    12  `one` takes a list, set, or tuple value with either zero or one elements.
    13  If the collection is empty, `one` returns `null`. Otherwise, `one` returns
    14  the first element. If there are two or more elements then `one` will return
    15  an error.
    16  
    17  This is a specialized function intended for the common situation where a
    18  conditional item is represented as either a zero- or one-element list, where
    19  a module author wishes to return a single value that might be null instead.
    20  
    21  For example:
    22  
    23  ```hcl
    24  variable "include_ec2_instance" {
    25    type    = bool
    26    default = true
    27  }
    28  
    29  resource "aws_instance" "example" {
    30    count = var.include_ec2_instance ? 1 : 0
    31  
    32    # (other resource arguments...)
    33  }
    34  
    35  output "instance_ip_address" {
    36    value = one(aws_instance.example[*].private_ip)
    37  }
    38  ```
    39  
    40  Because the `aws_instance` resource above has the `count` argument set to a
    41  conditional that returns either zero or one, the value of
    42  `aws_instance.example` is a list of either zero or one elements. The
    43  `instance_ip_address` output value uses the `one` function as a concise way
    44  to return either the private IP address of a single instance, or `null` if
    45  no instances were created.
    46  
    47  ## Relationship to the "Splat" Operator
    48  
    49  The Terraform language has a built-in operator `[*]`, known as
    50  [the _splat_ operator](/language/expressions/splat), and one of its functions
    51  is to translate a primitive value that might be null into a list of either
    52  zero or one elements:
    53  
    54  ```hcl
    55  variable "ec2_instance_type" {
    56    description = "The type of instance to create. If set to null, no instance will be created."
    57  
    58    type    = string
    59    default = null
    60  }
    61  
    62  resource "aws_instance" "example" {
    63    count = length(var.ec2_instance_type[*])
    64  
    65    instance_type = var.ec2_instance_type
    66    # (other resource arguments...)
    67  }
    68  
    69  output "instance_ip_address" {
    70    value = one(aws_instance.example[*].private_ip)
    71  }
    72  ```
    73  
    74  In this case we can see that the `one` function is, in a sense, the opposite
    75  of applying `[*]` to a primitive-typed value. Splat can convert a possibly-null
    76  value into a zero-or-one list, and `one` can reverse that to return to a
    77  primitive value that might be null.
    78  
    79  ## Examples
    80  
    81  ```
    82  > one([])
    83  null
    84  > one(["hello"])
    85  "hello"
    86  > one(["hello", "goodbye"])
    87  
    88  Error: Invalid function argument
    89  
    90  Invalid value for "list" parameter: must be a list, set, or tuple value with
    91  either zero or one elements.
    92  ```
    93  
    94  ### Using `one` with sets
    95  
    96  The `one` function can be particularly helpful in situations where you have a
    97  set that you know has only zero or one elements. Set values don't support
    98  indexing, so it's not valid to write `var.set[0]` to extract the "first"
    99  element of a set, but if you know that there's only one item then `one` can
   100  isolate and return that single item:
   101  
   102  ```
   103  > one(toset([]))
   104  null
   105  > one(toset(["hello"]))
   106  "hello"
   107  ```
   108  
   109  Don't use `one` with sets that might have more than one element. This function
   110  will fail in that case:
   111  
   112  ```
   113  > one(toset(["hello","goodbye"]))
   114  
   115  Error: Invalid function argument
   116  
   117  Invalid value for "list" parameter: must be a list, set, or tuple value with
   118  either zero or one elements.
   119  ```