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

     1  ---
     2  layout: "functions"
     3  page_title: "format - Functions - Configuration Language"
     4  sidebar_current: "docs-funcs-string-format-x"
     5  description: |-
     6    The format function produces a string by formatting a number of other values
     7    according to a specification string.
     8  ---
     9  
    10  # `format` Function
    11  
    12  -> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and
    13  earlier, see
    14  [0.11 Configuration Language: Interpolation Syntax](../../configuration-0-11/interpolation.html).
    15  
    16  `format` produces a string by formatting a number of other values according
    17  to a specification string. It is similar to the `printf` function in C, and
    18  other similar functions in other programming languages.
    19  
    20  ```hcl
    21  format(spec, values...)
    22  ```
    23  
    24  ## Examples
    25  
    26  ```
    27  > format("Hello, %s!", "Ander")
    28  Hello, Ander!
    29  > format("There are %d lights", 4)
    30  There are 4 lights
    31  ```
    32  
    33  Simple format verbs like `%s` and `%d` behave similarly to template
    34  interpolation syntax, which is often more readable:
    35  
    36  ```
    37  > format("Hello, %s!", var.name)
    38  Hello, Valentina!
    39  > "Hello, ${var.name}!"
    40  Hello, Valentina!
    41  ```
    42  
    43  The `format` function is therefore more useful when you use more complex format
    44  specifications, as described in the following section.
    45  
    46  ## Specification Syntax
    47  
    48  The specification is a string that includes formatting verbs that are introduced
    49  with the `%` character. The function call must then have one additional argument
    50  for each verb sequence in the specification. The verbs are matched with
    51  consecutive arguments and formatted as directed, as long as each given argument
    52  is convertible to the type required by the format verb.
    53  
    54  The specification may contain the following verbs:
    55  
    56  | Verb  | Result                                                                                    |
    57  | ----- | ----------------------------------------------------------------------------------------- |
    58  | `%%`  | Literal percent sign, consuming no value.                                                 |
    59  | `%v`  | Default formatting based on the value type, as described below.                           |
    60  | `%#v` | JSON serialization of the value, as with `jsonencode`.                                    |
    61  | `%t`  | Convert to boolean and produce `true` or `false`.                                         |
    62  | `%b`  | Convert to integer number and produce binary representation.                              |
    63  | `%d`  | Convert to integer number and produce decimal representation.                             |
    64  | `%o`  | Convert to integer number and produce octal representation.                               |
    65  | `%x`  | Convert to integer number and produce hexadecimal representation with lowercase letters.  |
    66  | `%X`  | Like `%x`, but use uppercase letters.                                                     |
    67  | `%e`  | Convert to number and produce scientific notation, like `-1.234456e+78`.                  |
    68  | `%E`  | Like `%e`, but use an uppercase `E` to introduce the exponent.                            |
    69  | `%f`  | Convert to number and produce decimal fraction notation with no exponent, like `123.456`. |
    70  | `%g`  | Like `%e` for large exponents or like `%f` otherwise.                                     |
    71  | `%G`  | Like `%E` for large exponents or like `%f` otherwise.                                     |
    72  | `%s`  | Convert to string and insert the string's characters.                                     |
    73  | `%q`  | Convert to string and produce a JSON quoted string representation.                        |
    74  
    75  When `%v` is used, one of the following format verbs is chosen based on the value type:
    76  
    77  | Type      | Verb  |
    78  | --------- | ----- |
    79  | `string`  | `%s`  |
    80  | `number`  | `%g`  |
    81  | `bool`    | `%t`  |
    82  | any other | `%#v` |
    83  
    84  Null values produce the string `null` if formatted with `%v` or `%#v`, and
    85  cause an error for other verbs.
    86  
    87  A width modifier can be included with an optional decimal number immediately
    88  preceding the verb letter, to specify how many characters will be used to
    89  represent the value. Precision can be specified after the (optional) width
    90  with a period (`.`) followed by a decimal number. If width or precision are
    91  omitted then default values are selected based on the given value. For example:
    92  
    93  | Sequence | Result                       |
    94  | -------- | ---------------------------- |
    95  | `%f`     | Default width and precision. |
    96  | `%9f`    | Width 9, default precision.  |
    97  | `%.2f`   | Default width, precision 2.  |
    98  | `%9.2f`  | Width 9, precision 2.        |
    99  
   100  The following additional symbols can be used immediately after the `%` symbol
   101  to set additoinal flags:
   102  
   103  | Symbol | Result                                                         |
   104  | ------ | -------------------------------------------------------------- |
   105  | space  | Leave a space where the sign would be if a number is positive. |
   106  | `+`    | Show the sign of a number even if it is positive.              |
   107  | `-`    | Pad the width with spaces on the left rather than the right.   |
   108  | `0`    | Pad the width with leading zeros rather than spaces.           |
   109  
   110  By default, `%` sequences consume successive arguments starting with the first.
   111  Introducing a `[n]` sequence immediately before the verb letter, where `n` is a
   112  decimal integer, explicitly chooses a particular value argument by its
   113  one-based index. Subsequent calls without an explicit index will then proceed
   114  with `n`+1, `n`+2, etc.
   115  
   116  The function produces an error if the format string requests an impossible
   117  conversion or access more arguments than are given. An error is produced also
   118  for an unsupported format verb.
   119  
   120  ## Related Functions
   121  
   122  * [`formatdate`](./formatdate.html) is a specialized formatting function for
   123    human-readable timestamps.
   124  * [`formatlist`](./formatlist.html) uses the same specification syntax to
   125    produce a list of strings.