| --- | |
| sidebar_label: format | |
| description: |- | |
| The format function produces a string by formatting a number of other values | |
| according to a specification string. | |
| --- | |
| # `format` Function | |
| The `format` function produces a string by formatting a number of other values according | |
| to a specification string. It is similar to the `printf` function in C, and | |
| other similar functions in other programming languages. | |
| ```hcl | |
| format(spec, values...) | |
| ``` | |
| ## Examples | |
| ``` | |
| > format("Hello, %s!", "Ander") | |
| Hello, Ander! | |
| > format("There are %d lights", 4) | |
| There are 4 lights | |
| ``` | |
| Simple format verbs like `%s` and `%d` behave similarly to template | |
| interpolation syntax, which is often more readable. | |
| ``` | |
| > format("Hello, %s!", var.name) | |
| Hello, Valentina! | |
| > "Hello, ${var.name}!" | |
| Hello, Valentina! | |
| ``` | |
| 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.mdx#error-messages) error messages. | |
| ``` | |
| > format("%#v", "hello") | |
| "\"hello\"" | |
| > format("%#v", true) | |
| "true" | |
| > format("%#v", 1) | |
| "1" | |
| > format("%#v", {a = 1}) | |
| "{\"a\":1}" | |
| > format("%#v", [true]) | |
| "[true]" | |
| > format("%#v", null) | |
| "null" | |
| ``` | |
| The `format` function is most useful when you use more complex format specifications. | |
| ## Specification Syntax | |
| The specification is a string that includes formatting verbs that are introduced | |
| with the `%` character. The function call must then have one additional argument | |
| for each verb sequence in the specification. The verbs are matched with | |
| consecutive arguments and formatted as directed, as long as each given argument | |
| is convertible to the type required by the format verb. | |
| By default, `%` sequences consume successive arguments starting with the first. | |
| Introducing a `[n]` sequence immediately before the verb letter, where `n` is a | |
| decimal integer, explicitly chooses a particular value argument by its | |
| one-based index. Subsequent calls without an explicit index will then proceed | |
| with `n`+1, `n`+2, etc. | |
| The function produces an error if the format string requests an impossible | |
| conversion or access more arguments than are given. An error is produced also | |
| for an unsupported format verb. | |
| ### Verbs | |
| The specification may contain the following verbs. | |
| | Verb | Result | | |
| | ----- | ----------------------------------------------------------------------------------------- | | |
| | `%%` | Literal percent sign, consuming no value. | | |
| | `%v` | Default formatting based on the [value type](#default-format-verbs). Accepts all types, including items of `null`, `list`, and `map` types. | | |
| | `%#v` | JSON serialization of the value, as with `jsonencode`. Accepts all types, including items of `null`, `list`, and `map` types. | | |
| | `%t` | Convert to boolean and produce `true` or `false`. | | |
| | `%b` | Convert to integer number and produce binary representation. | | |
| | `%d` | Convert to integer number and produce decimal representation. | | |
| | `%o` | Convert to integer number and produce octal representation. | | |
| | `%x` | Convert to integer number and produce hexadecimal representation with lowercase letters. | | |
| | `%X` | Like `%x`, but use uppercase letters. | | |
| | `%e` | Convert to number and produce scientific notation, like `-1.234456e+78`. | | |
| | `%E` | Like `%e`, but use an uppercase `E` to introduce the exponent. | | |
| | `%f` | Convert to number and produce decimal fraction notation with no exponent, like `123.456`. | | |
| | `%g` | Like `%e` for large exponents or like `%f` otherwise. | | |
| | `%G` | Like `%E` for large exponents or like `%f` otherwise. | | |
| | `%s` | Convert to string and insert the string's characters. | | |
| | `%q` | Convert to string and produce a JSON quoted string representation. | | |
| ### Default Format Verbs | |
| When `%v` is used, OpenTofu chooses the appropriate format verb based on the value type. | |
| | Type | Verb | | |
| | --------- | ----- | | |
| | `string` | `%s` | | |
| | `number` | `%g` | | |
| | `bool` | `%t` | | |
| | any other | `%#v` | | |
| Null values produce the string `null` if formatted with `%v` or `%#v`, and cause an error for other verbs. | |
| ### Width Modifier | |
| Use a width modifier with an optional decimal number immediately | |
| 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, OpenTofu selects default values based on the given value. | |
| The following examples demonstrate example use cases for the width modifier. | |
| | Sequence | Result | | |
| | -------- | ---------------------------- | | |
| | `%f` | Default width and precision. | | |
| | `%9f` | Width 9, default precision. | | |
| | `%.2f` | Default width, precision 2. | | |
| | `%9.2f` | Width 9, precision 2. | | |
| :::note | |
| Width and precision modifiers with non-numeric types such as | |
| strings (`%s`) are interpreted differently. Setting either width or precision to | |
| zero is the same as not including them at all. | |
| ::: | |
| ### Additional Format Options | |
| Use the following symbols immediately after the `%` symbol to set additional formatting requirements. | |
| | Symbol | Result | | |
| | ------ | -------------------------------------------------------------- | | |
| | space | Leave a space where the sign would be if a number is positive. | | |
| | `+` | Show the sign of a number even if it is positive. | | |
| | `-` | Pad the width with spaces on the right rather than the left. | | |
| | `0` | Pad the width with leading zeros rather than spaces. | | |
| ## Related Functions | |
| * [`formatdate`](../../language/functions/formatdate.mdx) is a specialized formatting function for | |
| human-readable timestamps. | |
| * [`formatlist`](../../language/functions/formatlist.mdx) uses the same specification syntax to | |
| produce a list of strings. |