»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.

format(spec, values...)

format(spec, values...)

»Examples

> format("Hello, %s!", "Ander")
Hello, Ander!
> format("There are %d lights", 4)
There are 4 lights

> 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!

> 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 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"

> 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.

»Default Format Verbs

When %v is used, Terraform chooses the appropriate format verb based on the value type.

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, Terraform selects default values based on the given value.

The following examples demonstrate example use cases for the width modifier.

»Additional Format Options

Use the following symbols immediately after the % symbol to set additional formatting requirements.

»Related Functions

• formatdate is a specialized formatting function for human-readable timestamps.
• formatlist uses the same specification syntax to produce a list of strings.