Форматирование строки GDScript

Godot предлагает несколько способов динамического изменения содержимого строк:

Формат строки: var string = "У меня %s кошек." % "3"
Метод String.format(): var string = "У меня {0} кошек.".format([3])
Конкатенация строк: var string = "У меня есть " + str(3) + " кошки."

На этой странице объясняется, как использовать строки формата, а также кратко описывается метод format() и конкатенация строк.

Форматировать строки

Format strings (Строки форматирования) — это способ повторного использования текстовых шаблонов для лаконичного создания различных, но похожих строк.

Строки форматирования ничем не отличаются от обычных строк, за исключением того, что они содержат определённые последовательности символов-заполнителей, например %s. Эти заполнители затем можно заменить параметрами, переданными в строку форматирования.

Изучите конкретный пример на GDScript:

# Define a format string with placeholder '%s'
var format_string = "We're waiting for %s."

# Using the '%' operator, the placeholder is replaced with the desired value
var actual_string = format_string % "Godot"

print(actual_string)
# Output: "We're waiting for Godot."

Заполнители всегда начинаются с %, но следующий символ или символы, format specifier, определяют, как данное значение преобразуется в строку.

%s, показанный в примере выше, — это простейший заполнитель (placeholder), подходящий для большинства случаев: он преобразует значение тем же методом, что и неявное преобразование строки или str(). Строки остаются неизменными, логические значения преобразуются либо в "True", либо в "False", int или float становятся decimal, а другие типы обычно возвращают данные в виде строки, удобной для восприятия человеком.

Существуют и другие format specifiers.

Несколько заполнителей

Строки формата могут содержать несколько заполнителей. В этом случае значения передаются в виде массива, по одному значению на каждый заполнитель (если не используется спецификатор формата с *, см. динамическое заполнение):

var format_string = "%s was reluctant to learn %s, but now he enjoys it."
var actual_string = format_string % ["Estragon", "GDScript"]

print(actual_string)
# Output: "Estragon was reluctant to learn GDScript, but now he enjoys it."

Значения вставляются по порядку. Помните, что все заполнители должны быть заменены сразу, поэтому должно быть соответствующее количество значений.

Спецификаторы форматирования

Есть спецификаторы форматирования, кроме s, которые могут быть использованы как заполнители. Они состоят из одного или нескольких символов. Некоторые из них работают сами по себе, как s, некоторые встречаются перед другими символами, некоторые работают только с определенными значениями или символами.

Типы заполнителей

Один и только один из них должен всегда отображаться как последний символ в спецификаторе форматирования. Помимо s, они требуют определенные типы параметров.

`s`	Simple преобразование в строку осуществляется тем же методом, что и неявное преобразование строки.
`c`	Один символ Unicode. Принимает кодовую точку Unicode (целое число) или строку из одного символа. Поддерживает значения свыше 255.
`d`	Десятичное целое число. Ожидается целое или действительное число (будет округлено до меньших значений).
`o`	Восьмеричное целое число. Ожидается целое или действительное число (будет округлено до меньших значений).
`x`	Шестнадцатеричное целое число со строчными буквами. Ожидается целое или действительное число (будет округлено до меньших значений).
`X`	Шестнадцатеричное целое число с заглавными буквами. Ожидается целое или действительное число (будет округлено до меньших значений).
`f`	Десятичное действительное число. Ожидается целое или действительное число.
`v`	Вектор. Ожидает любой векторный объект типа float или int (`Vector2`, `Vector3`, `Vector4`, `Vector2i`, `Vector3i` или `Vector4i`). Координаты вектора будут отображаться в скобках, каждая координата будет отформатирована так, как если бы это был `%f`, и будут использоваться те же модификаторы.

Модификаторы-заполнители

Эти символы появляются перед вышеуказанными. Некоторые из них работают только при определенных условиях.

`+`	В спецификаторах чисел, show + sign показывает знак + если число положительное.
Integer	Задаёт заполнение. Дополняется пробелами или нулями, если целое число начинается с `0` в заполнителе для целых или вещественных чисел. Начальный `0` игнорируется, если присутствует `-`. При использовании после `.` см. `.`.
`.`	Перед `f` или `v` установите precision на 0 знаков после запятой. Можно добавить цифры для изменения. Дополняется нулями.
`-`	Pad to the right заполнение справа, а не слева.
`*`	Динамическое заполнение, ожидает дополнительный целочисленный параметр для установки заполнения или точности после `.`, см. Dynamic padding.

Отступ

Символы . (точка), * (звездочка), - (знак минус) и цифры (0-9) используются для отступов. Это позволяет печатать несколько значений, выровненных по вертикали, как в столбце, при условии, что используется шрифт с фиксированной шириной.

Чтобы заполнить строку до минимальной длины, добавьте целое число в спецификатор:

print("%10d" % 12345)
# output: "     12345"
# 5 leading spaces for a total length of 10

Если целое число начинается с 0, целочисленные значения дополняются нулями вместо пробелов:

