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

GDScript пропонує функцію під назвою форматований текст, яка дозволяє повторно використовувати текстові шаблони для створення короткого, але схожого тексту.

Форматований текст (рядок, строка) подібний до звичайного тексту (рядка, строки), за винятком того, що вони містять певні послідовності символів-заповнювачів. Ці заповнювачі потім можуть бути легко замінені параметрами, переданими до форматованого тексту.

Наприклад, за допомогою заповнювача %s, форматований текст "Hello %s, how are you? може бути легко змінений на "Hello World, how are you?". Зауважте, що заповнювач знаходиться посередині текста; модифікація його без форматованого тексту може бути громіздкою.

Використання в GDScript

Ознайомтеся з цим конкретним прикладом 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."

Заповнювачі завжди починаються з символу %, але наступний символ, або символи, специфікатор формату, вони визначають, як задане значення перетворюється на текст.

Видимий в наведеному вище прикладі %s є найпростішим заповнювачем і працює для більшості випадків: він перетворює значення тим же методом, що і перетворення String, або str(). Текст залишається незмінним, булеві (логічні) перетворюються на «True», або «False», цілі, чи дійсні, числа перетворюється на десяткові, інші типи зазвичай повертають свої дані у читабельний для людини текст.

Існує також інший спосіб форматування тексту в 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"

Є й інші format specifiers, але вони застосовуються лише при використанні оператора %.

Кілька заповнювачів

Форматований текст може містити кілька заповнювачів. У такому випадку значення передаються у вигляді масиву, одне значення на заповнювач (якщо не використовується специфікатор формату з *, див. dynamic padding):

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 Просте перетворення в String (текст, строку) тим самим методом, що і неявне перетворення.
c Єдиний символ Unicode. Очікує одне 8-бітове ціле число (0-255) для кодової точки, або односимвольного тексту (строки).
d A decimal integral number. Expects an integral or real number (will be floored).
o Вісімкове інтегральне число. Очікує інтегральне, або дійсне, число (буде виведене).
x A hexadecimal integral number with lower-case letters. Expects an integral or real number (will be floored).
X A hexadecimal integral number with upper-case letters. Expects an integral or real number (will be floored).
f Десяткове дійсне число. Очікує ціле, чи дійсне, число.

Модифікатори заповнювачів

Ці символи з’являються раніше. Деякі з них працюють лише за певних умов.

+ У специфікаторах чисел, **покажіть + знак**(show + sign), якщо число позитивне.
Integer (ціле) Встановити заповнювачі. Заповнені пробілами, або нулями, якщо ціле число починається з 0 в цілочисельному заповнювачі. При використанні після ., дивіться ..
. Before f, set precision to 0 decimal places. Can be followed up with numbers to change. Padded with zeroes.
- Заповнення справа (Pad to the right), а не зліва.
* Dynamic padding, expect additional integral parameter to set padding or precision after ., see dynamic padding.

Фаска

The . (dot), * (asterisk), - (minus sign) and digit (0-9) characters are used for padding. This allows printing several values aligned vertically as if in a column, provided a fixed-width font is used.

Щоб заповнити рядок до мінімальної довжини додайте ціле число до специфікатора:

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

Dynamic padding

By using the * (asterisk) character, the padding or precision can be set without modifying the format string. It is used in place of an integer in the format specifier. The values for padding and precision are then passed when formatting:

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

It is still possible to pad with zeroes in integer placeholders by adding 0 before *:

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

Escape sequence

To insert a literal % character into a format string, it must be escaped to avoid reading it as a placeholder. This is done by doubling the character:

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

Format method examples

The following are some examples of how to use the various invocations of the String.format method.

Тип Стиль Приклад Результат
Dictionary key "Hi, {name} v{version}!".format({"name":"Godette", "version":"3.0"}) Hi, Godette v3.0!
Dictionary index "Hi, {0} v{1}!".format({"0":"Godette", "1":"3.0"}) Hi, Godette v3.0!
Dictionary суміш "Hi, {0} v{version}!".format({"0":"Godette", "version":"3.0"}) Hi, Godette v3.0!
Array key "Hi, {name} v{version}!".format([["version","3.0"], ["name","Godette"]]) Hi, Godette v3.0!
Array index "Hi, {0} v{1}!".format(["Godette","3.0"]) Hi, Godette v3.0!
Array суміш "Hi, {name} v{0}!".format([3.0, ["name","Godette"]]) Hi, Godette v3.0!
Array no index "Hi, {} v{}!".format(["Godette", 3.0], "{}") Hi, Godette v3.0!

Placeholders can also be customized when using String.format, here’s some examples of that functionality.

Тип Приклад Результат
Infix (default) "Hi, {0} v{1}".format(["Godette", "3.0"], "{_}") Hi, Godette v3.0
Суфікс "Hi, 0% v1%".format(["Godette", "3.0"], "_%") Hi, Godette v3.0
Префікс "Hi, %0 v%1".format(["Godette", "3.0"], "%_") Hi, Godette v3.0

Combining both the String.format method and the % operator could be useful, as String.format does not have a way to manipulate the representation of numbers.

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