Skip to content

Commit

Permalink
Fix differences between String and StringName's documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@Mickeon
Mickeon committed Aug 18, 2024
1 parent 1bd740d commit d55372b
Show file tree
Hide file tree
Showing 2 changed files with 27 additions and 21 deletions.
12 changes: 6 additions & 6 deletions doc/classes/String.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -263,12 +263,12 @@
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.
[b]Note:[/b] Each replacement is done sequentially for each element of [param values], [b]not[/b] all at once. This means that if any element is inserted and it contains another placeholder, it may be changed by the next replacement. While this can be very useful, it often causes unexpected results. If not necessary, make sure [param values]'s elements do not contain placeholders.
[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".
print("{0} {1}".format(["{1}", "x"])) # Prints "x x".
print("{0} {1}".format(["x", "{0}"])) # Prints "x {0}".
print("{a} {b}".format({"a": "{b}", "b": "c"})) # Prints "c c".
print("{a} {b}".format({"b": "c", "a": "{b}"})) # Prints "{b} c".
[/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.
</description>
Expand Down Expand Up @@ -854,7 +854,7 @@
<return type="float" />
<param index="0" name="text" type="String" />
<description>
Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sorensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar.
Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sørensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar.
[codeblock]
print("ABC123".similarity("ABC123")) # Prints 1.0
print("ABC123".similarity("XYZ456")) # Prints 0.0
Expand Down
36 changes: 21 additions & 15 deletions doc/classes/StringName.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,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] Each replacement is done sequentially for each element of [param values], [b]not[/b] all at once. This means that if any element is inserted and it contains another placeholder, it may be changed by the next replacement. While this can be very useful, it often causes unexpected results. If not necessary, make sure [param values]'s elements do not contain placeholders.
[codeblock]
print("{0} {1}".format(["{1}", "x"])) # Prints "x x".
print("{0} {1}".format(["x", "{0}"])) # Prints "x {0}".
print("{a} {b}".format({"a": "{b}", "b": "c"})) # Prints "c c".
print("{a} {b}".format({"b": "c", "a": "{b}"})) # Prints "{b} c".
[/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.
</description>
</method>
Expand Down Expand Up @@ -299,7 +306,7 @@
<param index="0" name="delimiter" type="String" />
<param index="1" name="slice" type="int" />
<description>
Splits the string using a [param delimiter] and returns the substring at index [param slice]. Returns an empty string if the [param slice] does not exist.
Splits the string using a [param delimiter] and returns the substring at index [param slice]. Returns the original string if [param delimiter] does not occur in the string. Returns an empty string if the [param slice] does not exist.
This is faster than [method split], if you only need one substring.
[b]Example:[/b]
[codeblock]
Expand Down Expand Up @@ -755,7 +762,7 @@
<return type="float" />
<param index="0" name="text" type="String" />
<description>
Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sorensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar.
Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sørensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar.
[codeblock]
print("ABC123".similarity("ABC123")) # Prints 1.0
print("ABC123".similarity("XYZ456")) # Prints 0.0
Expand Down Expand Up @@ -845,7 +852,7 @@
<method name="to_ascii_buffer" qualifiers="const">
<return type="PackedByteArray" />
<description>
Converts the string to an [url=https://en.wikipedia.org/wiki/ASCII]ASCII[/url]/Latin-1 encoded [PackedByteArray]. This method is slightly faster than [method to_utf8_buffer], but replaces all unsupported characters with spaces.
Converts the string to an [url=https://en.wikipedia.org/wiki/ASCII]ASCII[/url]/Latin-1 encoded [PackedByteArray]. This method is slightly faster than [method to_utf8_buffer], but replaces all unsupported characters with spaces. This is the inverse of [method PackedByteArray.get_string_from_ascii].
</description>
</method>
<method name="to_camel_case" qualifiers="const">
Expand All @@ -859,12 +866,11 @@
<description>
Converts the string representing a decimal number into a [float]. This method stops on the first non-number character, except the first decimal point ([code].[/code]) and the exponent letter ([code]e[/code]). See also [method is_valid_float].
[codeblock]
var a = "12.35".to_float() # a is 12.35
var b = "1.2.3".to_float() # b is 1.2
var c = "12xy3".to_float() # c is 12.0
var d = "1e3".to_float() # d is 1000.0
var e = "Hello!".to_int() # e is 0.0
[/codeblock]
var a = "12.35".to_float() # a is 12.35
var b = "1.2.3".to_float() # b is 1.2
var c = "12xy3".to_float() # c is 12.0
var d = "1e3".to_float() # d is 1000.0
var e = "Hello!".to_float() # e is 0.0
</description>
</method>
<method name="to_int" qualifiers="const">
Expand Down Expand Up @@ -919,25 +925,25 @@
<method name="to_utf8_buffer" qualifiers="const">
<return type="PackedByteArray" />
<description>
Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-8]UTF-8[/url] encoded [PackedByteArray]. This method is slightly slower than [method to_ascii_buffer], but supports all UTF-8 characters. For most cases, prefer using this method.
Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-8]UTF-8[/url] encoded [PackedByteArray]. This method is slightly slower than [method to_ascii_buffer], but supports all UTF-8 characters. For most cases, prefer using this method. This is the inverse of [method PackedByteArray.get_string_from_utf8].
</description>
</method>
<method name="to_utf16_buffer" qualifiers="const">
<return type="PackedByteArray" />
<description>
Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-16]UTF-16[/url] encoded [PackedByteArray].
Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-16]UTF-16[/url] encoded [PackedByteArray]. This is the inverse of [method PackedByteArray.get_string_from_utf16].
</description>
</method>
<method name="to_utf32_buffer" qualifiers="const">
<return type="PackedByteArray" />
<description>
Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-32]UTF-32[/url] encoded [PackedByteArray].
Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-32]UTF-32[/url] encoded [PackedByteArray]. This is the inverse of [method PackedByteArray.get_string_from_utf32].
</description>
</method>
<method name="to_wchar_buffer" qualifiers="const">
<return type="PackedByteArray" />
<description>
Converts the string to a [url=https://en.wikipedia.org/wiki/Wide_character]wide character[/url] ([code]wchar_t[/code], UTF-16 on Windows, UTF-32 on other platforms) encoded [PackedByteArray].
Converts the string to a [url=https://en.wikipedia.org/wiki/Wide_character]wide character[/url] ([code]wchar_t[/code], UTF-16 on Windows, UTF-32 on other platforms) encoded [PackedByteArray]. This is the inverse of [method PackedByteArray.get_string_from_wchar].
</description>
</method>
<method name="trim_prefix" qualifiers="const">
Expand All @@ -964,7 +970,7 @@
<method name="uri_decode" qualifiers="const">
<return type="String" />
<description>
Decodes the string from its URL-encoded format. This method is meant to properly decode the parameters in a URL when receiving an HTTP request.
Decodes the string from its URL-encoded format. This method is meant to properly decode the parameters in a URL when receiving an HTTP request. See also [method uri_encode].
[codeblocks]
[gdscript]
var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs"
Expand All @@ -980,7 +986,7 @@
<method name="uri_encode" qualifiers="const">
<return type="String" />
<description>
Encodes the string to URL-friendly format. This method is meant to properly encode the parameters in a URL when sending an HTTP request.
Encodes the string to URL-friendly format. This method is meant to properly encode the parameters in a URL when sending an HTTP request. See also [method uri_decode].
[codeblocks]
[gdscript]
var prefix = "$DOCS_URL/?highlight="
Expand Down

0 comments on commit d55372b

Please sign in to comment.