github.com/eliastor/durgaform@v0.0.0-20220816172711-d0ab2d17673e/website/docs/language/functions/format.mdx (about)

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