Document GDScript format strings
This commit is contained in:
parent
586ed72951
commit
2f905849ce
|
@ -6,6 +6,7 @@ Languages
|
|||
:name: toc-languages
|
||||
|
||||
gdscript
|
||||
gdscript_printf
|
||||
gdscript_more_efficiently
|
||||
shading_language
|
||||
locales
|
||||
|
|
|
@ -308,6 +308,8 @@ Used to contain a floating point value (real numbers).
|
|||
|
||||
A sequence of characters in `Unicode format <https://en.wikipedia.org/wiki/Unicode>`_. Strings can contain the
|
||||
`standard C escape sequences <https://en.wikipedia.org/wiki/Escape_sequences_in_C>`_.
|
||||
GDScript supports :ref:`format strings aka printf functionality
|
||||
<doc_gdscript_printf>`.
|
||||
|
||||
Vector built-in types
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
@ -437,7 +439,7 @@ arrays. They are therefore only recommended to use for very large data sets:
|
|||
- :ref:`ByteArray <class_ByteArray>`: An array of bytes (integers from 0 to 255).
|
||||
- :ref:`IntArray <class_IntArray>`: An array of integers.
|
||||
- :ref:`FloatArray <class_FloatArray>`: An array of floats.
|
||||
- :ref:`StringArray <class_StringArray>`: An array strings.
|
||||
- :ref:`StringArray <class_StringArray>`: An array of strings.
|
||||
- :ref:`Vector2Array <class_Vector2Array>`: An array of :ref:`Vector2 <class_Vector2>` objects.
|
||||
- :ref:`Vector3Array <class_Vector3Array>`: An array of :ref:`Vector3 <class_Vector3>` objects.
|
||||
- :ref:`ColorArray <class_ColorArray>`: An array of :ref:`Color <class_Color>` objects.
|
||||
|
|
|
@ -0,0 +1,194 @@
|
|||
.. _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%"
|
Loading…
Reference in New Issue