Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Formátovací řetězce GDScriptu

GDScript nabízí vlastnost nazvanou formátové řetězce, která umožňuje opakované použití textových šablon pro rychlé vytváření podobných řetězců.

Formátovací řetězce jsou stejné jako normální řetězce, jen obsahují určité zástupné znaky. Tyto zástupné znaky pak lze snadno nahradit parametry předanými formátovacímu řetězci.

Například s %s jako zástupným znakem lze formátovací řetězec "Hello %s, how are you?` snadno změnit na "Hello World, how are you?". Všimněte si, že zástupný znak je uprostřed řetězce; jeho úprava by bez formátovacích řetězců mohla být těžkopádná.

Použití v GDScriptu

Prohlédněte si tento konkrétní příklad 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."

Zástupné znaky vždy začínají znakem %, ale další znak nebo znaky, specifikátor formátu, určují, jak bude daná hodnota převedena na řetězec.

%s, který vidíte ve výše uvedeném příkladu, je nejjednodušší zástupný znak a funguje pro většinu případů: převádí hodnotu stejným způsobem, jakou by ji převedl implicitní převod řetězce nebo str(). Řetězce zůstanou beze změny, logické hodnoty se transformují buď na "True" nebo "False", celé nebo reálné číslo se změní na desetinné, ostatní typy obvykle vracejí svá data v lidsky čitelné podobě.

V jazyce GDScript existuje také další způsob formátování textu, a to metoda String.format()`. Ta nahradí všechny výskyty určitého znaku v řetězci určitou hodnotou. Metoda může pracovat s poli nebo slovníky pro dvojice klíč/hodnota.

Pole lze použít s klíči nebo indexy, oba styly lze i kombinovat (viz příklady níže). Na pořadí záleží pouze při použití indexového nebo smíšeného stylu pole.

Rychlý příklad v 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"

Existují i další formátové specifikátory, ale ty jsou použitelné pouze při použití operátoru %.

Více zástupných symbolů

Formátovací řetězce mohou obsahovat více zástupných znaků. V takovém případě jsou hodnoty předávány ve formě pole, jedna hodnota na každý zástupný znak (pokud není použit specifikátor formátu s *, viz dynamické vyplňování):

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."

Všimněte si, že hodnoty jsou vkládány popořádku. Nezapomeňte, že všechny zástupné symboly musí být nahrazeny najednou, takže je potřeba i odpovídající počet hodnot.

Specifikátory formátu

V zástupných znacích lze použít i jiné specifikátory formátu než s. Skládají se z jednoho nebo více znaků. Některé z nich fungují samy o sobě podobně jako s, některé se objevují před jinými znaky, některé fungují pouze s určitými hodnotami nebo znaky.

Typy zástupných symbolů

Jeden a to právě jeden z nich se musí vždy objevit jako poslední znak ve specifikátoru formátu. Kromě s vyžadují všechny ostatní určité typy parametrů.

s

Jednoduchý převod na řetězec pomocí implicitní metody konverze na String.

c

Jeden znak Unicode. Očekává 8bitové celé číslo bez znaménka (0-255) pro codepoint nebo jednoznakový řetězec.

d

desítkové celé číslo. Očekává celé nebo reálné číslo (bude zaokrouhleno).

o

osmičkové celé číslo. Očekává celé nebo reálné číslo (bude zaokrouhleno).

x

hexadecimální celé číslo s malými písmeny. Očekává celé nebo reálné číslo (bude zaokrouhleno).

X

hexadecimální celé číslo s velkými písmeny. Očekává celé nebo reálné číslo (bude zaokrouhleno).

f

desítkové reálné číslo. Očekává celé nebo reálné číslo.

v

A vector. Expects any float or int-based vector object ( Vector2, Vector3, Vector4, Vector2i, Vector3i or Vector4i). Will display the vector coordinates in parentheses, formatting each coordinate as if it was an %f, and using the same modifiers.

Modifikátory zástupných symbolů

Tyto znaky se objevují před výše uvedenými. Některé z nich fungují pouze za určitých podmínek.

+

V číselných specifikátorech zobrazí znaménko +, pokud je kladné.

Číslo

Set padding. Padded with spaces or with zeroes if integer starts with 0 in an integer or real number placeholder. The leading 0 is ignored if - is present. When used after ., see ..

.

Before f or v, set precision to 0 decimal places. Can be followed up with numbers to change. Padded with zeroes.

-

Zarovnává doprava, nikoli doleva.

*

Dynamické vyplňování, očekávejte další celočíselný parametr pro nastavení vyplňování nebo přesnosti za ., viz dynamické vyplňování.

Zarovnávání

Znaky .` (tečka), * (hvězdička), - (minus) a číslice (0-9) se používají pro zarovnávání. To umožňuje tisk několika hodnot zarovnaných vertikálně jako ve sloupci, pokud je použito písmo s pevnou šířkou.

