Merge pull request #62439 from timothyqiu/str-format

1 files changed, 16 insertions, 1 deletions

diff --git a/doc/classes/String.xml b/doc/classes/String.xml
index f4d453700c..9f197dae02 100644
--- a/doc/classes/String.xml
+++ b/doc/classes/String.xml
@@ -180,7 +180,22 @@
 			<argument index="0" name="values" type="Variant" />
 			<argument index="1" name="placeholder" type="String" default="&quot;{_}&quot;" />
 			<description>
-				Formats the string by replacing all occurrences of [code]placeholder[/code] with [code]values[/code].
+				Formats the string by replacing all occurrences of [code]placeholder[/code] with the elements of [code]values[/code].
+				[code]values[/code] can be a [Dictionary] or an [Array]. Any underscores in [code]placeholder[/code] will be replaced with the corresponding keys in advance. Array elements use their index as keys.
+				[codeblock]
+				# Prints: Waiting for Godot is a play by Samuel Beckett, and Godot Engine is named after it.
+				var use_array_values = "Waiting for {0} is a play by {1}, and {0} Engine is named after it."
+				print(use_array_values.format(["Godot", "Samuel Beckett"]))
+
+				# Prints: User 42 is Godot.
+				print("User {id} is {name}.".format({"id": 42, "name": "Godot"}))
+				[/codeblock]
+				Some additional handling is performed when [code]values[/code] is an array. If [code]placeholder[/code] does not contain an underscore, the elements of the array will be used to replace one occurrence of the placeholder in turn; If an array element is another 2-element array, it'll be interpreted as a key-value pair.
+				[codeblock]
+				# Prints: User 42 is Godot.
+				print("User {} is {}.".format([42, "Godot"], "{}"))
+				print("User {id} is {name}.".format([["id", 42], ["name", "Godot"]]))
+				[/codeblock]
 			</description>
 		</method>
 		<method name="get_base_dir" qualifiers="const">