IntenseWebs/opentofu
3
0
Fork 0
mirror of https://github.com/opentofu/opentofu.git synced 2025-01-14 02:32:39 -06:00
Code Issues Packages Projects Releases Wiki Activity

Reorder page items and add note about available types to specific verb descriptions

Browse Source
This commit is contained in:
Laura Pacilio 2022-07-05 17:25:08 -04:00
parent 91d6c50ccc
commit 15b59fd6c9
1 changed files with 35 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
website/docs/language/functions/format.mdx
View File

@ -7,7 +7,7 @@ description: |-
# `format` Function
`format` produces a string by formatting a number of other values according
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.
@ -15,8 +15,6 @@ other similar functions in other programming languages.
format(spec, values...)
```
You can use `format` to convert all [Terraform language types](/language/expressions/types#types) into a formatted string, including items of `null`, `list`, and `map` types.
## Examples
```
@ -27,7 +25,7 @@ There are 4 lights
```
Simple format verbs like `%s` and `%d` behave similarly to template
interpolation syntax, which is often more readable:
interpolation syntax, which is often more readable.
```
> format("Hello, %s!", var.name)
@ -36,8 +34,7 @@ Hello, Valentina!
Hello, Valentina!
```
The `format` function is therefore more useful when you use more complex format
specifications, as described in the following section.
The `format` function is most useful when you use more complex format specifications.
## Specification Syntax
@ -47,13 +44,25 @@ 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.
The specification may contain the following verbs:
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, as described below. |
| `%#v` | JSON serialization of the value, as with `jsonencode`. |
| `%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. |
@ -68,7 +77,9 @@ The specification may contain the following verbs:
| `%s` | Convert to string and insert the string's characters. |
| `%q` | Convert to string and produce a JSON quoted string representation. |
When `%v` is used, one of the following format verbs is chosen based on the value type:
### Default Format Verbs
When `%v` is used, Terraform chooses the appropriate format verb based on the value type.
| Type | Verb |
| --------- | ----- |
@ -77,14 +88,14 @@ When `%v` is used, one of the following format verbs is chosen based on the valu
| `bool` | `%t` |
| any other | `%#v` |
Null values produce the string `null` if formatted with `%v` or `%#v`, and
cause an error for other verbs.
Null values produce the string `null` if formatted with `%v` or `%#v`, and cause an error for other verbs.
A width modifier can be included with an optional decimal number immediately
preceding the verb letter, to specify how many characters will be used to
represent the value. Precision can be specified after the (optional) width
with a period (`.`) followed by a decimal number. If width or precision are
omitted then default values are selected based on the given value. For example:
### 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.
| Sequence | Result |
| -------- | ---------------------------- |
@ -93,8 +104,13 @@ omitted then default values are selected based on the given value. For example:
| `%.2f` | Default width, precision 2. |
| `%9.2f` | Width 9, precision 2. |
The following additional symbols can be used immediately after the `%` symbol
to set additional flags:
-> **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 |
| ------ | -------------------------------------------------------------- |
@ -103,19 +119,6 @@ to set additional flags:
| `-` | Pad the width with spaces on the right rather than the left. |
| `0` | Pad the width with leading zeros rather than spaces. |
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.
-> **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.
## Related Functions