format Функция
Функция format формирует строку, форматируя несколько других значений согласно строке спецификации. Она похожа на функцию printf в C и аналогичные функции в других языках программирования.
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 — десятичное целое число, то можно явно выбрать аргумент по его порядковому номеру, начиная с единицы. При последующих вызовах без явно заданного индекса будут использоваться аргументы 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 выбирает подходящий спецификатор формата в зависимости от типа значения.
| Тип | Спецификатор |
|---|---|
string |
%s |
number |
%g |
bool |
%t |
| любой другой | %#v |
При форматировании с помощью %v или %#v значения null преобразуются в строку null, а при использовании других спецификаторов вызывают ошибку.
Модификатор ширины
Чтобы указать, сколько символов будет использоваться для представления значения, добавьте модификатор ширины с необязательным десятичным числом непосредственно перед буквой спецификатора. После ширины (если она указана) можно задать точность: поставьте точку (.), а затем десятичное число. Если ширина или точность не заданы, OpenTofu выбирает значения по умолчанию на основе переданного значения.
В следующих примерах показаны варианты использования модификатора ширины.
| Последовательность | Результат |
|---|---|
%f |
Ширина и точность по умолчанию. |
%9f |
Ширина 9, точность по умолчанию. |
%.2f |
Ширина по умолчанию, точность 2. |
%9.2f |
Ширина 9, точность 2. |
Модификаторы ширины и точности для нечисловых типов, таких как строки (%s), интерпретируются иначе. Указание нулевой ширины или точности равносильно их отсутствию.
Дополнительные параметры форматирования
Используйте следующие символы сразу после символа %, чтобы задать дополнительные требования к форматированию.
| Символ | Результат |
|---|---|
| пробел | Оставляет пробел на месте знака числа, если число положительное. |
+ |
Выводит знак числа, даже если оно положительное. |
- |
Дополняет значение пробелами справа, а не слева. |
0 |
Дополняет значение нулями слева, а не пробелами. |
Связанные функции
-
formatdate— специализированная функция форматирования временных меток в удобном для чтения виде. -
formatlistиспользует тот же синтаксис спецификации для создания списка строк.
Copyright (c) The OpenTofu Authors
Copyright (c) 2014 HashiCorp, Inc.
Mozilla Public License, version 2.0
https://opentofu.org/docs/v1.9/language/functions/format/
