From 30eb46b93845a40ea5e0c1f99e14fc652d2890a7 Mon Sep 17 00:00:00 2001 From: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com> Date: Sun, 17 Mar 2024 14:38:36 +0100 Subject: [PATCH] [Doc] Clarify behavior of `String.format` with keys in replacements (cherry picked from commit 8a78e7e174e4e1dc42fcefc6b01f9d9e3fbfb356) --- doc/classes/String.xml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/classes/String.xml b/doc/classes/String.xml index 2f3669513e4..63ea5ad3840 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -239,6 +239,13 @@ print("User {id} is {name}.".format([["id", 42], ["name", "Godot"]])) [/codeblock] See also the [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_format_string.html]GDScript format string[/url] tutorial. + [b]Note:[/b] The replacement of placeholders is not done all at once, instead each placeholder is replaced in the order they are passed, this means that if one of the replacement strings contains a key it will also be replaced. This can be very powerful, but can also cause unexpected results if you are not careful. If you do not need to perform replacement in the replacement strings, make sure your replacements do not contain placeholders to ensure reliable results. + [codeblock] + print("{0} {1}".format(["{1}", "x"])) # Prints "x x". + print("{0} {1}".format(["x", "{0}"])) # Prints "x {0}". + print("{foo} {bar}".format({"foo": "{bar}", "bar": "baz"})) # Prints "baz baz". + print("{foo} {bar}".format({"bar": "baz", "foo": "{bar}"})) # Prints "{bar} baz". + [/codeblock] [b]Note:[/b] In C#, it's recommended to [url=https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/interpolated]interpolate strings with "$"[/url], instead.