Chcete-li řetězec zarovnat na minimální délku, přidejte ke specifikátoru celé číslo:

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

Pokud celé číslo začíná 0, jsou celočíselné hodnoty doplněny nulami namísto mezer:

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

Přesnost lze u reálných čísel zadat přidáním znaku . (tečka), za kterým následuje celé číslo. Bez uvedení celého čísla za . se použije přesnost 0 se zaokrouhlením na celočíselnou hodnotu. Celé číslo, které se má použít pro zarovnání, se musí objevit před tečkou.

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

Znak - způsobí zarovnání vpravo, nikoli vlevo, což je užitečné pro zarovnávání textu vpravo:

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

Dynamické zarovnávání

Pomocí znaku *` (hvězdička) lze nastavit zarovnání nebo přesnost bez úpravy formátovacího řetězce. Používá se místo celého čísla ve specifikátoru formátu. Hodnoty pro zarovnání a přesnost se pak předávají při formátování:

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

V celočíselných zástupných znacích je stále možné zarovnávat nulami přidáním 0` před *:

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

Escape sekvence

Chcete-li do formátovacího řetězce vložit prostý znak %, je třeba jej escapovat. Tak se zabrání jeho čtení jako zástupného znaku. Toto se provádí zdvojením znaku:

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

Příklady formátovacích metod

Následuje několik příkladů použití různých volání metody String.format.

Typ

Styl

Příklad

Výsledek

Slovník

klíč

"Hi, {name} v{version}!".format({"name":"Godette", "version":"3.0"})

Hi, Godette v3.0!

Slovník

index

"Hi, {0} v{1}!".format({"0":"Godette", "1":"3.0"})

Hi, Godette v3.0!

Slovník

mix

"Hi, {0} v{version}!".format({"0":"Godette", "version":"3.0"})

Hi, Godette v3.0!

Pole

klíč

"Hi, {name} v{version}!".format([["version","3.0"], ["name","Godette"]])

Hi, Godette v3.0!

Pole

index

"Hi, {0} v{1}!".format(["Godette","3.0"])

Hi, Godette v3.0!

Pole

mix

"Hi, {name} v{0}!".format([3.0, ["name","Godette"]])

Hi, Godette v3.0!

Pole

žádný index

"Hi, {} v{}!".format(["Godette", 3.0], "{}")

Hi, Godette v3.0!

Zástupné znaky lze také přizpůsobit pomocí String.format, zde je několik příkladů této funkce.

Typ

Příklad

Výsledek

Infix (výchozí)

"Hi, {0} v{1}".format(["Godette", "3.0"], "{_}")

Hi, Godette v3.0

Postfix

"Hi, 0% v1%".format(["Godette", "3.0"], "_%")

Hi, Godette v3.0

Prefix

"Hi, %0 v%1".format(["Godette", "3.0"], "%_")

Hi, Godette v3.0

Kombinace metody String.format a operátoru % by mohla být užitečná, protože String.format nemá možnost manipulovat s reprezentací čísel.

Příklad

Výsledek

"Hi, {0} v{version}".format({0:"Godette", "version":"%0.2f" % 3.114})

Hi, Godette v3.11