github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/docs/configuration/functions/range.html.md (about)

     1  ---
     2  layout: "functions"
     3  page_title: "range - Functions - Configuration Language"
     4  sidebar_current: "docs-funcs-collection-range"
     5  description: |-
     6    The range function generates sequences of numbers.
     7  ---
     8  
     9  # `range` Function
    10  
    11  -> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and
    12  earlier, see
    13  [0.11 Configuration Language: Interpolation Syntax](../../configuration-0-11/interpolation.html).
    14  
    15  `range` generates a list of numbers using a start value, a limit value,
    16  and a step value.
    17  
    18  ```hcl
    19  range(max)
    20  range(start, limit)
    21  range(start, limit, step)
    22  ```
    23  
    24  The `start` and `step` arguments can be omitted, in which case `start` defaults
    25  to zero and `step` defaults to either one or negative one depending on whether
    26  `limit` is greater than or less than `start`.
    27  
    28  The resulting list is created by starting with the given `start` value and
    29  repeatedly adding `step` to it until the result is equal to or beyond `limit`.
    30  
    31  The interpretation of `limit` depends on the direction of `step`: for a positive
    32  step, the sequence is complete when the next number is greater than or equal
    33  to `limit`. For a negative step, it's complete when less than or equal.
    34  
    35  The sequence-building algorithm follows the following pseudocode:
    36  
    37  ```
    38  let num = start
    39  while num < limit: (or, for negative step, num >= limit)
    40    append num to the sequence
    41    num = num + step
    42  return the sequence
    43  ```
    44  
    45  Because the sequence is created as a physical list in memory, Terraform imposes
    46  an artificial limit of 1024 numbers in the resulting sequence in order to avoid
    47  unbounded memory usage if, for example, a very large value were accidentally
    48  passed as the limit or a very small value as the step. If the algorithm above
    49  would append the 1025th number to the sequence, the function immediately exits
    50  with an error.
    51  
    52  We recommend iterating over existing collections where possible, rather than
    53  creating ranges. However, creating small numerical sequences can sometimes
    54  be useful when combined with other collections in collection-manipulation
    55  functions or `for` expressions.
    56  
    57  ## Examples
    58  
    59  ```
    60  > range(3)
    61  [
    62    0,
    63    1,
    64    2,
    65  ]
    66  
    67  > range(1, 4)
    68  [
    69    1,
    70    2,
    71    3,
    72  ]
    73  
    74  > range(1, 8, 2)
    75  [
    76    1,
    77    3,
    78    5,
    79    7,
    80  ]
    81  
    82  > range(1, 4, 0.5)
    83  [
    84    1,
    85    1.5,
    86    2,
    87    2.5,
    88    3,
    89    3.5,
    90  ]
    91  
    92  > range(4, 1)
    93  [
    94    4,
    95    3,
    96    2,
    97  ]
    98  
    99  > range(10, 5, -2)
   100  [
   101    10,
   102    8,
   103    6,
   104  ]
   105  ```
   106  
   107  The `range` function is primarily useful when working with other collections
   108  to produce a certain number of instances of something. For example:
   109  
   110  ```hcl
   111  variable "name_counts" {
   112    type    = map(number)
   113    default = {
   114      "foo" = 2
   115      "bar" = 4
   116    }
   117  }
   118  
   119  locals {
   120    expanded_names = {
   121      for name, count in var.name_counts : name => [
   122        for i in range(count) : format("%s%02d", name, i)
   123      ]
   124    }
   125  }
   126  
   127  output "expanded_names" {
   128    value = local.expanded_names
   129  }
   130  
   131  # Produces the following expanded_names value when run with the default
   132  # "name_counts":
   133  #
   134  # {
   135  #   "bar" = [
   136  #     "bar00",
   137  #     "bar01",
   138  #     "bar02",
   139  #     "bar03",
   140  #   ]
   141  #   "foo" = [
   142  #     "foo00",
   143  #     "foo01",
   144  #   ]
   145  # }
   146  ```