github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/job-specification/hcl2/functions/collection/range.mdx (about)

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