github.com/muratcelep/terraform@v1.1.0-beta2-not-internal-4/website/docs/language/functions/one.html.md (about)

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