GDScript format strings

format strings, which allows reusing text templates to succinctly create different but similar strings. Format strings are just like normal strings, except they contain certain placeholder character-sequences. These placeholders can then easily be replaced by parameters handed to the format string. %s as a placeholder, the format string "Hello %s, how are you?" can easily be changed to "Hello World, how are you?". Notice the placeholder is in the middle of the string; modifying it without format strings could be cumbersome.

Usage in GDScript

Examine this concrete GDScript example:

  1. # 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 valuevar actual_string = format_string % "Godot"print(actual_string)# Output: "We're waiting for Godot."

%, but the next character or characters, the format specifier, determines how the given value is converted to a string. %s seen in the example above is the simplest placeholder and works for most use cases: it converts the value by the same method by which an implicit String conversion or str() would convert it. Strings remain unchanged, Booleans turn into either "True" or "False", an integral or real number becomes a decimal, other types usually return their data in a human-readable string. String.format() method. It replaces all occurrences of a key in the string with the corresponding value. The method can handle arrays or dictionaries for the key/value pairs. Arrays can be used as key, index, or mixed style (see below examples). Order only matters when the index or mixed style of Array is used. A quick example in GDScript:

  1. # Define a format stringvar format_string = "We're waiting for {str}"# Using the 'format' method, replace the 'str' placeholdervar actual_string = format_string.format({"str": "Godot"})print(actual_string)# Output: "We're waiting for Godot"

format specifiers, but they are only applicable when using the % operator.

Multiple placeholders

*, see dynamic padding):

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

Note the values are inserted in order. Remember all placeholders must be replaced at once, so there must be an appropriate number of values.

Format specifiers

s that can be used in placeholders. They consist of one or more characters. Some of them work by themselves like s, some appear before other characters, some only work with certain values or characters.

Placeholder types

s, these require certain types of parameters.

Placeholder modifiers

These characters appear before the above. Some of them work only under certain conditions.

Padding

. (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. To pad a string to a minimum length, add an integer to the specifier:

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

0, integral values are padded with zeroes instead of white space:

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

. (dot) with an integer following it. With no integer after ., a precision of 0 is used, rounding to integral value. The integer to use for padding must appear before the dot.

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

- character will cause padding to the right rather than the left, useful for right text alignment:

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

Dynamic padding

* (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:

  1. 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 before *:

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

Escape sequence

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

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

Format method examples

String.format method. String.format, here’s some examples of that functionality. String.format method and the % operator could be useful, as String.format does not have a way to manipulate the representation of numbers.