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 espace réservé tel que %s, la chaîne de format "Salut %s, ça va ?" peut facilement être changée en "Salut l'ami, ça va ?". Notez la présence de l’espace 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 espaces 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’espace 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 %.

Espaces réservés multiples

Les chaînes de formatage peuvent contenir plusieurs espaces réservés. Dans un tel cas, les valeurs sont présentées sous la forme d’un tableau, une valeur par espace 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 espace 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 espaces 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’espaces 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.

Modificateurs d’espace 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 Fixe le remplissage. Remplit avec des espaces ou des zéros si l’entier commence par 0 dans un spécificateur de nombre entier. Quand il est utilisé après un .``voir ``..
. Avant f, fixe la précision à 0 décimales. Peut être suivi d’un nombre pour la modifier. Remplit par des zéros.
- 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

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

Rembourrage 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 "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 "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 espaces 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