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