format Function
Функция 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.10/language/functions/format/
