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.11/language/functions/format/
