github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/docs/job-specification/hcl2/functions/collection/range.mdx (about)

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