195 lines
7.7 KiB
ReStructuredText
195 lines
7.7 KiB
ReStructuredText
.. _doc_gdscript_printf:
|
|
|
|
GDScript format strings
|
|
=======================
|
|
|
|
GDScript offers a feature called *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.
|
|
|
|
As an example, with ``%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::
|
|
|
|
# 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."
|
|
|
|
Placeholders always start with a ``%``, but the next character or characters,
|
|
the *format specifier*, determines how the given value is converted to a
|
|
string.
|
|
|
|
The ``%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.
|
|
|
|
There are other `format specifiers`_.
|
|
|
|
|
|
Multiple placeholders
|
|
---------------------
|
|
|
|
Format strings may contain multiple placeholders. In such a case, the values
|
|
are handed in the form of an array, one value per placeholder (unless using a
|
|
format specifier with ``*``, see `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."
|
|
|
|
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
|
|
-----------------
|
|
|
|
There are format specifiers other than ``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
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
One and only one of these must always appear as the last character in a format
|
|
specifier. Apart from ``s``, these require certain types of parameters.
|
|
|
|
+-------+---------------------------------------------------------------------+
|
|
| ``s`` | **Simple** conversion to String by the same method as implicit |
|
|
| | String conversion. |
|
|
+-------+---------------------------------------------------------------------+
|
|
| ``c`` | A single **Unicode character**. Expects an unsigned 8-bit integer |
|
|
| | (0-255) for a code point or a single-character string. |
|
|
+-------+---------------------------------------------------------------------+
|
|
| ``d`` | A **decimal integral** number. Expects an integral or real number |
|
|
| | (will be floored). |
|
|
+-------+---------------------------------------------------------------------+
|
|
| ``o`` | An **octal integral** number. Expects an integral or real number |
|
|
| | (will be floored). |
|
|
+-------+---------------------------------------------------------------------+
|
|
| ``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`` | A **decimal real** number. Expects an integral or real number. |
|
|
+-------+---------------------------------------------------------------------+
|
|
|
|
|
|
Placeholder modifiers
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
These characters appear before the above. Some of them work only under certain
|
|
conditions.
|
|
|
|
+---------+-------------------------------------------------------------------+
|
|
| ``+`` | In number specifiers, **show + sign** if positive. |
|
|
+---------+-------------------------------------------------------------------+
|
|
| Integer | Set **padding**. Padded with spaces or with zeroes if integer |
|
|
| | starts with ``0`` in an integer placeholder. When used after |
|
|
| | ``.``, see ``.``. |
|
|
+---------+-------------------------------------------------------------------+
|
|
| ``.`` | Before ``f``, set **precision** to 0 decimal places. Can be |
|
|
| | followed up with numbers to change. Padded with zeroes. |
|
|
+---------+-------------------------------------------------------------------+
|
|
| ``-`` | **Pad to the right** rather than the left. |
|
|
+---------+-------------------------------------------------------------------+
|
|
| ``*`` | **Dynamic padding**, expect additional integral parameter to set |
|
|
| | padding or precision after ``.``, see `dynamic padding`_. |
|
|
+---------+-------------------------------------------------------------------+
|
|
|
|
|
|
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.
|
|
|
|
To pad a string to a minimum length, add an integer to the specifier::
|
|
|
|
print("%10d" % 12345)
|
|
# output: " 12345"
|
|
# 5 leading spaces for a total length of 10
|
|
|
|
If the integer starts with ``0``, integral values are padded with zeroes
|
|
instead of white space::
|
|
|
|
print("%010d" % 12345)
|
|
# output: "0000012345"
|
|
|
|
Precision can be specified for real numbers by adding a ``.`` (*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.
|
|
|
|
::
|
|
|
|
# pad to minimum length of 10, round to 3 decimal places
|
|
print("%10.3f" % 10000.5555)
|
|
# output: " 10000.556"
|
|
# 1 leading space
|
|
|
|
The ``-`` character will cause padding to the right rather than the left,
|
|
useful for right text alignment::
|
|
|
|
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%"
|