跳至主要内容

format 函数

format 函数根据规范字符串格式化多个其他值，生成一个字符串。它类似于 C 语言中的 printf 函数，以及其他编程语言中的类似函数。

代码块
format(spec, values...)

示例​

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

像 %s 和 %d 这样的简单格式化动词的行为类似于模板插值语法，后者通常更易读。

代码块
> format("Hello, %s!", var.name)
Hello, Valentina!
> "Hello, ${var.name}!"
Hello, Valentina!

格式化动词 %#v 接受任何类型的值，并使用 JSON 编码呈现它，类似于 jsonencode。这对于在 自定义条件检查 错误消息中描述提供给模块的值很有用。

代码块
> 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 函数最有用。

规范语法​

规范是一个包含以 % 字符开头的格式化动词的字符串。然后，函数调用必须为规范中的每个动词序列提供一个额外的参数。动词与连续的参数匹配并根据指示进行格式化，只要每个给定的参数都可以转换为格式化动词所需的类型。

默认情况下，% 序列从第一个开始消耗后续的参数。在动词字母之前立即引入 [n] 序列，其中 n 是一个十进制整数，通过其基于 1 的索引显式选择特定值参数。然后，后续的调用不带显式索引将继续使用 n+1、n+2 等。

如果格式字符串请求不可能的转换或访问比给定的参数更多的参数，则函数会产生错误。对于不支持的格式化动词也会产生错误。

动词​

规范可以包含以下动词。

动词结果
%%字面百分号，不消耗任何值。
%v基于 值类型 的默认格式化。接受所有类型，包括 null、list 和 map 类型的项。
%#v值的 JSON 序列化，与 jsonencode 相同。接受所有类型，包括 null、list 和 map 类型的项。
%t转换为布尔值并生成 true 或 false。
%b转换为整数并生成二进制表示形式。
%d转换为整数并生成十进制表示形式。
%o转换为整数并生成八进制表示形式。
%x转换为整数并生成使用小写字母的十六进制表示形式。
%X与 %x 相同，但使用大写字母。
%e转换为数字并生成科学记数法，例如 -1.234456e+78。
%E与 %e 相同，但使用大写 E 来引入指数。
%f转换为数字并生成没有指数的小数表示形式，例如 123.456。
%g对于大指数，类似于 %e；否则，类似于 %f。
%G对于大指数，类似于 %E；否则，类似于 %f。
%s转换为字符串并插入字符串的字符。
%q转换为字符串并生成 JSON 引号字符串表示形式。

默认格式化动词​

当使用 %v 时，OpenTofu 会根据值类型选择合适的格式化动词。

类型动词
字符串%s
数字%g
布尔值%t
任何其他类型%#v

如果使用 %v 或 %#v 格式化，空值会生成字符串 null，而对于其他动词则会导致错误。

宽度修饰符​

使用宽度修饰符，并在动词字母前紧跟一个可选的小数，以指定表示值的字符数。您可以在（可选）宽度之后使用句点 (.) 后跟一个小数来指定精度。如果省略宽度或精度，OpenTofu 将根据给定值选择默认值。

以下示例演示了宽度修饰符的用例。

序列结果
%f默认宽度和精度。
%9f宽度为 9，默认精度。
%.2f默认宽度，精度为 2。
%9.2f宽度为 9，精度为 2。

其他格式选项​

在%符号后立即使用以下符号来设置其他格式要求。

符号结果
空格如果数字为正，则在符号所在位置保留一个空格。
+显示数字的符号，即使它是正数。
-在右侧而不是左侧用空格填充宽度。
0用前导零而不是空格填充宽度。
  • formatdate 是一个用于生成人类可读时间戳的专用格式化函数。
  • formatlist 使用相同的规范语法生成字符串列表。