Up to date

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

Chaînes de format GDScript

GDScript fournit une fonctionnalité appelée chaîne de formatage qui permet de réutiliser des modèles de texte pour créer succinctement des chaînes différentes mais similaires.

Les chaînes de format sont comme les chaînes normales, sauf qu'elles contiennent certaines séquences de caractères génériques. Ces séquences de caractères génériques peuvent ensuite être facilement remplacés par des paramètres transmis à la chaîne de format.

Par exemple, en utilisant un emplacement réservé tel que %s, la chaîne de format "Hello %s, how are you?" peut facilement être changée en "Hello World, how are you?". Notez la présence de l'emplacement réservé au milieu de la chaîne. Changer celle-ci sans utiliser de chaînes de format peut s'avérer laborieux.

Utilisation en GDScript

Examinez cet exemple concret en 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."

Les emplacements réservés commencent toujours par un %, mais le ou les caractères suivants, le spécificateur de format, détermine comment la valeur donnée est convertie en chaîne.

Le %s vu dans l'exemple ci-dessus est l'emplacement réservé le plus simple et fonctionne pour la plupart des cas d'utilisation : il convertit la valeur par la même méthode par laquelle une conversion de chaîne implicite ou str() la convertirait. Les chaînes restent inchangées, les booléens deviennent soit "True" ou "False", un nombre entier ou réel devient un nombre décimal, les autres types retournent généralement leurs données dans une chaîne de caractère lisible par un être humain.

Il existe également une autre façon de formater du texte dans GDScript, à savoir la méthode String.format (). Elle remplace toutes les occurrences d'une clé dans la chaîne, par la valeur correspondante. La méthode peut gérer des tableaux ou des dictionnaires pour des paires de clé/valeur.

Les tableaux peuvent être utilisés par clé, index ou en style mixte (voir les exemples ci-dessous). L'ordre n'a d'importance que lorsqu'on utilise l'index ou le style mixte de Array.

Un bref exemple en 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"

Il y a d'autres spécificateurs de format, mais ils ne sont applicables que lorsqu'on utilise l'opérateur %.

Emplacements réservés multiples

Les chaînes de formatage peuvent contenir plusieurs emplacements réservés. Dans un tel cas, les valeurs sont présentées sous la forme d'un tableau, une valeur par emplacement réservé (sauf si vous utilisez un spécificateur de format avec *, voir remplissage dynamique) :

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

Notez que les valeurs sont insérées dans l'ordre. À chaque emplacement réservé doit correspondre une valeur. Pensez donc à passer le nombre de valeurs adéquat.

Les spécificateurs de format

Il existe des spécificateurs de format autres que s qui peuvent être utilisés dans les emplacements réservés. Ils consistent en un ou plusieurs caractères. Certains d'entre eux fonctionnent par eux-mêmes comme s, certains apparaissent avant les autres caractères, d'autres ne fonctionnent qu'avec certaines valeurs ou caractères.

Types d'emplacements réservés

Un et un seul d'entre eux doivent toujours apparaître en tant que dernier caractère dans un spécificateur de format. En dehors de s, ceux-ci nécessitent certains types de paramètres.

s

Simple conversion en chaîne par la même méthode que la conversion implicite de chaîne.

c

Un seul caractère Unicode. Attend un entier non signé 8 bits (0-255) pour un point de code ou une chaîne d'un seul caractère.

d

Un nombre entier décimal. Attend un nombre entier ou réel (sera arrondi à l'entier inférieur).

o

Un nombre entier octal. Attend un nombre entier ou réel (sera arrondi à l'entier inférieur).

x

Un nombre entier hexadécimal avec des lettres minuscules. Attend un nombre entier ou réel (sera arrondi à l'entier inférieur).

X

Un nombre entier hexadécimal avec des lettres majuscules. Attend un nombre entier ou réel (sera arrondi à l'entier inférieur).

f

Un nombre décimal réel. Attend un nombre entier ou réel.

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.

Modificateurs d'emplacement réservé

Ces caractères apparaissent avant les précédents. Ils ne fonctionnent que sous certaines conditions.

+

Dans les spécificateurs de nombres, afficher le signe + si positif.

Nombre entier

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.

-

Remplissage à droite plutôt qu'à gauche.

*

Remplissage dynamique, attend un paramètre entier additionnel pour fixer le remplissage ou la précision après ., voir remplissage dynamique.

Remplissage(Padding)

Les caractères . (point), * (astérisque), - (signe moins) et chiffres (0-9) sont utilisés pour le remplissage. Ceci permet d'imprimer plusieurs valeurs alignées verticalement comme dans une colonne, à condition d'utiliser une police à largeur fixe.

Pour remplir une chaîne jusqu'à une longueur minimale, ajoutez un entier au spécificateur :

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

Si l'entier commence par 0, les valeurs entières sont remplies avec des zéros au lieu d'espaces :

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

La précision peut être spécifiée pour les nombres réels en ajoutant un . (point) suivi par un entier. Sans entier après le ., une précision de 0 est utilisée, arrondissant à la valeur entière. L'entier utilisé pour le remplissage doit apparaître avant le point.

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

Le caractère - provoquera le remplissage à droite plutôt qu'à gauche, ce qui est utile pour l'alignement du texte :

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

Remplissage dynamique

En utilisant le caractère * (astérisque), le remplissage ou la précision peuvent être réglés sans modifier la chaîne de format. Il est utilisé à la place d'un entier dans le spécificateur de format. Les valeurs pour le remplissage et la précision sont alors passées lors du formatage :

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

Il est toujours possible de remplir avec des zéros dans les spécificateurs de nombre entiers en ajoutant 0 avant * :

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

Séquence d'échappement

Pour insérer un caractère littéral % dans une chaîne de formatage, il faut l'échapper pour éviter de le lire comme un caractère de remplacement. Cela se fait en doublant le caractère :

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

Exemples de méthodes de formatage

Voici quelques exemples de l'utilisation de différents appels à la méthode String.format.

Type

Style

Exemple

Résultat

Dictionnaire

clé

"Salut, {nom} v{version} !".format({"nom":"Godette", "version":"3.0"})

Salut, Godette v3.0 !

Dictionnaire

index, position

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

Salut, Godette v3.0 !

Dictionnaire

mixte

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

Salut, Godette v3.0 !

Tableau

clé

"Salut, {nom} v{version} !".format([["version":"3.0"],["nom":"Godette"]])

Salut, Godette v3.0 !

Tableau

index, position

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

Salut, Godette v3.0 !

Tableau

mixte

"Salut, {nom} v{0} !".format([3.0, ["nom":"Godette"]])

Salut, Godette v3.0 !

Tableau

pas d'index

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

Salut, Godette v3.0 !

Les emplacements réservés peuvent également être personnalisés lors de l'utilisation de String.format, voici quelques exemples de cette fonctionnalité.

Type

Exemple

Résultat

Infixe (par défaut)

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

Salut, Godette v3.0

Postfixe

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

Salut, Godette v3.0

Préfixe

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

Salut, Godette v3.0

Combiner la méthode String.format et l'opérateur % pourrait être utile puisque String.format n'a pas de possibilité de manipuler une représentation numérique.

Exemple

Résultat

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

Salut, Godette v3.11