print("%010d" % 12345)
# output: "0000012345"

Точность для действительных чисел можно задать, добавив . (точку) с целым числом после него. Если после . не стоит целое число, используется точность 0 с округлением до целых чисел. Целое число, используемое для заполнения, должно находиться перед точкой.

# Pad to minimum length of 10, round to 3 decimal places
print("%10.3f" % 10000.5555)
# Output: " 10000.556"
# 1 leading space

Символ - приведет к отступу справа, а не слева, полезному для выравнивания текста справа:

print("%-10d" % 12345678)
# Output: "12345678  "
# 2 trailing spaces

Динамический отступ

Используя символ * (звездочка), отступ или точность могут быть установлены без изменения формата строки. Он используется вместо целого числа в спецификаторе формата. Затем значения для отступа и точности передаются при форматировании:

var format_string = "%*.*f"
# Pad to length of 7, round to 3 decimal places:
print(format_string % [7, 3, 8.8888])
# Output: "  8.889"
# 2 leading spaces

По-прежнему можно поместить нули в целочисленные заполнители, добавив 0 перед *:

print("%0*d" % [2, 3])
# Output: "03"

Escape-последовательность

Чтобы вставить литерал % в строку форматирования, он должен быть экранирован, чтобы не читать его в качестве заполнителя. Это делается путем дублирования символа:

var health = 56
print("Remaining health: %d%%" % health)
# Output: "Remaining health: 56%"

Метод форматирования строки

В GDScript есть ещё один способ форматирования текста — метод String.format(). Он заменяет все вхождения ключа в строке соответствующим значением. Этот метод может работать с массивами или словарями для пар ключ/значение.

Массивы могут использоваться в качестве ключа, индекса или в смешанном стиле (см. примеры ниже). Порядок имеет значение только при использовании индекса или массива в смешанном стиле.

Быстрый пример на GDScript:

# Define a format string
var format_string = "We're waiting for {str}"

# Using the 'format' method, replace the 'str' placeholder
var actual_string = format_string.format({"str": "Godot"})

print(actual_string)
# Output: "We're waiting for Godot"

Примеры методов форматирования

Ниже приведены некоторые примеры использования различных вызовов метода String.format().

Тип	Стиль	Пример	Результат
Словарь	ключ	"Привет, {name} v{version}!".format({"имя":"Godette", "версия":"3.0"})	Привет, Godette v3.0!
Словарь	индекс	"Привет, {0} v{1}!".format({"0":"Godette", "1":"3.0"})	Привет, Godette v3.0!
Словарь	Сочетание	`"Привет, {0} v{version}!".format({"0":"Godette", "версия":"3.0"})`	Привет, Godette v3.0!
Массив	ключ	`"Привет, {name} v{version}!".format([["версия":"3.0"], ["имя","Godette"])`	Привет, Godette v3.0!
Массив	индекс	`"Привет, {0} v{1}!".format(["Godette","3.0"])`	Привет, Godette v3.0!
Массив	Сочетание	`"Привет, {name} v{0}!".format(["3.0", ["name","Годета"]])`	Привет, Godette v3.0!
Массив	без индекса	`"Привет, {} v{}!".format(["Godette", 3.0], "{}")`	Привет, Godette v3.0!

Заполнители также могут быть настроены при использовании String.format. Вот несколько примеров этого функционала.

Тип	Пример	Результат
Infix (по умолчанию)	`"Привет, {0} v{1}".format(["Godette", "3.0"], "{_}")`	Привет, Godette v3.0
Постфикс	`"Привет, 0% v1%".format(["Godette", "3.0"], "_%")`	Привет, Godette v3.0
Префикс	`"Привет, %0 v%1".format(["Godette", "3.0"], "%_")`	Привет, Godette v3.0

Полезно использовать комбинацию String.format и оператора %, так как String.format не предоставляет возможности управлять представлением чисел.

Пример	Результат
`"Привет, {0} v{version}".format({0:"Godette", "version":"%0.2f" % 3.114})`	Привет, Godette v3.11

Конкатенация строк

Вы также можете объединять строки, соединяя их вместе, используя оператор +.

# Define a base string
var base_string = "We're waiting for "

# Concatenate the string
var actual_string = base_string + "Godot"

print(actual_string)
# Output: "We're waiting for Godot"

При использовании конкатенации строк значения, не являющиеся строками, должны быть преобразованы с помощью функции str(). Указать строковый формат преобразованных значений невозможно.

var name_string = "Godette"
var version = 3.0
var actual_string = "Hi, " + name_string + " v" + str(version) + "!"

print(actual_string)
# Output: "Hi, Godette v3!"

Из-за этих ограничений форматные строки или метод format() часто оказываются более предпочтительным выбором. Во многих случаях конкатенация (concatenation) строк также менее читабельна.

Примечание

В коде Godot на языке C++ доступ к строкам формата GDScript можно получить с помощью вспомогательной функции vformat() в заголовке Variant.