godotengine
/
godot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #69821 from Mickeon/the-future-is-now-old-man 

Update StringName documentation to match String's
This commit is contained in:
Rémi Verschelde 2022-12-09 21:23:34 +01:00 committed by GitHub
parent 01b501fc2d 45e991fdc2
commit ae86d907e7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 270 additions and 184 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

438
doc/classes/StringName.xml
View File

@ -7,6 +7,8 @@
[StringName]s are immutable strings designed for general-purpose representation of unique names (also called "string interning"). [StringName] ensures that only one instance of a given name exists (so two [StringName]s with the same value are the same object). Comparing them is much faster than with regular [String]s, because only the pointers are compared, not the whole strings.
You will usually just pass a [String] to methods expecting a [StringName] and it will be automatically converted, but you may occasionally want to construct a [StringName] ahead of time with [StringName] or, in GDScript, the literal syntax [code]&"example"[/code].
See also [NodePath], which is a similar concept specifically designed to store pre-parsed node paths.
Some string methods have corresponding variations. Variations suffixed with [code]n[/code] ([method countn], [method findn], [method replacen], etc.) are [b]case-insensitive[/b] (they make no distinction between uppercase and lowercase letters). Method variations prefixed with [code]r[/code] ([method rfind], [method rsplit], etc.) are reversed, and start from the end of the string, instead of the beginning.
[b]Note:[/b] In a boolean context, a [StringName] will evaluate to [code]false[/code] if it is empty ([code]StringName("")[/code]). Otherwise, a [StringName] will always evaluate to [code]true[/code].
</description>
<tutorials>
</tutorials>
@ -37,30 +39,32 @@
<return type="bool" />
<param index="0" name="text" type="String" />
<description>
Returns [code]true[/code] if the string begins with the given string.
Returns [code]true[/code] if the string begins with the given [param text]. See also [method ends_with].
</description>
</method>
<method name="bigrams" qualifiers="const">
<return type="PackedStringArray" />
<description>
Returns an array containing the bigrams (pairs of consecutive letters) of this string.
Returns an array containing the bigrams (pairs of consecutive characters) of this string.
[codeblock]
print("Bigrams".bigrams()) # Prints "[Bi, ig, gr, ra, am, ms]"
print("Get up!".bigrams()) # Prints ["Ge", "et", "t ", " u", "up", "p!"]
[/codeblock]
</description>
</method>
<method name="bin_to_int" qualifiers="const">
<return type="int" />
<description>
Converts a string containing a binary number into an integer. Binary strings can either be prefixed with [code]0b[/code] or not, and they can also start with a [code]-[/code] before the optional prefix.
Converts the string representing a binary number into an [int]. The string may optionally be prefixed with [code]"0b"[/code], and an additional [code]-[/code] prefix for negative numbers.
[codeblocks]
[gdscript]
print("0b101".bin_to_int()) # Prints "5".
print("101".bin_to_int()) # Prints "5".
print("101".bin_to_int()) # Prints 5
print("0b101".bin_to_int()) # Prints 5
print("-0b10".bin_to_int()) # Prints -2
[/gdscript]
[csharp]
GD.Print("0b101".BinToInt()); // Prints "5".
GD.Print("101".BinToInt()); // Prints "5".
GD.Print("101".BinToInt()); // Prints 5
GD.Print("0b101".BinToInt()); // Prints 5
GD.Print("-0b10".BinToInt()); // Prints -2
[/csharp]
[/codeblocks]
</description>
@ -81,24 +85,46 @@
<method name="capitalize" qualifiers="const">
<return type="String" />
<description>
Changes the case of some letters. Replaces underscores with spaces, adds spaces before in-word uppercase characters, converts all letters to lowercase, then capitalizes the first letter and every letter following a space character. For [code]capitalize camelCase mixed_with_underscores[/code], it will return [code]Capitalize Camel Case Mixed With Underscores[/code].
Changes the appearance of the string: replaces underscores ([code]_[/code]) with spaces, adds spaces before uppercase letters in the middle of a word, converts all letters to lowercase, then converts the first one and each one following a space to uppercase.
[codeblocks]
[gdscript]
"move_local_x".capitalize() # Returns "Move Local X"
"sceneFile_path".capitalize() # Returns "Scene File Path"
[/gdscript]
[csharp]
"move_local_x".Capitalize(); // Returns "Move Local X"
"sceneFile_path".Capitalize(); // Returns "Scene File Path"
[/csharp]
[/codeblocks]
[b]Note:[/b] This method not the same as the default appearance of properties in the Inspector dock, as it does not capitalize acronyms ([code]"2D"[/code], [code]"FPS"[/code], [code]"PNG"[/code], etc.) as you may expect.
</description>
</method>
<method name="casecmp_to" qualifiers="const">
<return type="int" />
<param index="0" name="to" type="String" />
<description>
Performs a case-sensitive comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order.
[b]Behavior with different string lengths:[/b] Returns [code]1[/code] if the "base" string is longer than the [param to] string or [code]-1[/code] if the "base" string is shorter than the [param to] string. Keep in mind this length is determined by the number of Unicode codepoints, [i]not[/i] the actual visible characters.
[b]Behavior with empty strings:[/b] Returns [code]-1[/code] if the "base" string is empty, [code]1[/code] if the [param to] string is empty or [code]0[/code] if both strings are empty.
To get a boolean result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to] and [method naturalnocasecmp_to].
Performs a case-sensitive comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" and "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order.
With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code].
To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to] and [method naturalnocasecmp_to].
</description>
</method>
<method name="contains" qualifiers="const">
<return type="bool" />
<param index="0" name="what" type="String" />
<description>
Returns [code]true[/code] if the string contains the given string.
Returns [code]true[/code] if the string contains [param what]. In GDScript, this corresponds to the [code]in[/code] operator.
[codeblocks]
[gdscript]
print("Node".contains("de")) # Prints true
print("team".contains("I")) # Prints false
print("I" in "team") # Prints false
[/gdscript]
[csharp]
GD.Print("Node".Contains("de")); // Prints true
GD.Print("team".Contains("I")); // Prints false
[/csharp]
[/codeblocks]
If you need to know where [param what] is within the string, use [method find].
</description>
</method>
<method name="count" qualifiers="const">
@ -107,7 +133,7 @@
<param index="1" name="from" type="int" default="0" />
<param index="2" name="to" type="int" default="0" />
<description>
Returns the number of occurrences of substring [param what] between [param from] and [param to] positions. If [param from] and [param to] equals 0 the whole string will be used. If only [param to] equals 0 the remained substring will be used.
Returns the number of occurrences of the substring [param what] between [param from] and [param to] positions. If [param to] is 0, the search continues until the end of the string.
</description>
</method>
<method name="countn" qualifiers="const">
@ -116,7 +142,7 @@
<param index="1" name="from" type="int" default="0" />
<param index="2" name="to" type="int" default="0" />
<description>
Returns the number of occurrences of substring [param what] (ignoring case) between [param from] and [param to] positions. If [param from] and [param to] equals 0 the whole string will be used. If only [param to] equals 0 the remained substring will be used.
Returns the number of occurrences of the substring [param what] between [param from] and [param to] positions, [b]ignoring case[/b]. If [param to] is 0, the search continues until the end of the string.
</description>
</method>
<method name="dedent" qualifiers="const">
@ -129,7 +155,7 @@
<return type="bool" />
<param index="0" name="text" type="String" />
<description>
Returns [code]true[/code] if the string ends with the given string.
Returns [code]true[/code] if the string ends with the given [param text]. See also [method begins_with].
</description>
</method>
<method name="find" qualifiers="const">
@ -137,17 +163,24 @@
<param index="0" name="what" type="String" />
<param index="1" name="from" type="int" default="0" />
<description>
Returns the index of the [b]first[/b] case-sensitive occurrence of the specified string in this instance, or [code]-1[/code]. Optionally, the starting search index can be specified, continuing to the end of the string.
[b]Note:[/b] If you just want to know whether a string contains a substring, use the [code]in[/code] operator as follows:
Returns the index of the [b]first[/b] occurrence of [param what] in this string, or [code]-1[/code] if there are none. The search's start can be specified with [param from], continuing to the end of the string.
[codeblocks]
[gdscript]
print("i" in "team") # Will print `false`.
print("Team".find("I")) # Prints -1
print("Potato".find("t")) # Prints 2
print("Potato".find("t", 3)) # Prints 4
print("Potato".find("t", 5)) # Prints -1
[/gdscript]
[csharp]
// C# has no in operator, but we can use `Contains()`.
GD.Print("team".Contains("i")); // Will print `false`.
GD.Print("Team".Find("I")); // Prints -1
GD.Print("Potato".Find("t")); // Prints 2
GD.print("Potato".Find("t", 3)); // Prints 4
GD.print("Potato".Find("t", 5)); // Prints -1
[/csharp]
[/codeblocks]
[b]Note:[/b] If you just want to know whether the string contains [param what], use [method contains]. In GDScript, you may also use the [code]in[/code] operator.
</description>
</method>
<method name="findn" qualifiers="const">
@ -155,7 +188,7 @@
<param index="0" name="what" type="String" />
<param index="1" name="from" type="int" default="0" />
<description>
Returns the index of the [b]first[/b] case-insensitive occurrence of the specified string in this instance, or [code]-1[/code]. Optionally, the starting search index can be specified, continuing to the end of the string.
Returns the index of the [b]first[/b] [b]case-insensitive[/b] occurrence of [param what] in this string, or [code]-1[/code] if there are none. The starting search index can be specified with [param from], continuing to the end of the string.
</description>
</method>
<method name="format" qualifiers="const">
@ -166,53 +199,64 @@
Formats the string by replacing all occurrences of [param placeholder] with the elements of [param values].
[param values] can be a [Dictionary] or an [Array]. Any underscores in [param placeholder] 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.
# 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.
# Prints "User 42 is Godot."
print("User {id} is {name}.".format({"id": 42, "name": "Godot"}))
[/codeblock]
Some additional handling is performed when [param values] is an array. If [param placeholder] 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.
Some additional handling is performed when [param values] is an [Array]. If [param placeholder] does not contain an underscore, the elements of the [param values] array will be used to replace one occurrence of the placeholder in order; If an element of [param values] is another 2-element array, it'll be interpreted as a key-value pair.
[codeblock]
# Prints: User 42 is Godot.
# Prints "User 42 is Godot."
print("User {} is {}.".format([42, "Godot"], "{}"))
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.
</description>
</method>
<method name="get_base_dir" qualifiers="const">
<return type="String" />
<description>
If the string is a valid file path, returns the base directory name.
[codeblock]
var dir_path = "/path/to/file.txt".get_basename() # dir_path is "/path/to"
[/codeblock]
</description>
</method>
<method name="get_basename" qualifiers="const">
<return type="String" />
<description>
If the string is a valid file path, returns the full file path without the extension.
If the string is a valid file path, returns the full file path, without the extension.
[codeblock]
var base = "/path/to/file.txt".get_basename() # base is "/path/to/file"
[/codeblock]
</description>
</method>
<method name="get_extension" qualifiers="const">
<return type="String" />
<description>
Returns the extension without the leading period character ([code].[/code]) if the string is a valid file name or path. If the string does not contain an extension, returns an empty string instead.
If the string is a valid file name or path, returns the file extension without the leading period ([code].[/code]). Otherwise, returns an empty string.
[codeblock]
print("/path/to/file.txt".get_extension()) # "txt"
print("file.txt".get_extension()) # "txt"
print("file.sample.txt".get_extension()) # "txt"
print(".txt".get_extension()) # "txt"
print("file.txt.".get_extension()) # "" (empty string)
print("file.txt..".get_extension()) # "" (empty string)
print("txt".get_extension()) # "" (empty string)
print("".get_extension()) # "" (empty string)
var a = "/path/to/file.txt".get_extension() # a is "txt"
var b = "cool.txt".get_extension() # b is "txt"
var c = "cool.font.tres".get_extension() # c is "tres"
var d = ".pack1".get_extension() # d is "pack1"
var e = "file.txt.".get_extension() # e is ""
var f = "file.txt..".get_extension() # f is ""
var g = "txt".get_extension() # g is ""
var h = "".get_extension() # h is ""
[/codeblock]
</description>
</method>
<method name="get_file" qualifiers="const">
<return type="String" />
<description>
If the string is a valid file path, returns the filename.
If the string is a valid file path, returns the file name, including the extension.
[codeblock]
var file = "/path/to/icon.png".get_file() # file is "icon.png"
[/codeblock]
</description>
</method>
<method name="get_slice" qualifiers="const">
@ -220,11 +264,11 @@
<param index="0" name="delimiter" type="String" />
<param index="1" name="slice" type="int" />
<description>
Splits a string using a [param delimiter] and returns a substring at index [param slice]. Returns an empty string if the index doesn't exist.
This is a more performant alternative to [method split] for cases when you need only one element from the array at a fixed index.
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.
This is faster than [method split], if you only need one substring.
[b]Example:[/b]
[codeblock]
print("i/am/example/string".get_slice("/", 2)) # Prints 'example'.
print("i/am/example/hi".get_slice("/", 2)) # Prints "example"
[/codeblock]
</description>
</method>
@ -232,7 +276,7 @@
<return type="int" />
<param index="0" name="delimiter" type="String" />
<description>
Splits a string using a [param delimiter] and returns a number of slices.
Returns the total number of slices when the string is split with the given [param delimiter] (see [method split]).
</description>
</method>
<method name="get_slicec" qualifiers="const">
@ -240,28 +284,29 @@
<param index="0" name="delimiter" type="int" />
<param index="1" name="slice" type="int" />
<description>
Splits a string using a Unicode character with code [param delimiter] and returns a substring at index [param slice]. Returns an empty string if the index doesn't exist.
This is a more performant alternative to [method split] for cases when you need only one element from the array at a fixed index.
Splits the string using a Unicode character with code [param delimiter] and returns the substring at index [param slice]. Returns an empty string if the [param slice] does not exist.
This is faster than [method split], if you only need one substring.
</description>
</method>
<method name="hash" qualifiers="const">
<return type="int" />
<description>
Returns the 32-bit hash value representing the [StringName]'s contents.
Returns the 32-bit hash value representing the string's contents.
[b]Note:[/b] Strings with equal hash values are [i]not[/i] guaranteed to be the same, as a result of hash collisions. On the countrary, strings with different hash values are guaranteed to be different.
</description>
</method>
<method name="hex_to_int" qualifiers="const">
<return type="int" />
<description>
Converts a string containing a hexadecimal number into an integer. Hexadecimal strings can either be prefixed with [code]0x[/code] or not, and they can also start with a [code]-[/code] before the optional prefix.
Converts the string representing a hexadecimal number into an [int]. The string may be optionally prefixed with [code]"0x"[/code], and an additional [code]-[/code] prefix for negative numbers.
[codeblocks]
[gdscript]
print("0xff".hex_to_int()) # Prints "255".
print("ab".hex_to_int()) # Prints "171".
print("0xff".hex_to_int()) # Prints 255
print("ab".hex_to_int()) # Prints 171
[/gdscript]
[csharp]
GD.Print("0xff".HexToInt()); // Prints "255".
GD.Print("ab".HexToInt()); // Prints "171".
GD.Print("0xff".HexToInt()); // Prints 255
GD.Print("ab".HexToInt()); // Prints 171
[/csharp]
[/codeblocks]
</description>
@ -270,9 +315,8 @@
<return type="String" />
<param index="0" name="prefix" type="String" />
<description>
Returns a copy of the string with lines indented with [param prefix].
For example, the string can be indented with two tabs using [code]"\t\t"[/code], or four spaces using [code]" "[/code]. The prefix can be any string so it can also be used to comment out strings with e.g. [code]"# "[/code]. See also [method dedent] to remove indentation.
[b]Note:[/b] Empty lines are kept empty.
Indents every line of the string with the given [param prefix]. Empty lines are not indented. See also [method dedent] to remove indentation.
For example, the string can be indented with two tabulations using [code]"\t\t"[/code], or four spaces using [code]" "[/code].
</description>
</method>
<method name="insert" qualifiers="const">
@ -280,57 +324,65 @@
<param index="0" name="position" type="int" />
<param index="1" name="what" type="String" />
<description>
Returns a copy of the string with the substring [param what] inserted at the given [param position].
Inserts [param what] at the given [param position] in the string.
</description>
</method>
<method name="is_absolute_path" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the string is a path to a file or directory and its starting point is explicitly defined. This includes [code]res://[/code], [code]user://[/code], [code]C:\[/code], [code]/[/code], etc.
Returns [code]true[/code] if the string is a path to a file or directory, and its starting point is explicitly defined. This method is the opposite of [method is_relative_path].
This includes all paths starting with [code]"res://"[/code], [code]"user://"[/code], [code]"C:\"[/code], [code]"/"[/code], etc.
</description>
</method>
<method name="is_empty" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the length of the string equals [code]0[/code].
Returns [code]true[/code] if the string's length is [code]0[/code] ([code]""[/code]). See also [method length].
</description>
</method>
<method name="is_relative_path" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the string is a path to a file or directory and its starting point is implicitly defined within the context it is being used. The starting point may refer to the current directory ([code]./[/code]), or the current [Node].
Returns [code]true[/code] if the string is a path, and its starting point is dependent on context. The path could begin from the current directory, or the current [Node] (if the string is derived from a [NodePath]), and may sometimes be prefixed with [code]"./"[/code]. This method is the opposite of [method is_absolute_path].
</description>
</method>
<method name="is_subsequence_of" qualifiers="const">
<return type="bool" />
<param index="0" name="text" type="String" />
<description>
Returns [code]true[/code] if this string is a subsequence of the given string.
Returns [code]true[/code] if all characters of this string can be found in [param text] in their original order.
[codeblock]
var text = "Wow, incredible!"
print("inedible".is_subsequence_of(text)) # Prints true
print("Word!".is_subsequence_of(text)) # Prints true
print("Window".is_subsequence_of(text)) # Prints false
print("".is_subsequence_of(text)) # Prints true
[/codeblock]
</description>
</method>
<method name="is_subsequence_ofn" qualifiers="const">
<return type="bool" />
<param index="0" name="text" type="String" />
<description>
Returns [code]true[/code] if this string is a subsequence of the given string, without considering case.
Returns [code]true[/code] if all characters of this string can be found in [param text] in their original order, [b]ignoring case[/b].
</description>
</method>
<method name="is_valid_filename" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this string is free from characters that aren't allowed in file names, those being:
[code]: / \ ? * " | % &lt; &gt;[/code]
Returns [code]true[/code] if this string does not contain characters that are not allowed in file names ([code]:[/code] [code]/[/code] [code]\[/code] [code]?[/code] [code]*[/code] [code]"[/code] [code]|[/code] [code]%[/code] [code]&lt;[/code] [code]&gt;[/code]).
</description>
</method>
<method name="is_valid_float" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this string contains a valid float. This is inclusive of integers, and also supports exponents:
Returns [code]true[/code] if this string represents a valid floating-point number. A valid float may contain only digits, one decimal point ([code].[/code]), and the exponent letter ([code]e[/code]). It may also be prefixed with a positive ([code]+[/code]) or negative ([code]-[/code]) sign. Any valid integer is also a valid float (see [method is_valid_int]). See also [method to_float].
[codeblock]
print("1.7".is_valid_float()) # Prints "true"
print("24".is_valid_float()) # Prints "true"
print("7e3".is_valid_float()) # Prints "true"
print("Hello".is_valid_float()) # Prints "false"
print("1.7".is_valid_float()) # Prints true
print("24".is_valid_float()) # Prints true
print("7e3".is_valid_float()) # Prints true
print("Hello".is_valid_float()) # Prints false
[/codeblock]
</description>
</method>
@ -338,57 +390,73 @@
<return type="bool" />
<param index="0" name="with_prefix" type="bool" default="false" />
<description>
Returns [code]true[/code] if this string contains a valid hexadecimal number. If [param with_prefix] is [code]true[/code], then a validity of the hexadecimal number is determined by the [code]0x[/code] prefix, for example: [code]0xDEADC0DE[/code].
Returns [code]true[/code] if this string is a valid hexadecimal number. A valid hexadecimal number only contains digits or letters [code]A[/code] to [code]F[/code] (either uppercase or lowercase), and may be prefixed with a positive ([code]+[/code]) or negative ([code]-[/code]) sign.
If [param with_prefix] is [code]true[/code], the hexadecimal number needs to prefixed by [code]"0x"[/code] to be considered valid.
[codeblock]
print("A08E".is_valid_hex_number()) # Prints true
print("-AbCdEf".is_valid_hex_number()) # Prints true
print("2.5".is_valid_hex_number()) # Prints false
print("0xDEADC0DE".is_valid_hex_number(true)) # Prints true
[/codeblock]
</description>
</method>
<method name="is_valid_html_color" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this string contains a valid color in hexadecimal HTML notation. Other HTML notations such as named colors or [code]hsl()[/code] colors aren't considered valid by this method and will return [code]false[/code].
Returns [code]true[/code] if this string is a valid color in hexadecimal HTML notation. The string must be a hexadecimal value (see [method is_valid_hex_number]) of either 3, 4, 6 or 8 digits, and may be prefixed by a hash sign ([code]#[/code]). Other HTML notations for colors, such as names or [code]hsl()[/code], are not considered valid. See also [method Color.html].
</description>
</method>
<method name="is_valid_identifier" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this string is a valid identifier. A valid identifier may contain only letters, digits and underscores ([code]_[/code]) and the first character may not be a digit.
Returns [code]true[/code] if this string is a valid identifier. A valid identifier may contain only letters, digits and underscores ([code]_[/code]), and the first character may not be a digit.
[codeblock]
print("good_ident_1".is_valid_identifier()) # Prints "true"
print("1st_bad_ident".is_valid_identifier()) # Prints "false"
print("bad_ident_#2".is_valid_identifier()) # Prints "false"
print("node_2d".is_valid_identifier()) # Prints true
print("TYPE_FLOAT".is_valid_identifier()) # Prints true
print("1st_method".is_valid_identifier()) # Prints false
print("MyMethod#2".is_valid_identifier()) # Prints false
[/codeblock]
</description>
</method>
<method name="is_valid_int" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this string contains a valid integer.
Returns [code]true[/code] if this string represents a valid integer. A valid integer only contains digits, and may be prefixed with a positive ([code]+[/code]) or negative ([code]-[/code]) sign. See also [method to_int].
[codeblock]
print("7".is_valid_int()) # Prints "true"
print("14.6".is_valid_int()) # Prints "false"
print("L".is_valid_int()) # Prints "false"
print("+3".is_valid_int()) # Prints "true"
print("-12".is_valid_int()) # Prints "true"
print("7".is_valid_int()) # Prints true
print("1.65".is_valid_int()) # Prints false
print("Hi".is_valid_int()) # Prints false
print("+3".is_valid_int()) # Prints true
print("-12".is_valid_int()) # Prints true
[/codeblock]
</description>
</method>
<method name="is_valid_ip_address" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this string contains only a well-formatted IPv4 or IPv6 address. This method considers [url=https://en.wikipedia.org/wiki/Reserved_IP_addresses]reserved IP addresses[/url] such as [code]0.0.0.0[/code] as valid.
Returns [code]true[/code] if this string represents a well-formatted IPv4 or IPv6 address. This method considers [url=https://en.wikipedia.org/wiki/Reserved_IP_addresses]reserved IP addresses[/url] such as [code]"0.0.0.0"[/code] and [code]"ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"[/code] as valid.
</description>
</method>
<method name="join" qualifiers="const">
<return type="String" />
<param index="0" name="parts" type="PackedStringArray" />
<description>
Returns a [String] which is the concatenation of the [param parts]. The separator between elements is the string providing this method.
Returns the concatenation of [param parts]' elements, with each element separated by the string calling this method. This method is the opposite of [method split].
[b]Example:[/b]
[codeblocks]
[gdscript]
print(", ".join(["One", "Two", "Three", "Four"]))
var fruits = ["Apple", "Orange", "Pear", "Kiwi"]
print(", ".join(fruits)) # Prints "Apple, Orange, Pear, Kiwi"
print("---".join(fruits)) # Prints "Apple---Orange---Pear---Kiwi"
[/gdscript]
[csharp]
GD.Print(String.Join(",", new string[] {"One", "Two", "Three", "Four"}));
var fruits = new string[] {"Apple", "Orange", "Pear", "Kiwi"};
// In C#, this method is static.
GD.Print(string.Join(", ", fruits); // Prints "Apple, Orange, Pear, Kiwi"
GD.Print(string.Join("---", fruits)); // Prints "Apple---Orange---Pear---Kiwi"
[/csharp]
[/codeblocks]
</description>
@ -396,25 +464,24 @@
<method name="json_escape" qualifiers="const">
<return type="String" />
<description>
Returns a copy of the string with special characters escaped using the JSON standard.
Returns a copy of the string with special characters escaped using the JSON standard. Because it closely matches the C standard, it is possible to use [method c_unescape] to unescape the string, if necessary.
</description>
</method>
<method name="left" qualifiers="const">
<return type="String" />
<param index="0" name="length" type="int" />
<description>
Returns a number of characters from the left of the string. If negative [param length] is used, the characters are counted downwards from [String]'s length.
[b]Example:[/b]
Returns the first [param length] characters from the beginning of the string. If [param length] is negative, strips the last [param length] characters from the string's end.
[codeblock]
print("sample text".left(3)) #prints "sam"
print("sample text".left(-3)) #prints "sample t"
print("Hello World!".left(3)) # Prints "Hel"
print("Hello World!".left(-4)) # Prints "Hello Wo"
[/codeblock]
</description>
</method>
<method name="length" qualifiers="const">
<return type="int" />
<description>
Returns the number of characters in the string.
Returns the number of characters in the string. Empty strings ([code]""[/code]) always return [code]0[/code]. See also [method is_empty].
</description>
</method>
<method name="lpad" qualifiers="const">
@ -422,90 +489,89 @@
<param index="0" name="min_length" type="int" />
<param index="1" name="character" type="String" default="&quot; &quot;" />
<description>
Formats a string to be at least [param min_length] long by adding [param character]s to the left of the string.
Formats the string to be at least [param min_length] long by adding [param character]s to the left of the string, if necessary. See also [method rpad].
</description>
</method>
<method name="lstrip" qualifiers="const">
<return type="String" />
<param index="0" name="chars" type="String" />
<description>
Returns a copy of the string with characters removed from the left. The [param chars] argument is a string specifying the set of characters to be removed.
[b]Note:[/b] The [param chars] is not a prefix. See [method trim_prefix] method that will remove a single prefix string rather than a set of characters.
Removes a set of characters defined in [param chars] from the string's beginning. See also [method rstrip].
[b]Note:[/b] [param chars] is not a prefix. Use [method trim_prefix] to remove a single prefix, rather than a set of characters.
</description>
</method>
<method name="match" qualifiers="const">
<return type="bool" />
<param index="0" name="expr" type="String" />
<description>
Does a simple case-sensitive expression match, where [code]"*"[/code] matches zero or more arbitrary characters and [code]"?"[/code] matches any single character except a period ([code]"."[/code]). An empty string or empty expression always evaluates to [code]false[/code].
Does a simple expression match, where [code]*[/code] matches zero or more arbitrary characters and [code]?[/code] matches any single character except a period ([code].[/code]). An empty string or empty expression always evaluates to [code]false[/code].
</description>
</method>
<method name="matchn" qualifiers="const">
<return type="bool" />
<param index="0" name="expr" type="String" />
<description>
Does a simple case-insensitive expression match, where [code]"*"[/code] matches zero or more arbitrary characters and [code]"?"[/code] matches any single character except a period ([code]"."[/code]). An empty string or empty expression always evaluates to [code]false[/code].
Does a simple [b]case-insensitive[/b] expression match, where [code]*[/code] matches zero or more arbitrary characters and [code]?[/code] matches any single character except a period ([code].[/code]). An empty string or empty expression always evaluates to [code]false[/code].
</description>
</method>
<method name="md5_buffer" qualifiers="const">
<return type="PackedByteArray" />
<description>
Returns the MD5 hash of the string as an array of bytes.
Returns the [url=https://en.wikipedia.org/wiki/MD5]MD5 hash[/url] of the string as a [PackedByteArray].
</description>
</method>
<method name="md5_text" qualifiers="const">
<return type="String" />
<description>
Returns the MD5 hash of the string as a string.
Returns the [url=https://en.wikipedia.org/wiki/MD5]MD5 hash[/url] of the string as another [String].
</description>
</method>
<method name="naturalnocasecmp_to" qualifiers="const">
<return type="int" />
<param index="0" name="to" type="String" />
<description>
Performs a case-insensitive [i]natural order[/i] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters will be converted to uppercase during the comparison.
When used for sorting, natural order comparison will order suites of numbers as expected by most people. If you sort the numbers from 1 to 10 using natural order, you will get [code][1, 2, 3, ...][/code] instead of [code][1, 10, 2, 3, ...][/code].
[b]Behavior with different string lengths:[/b] Returns [code]1[/code] if the "base" string is longer than the [param to] string or [code]-1[/code] if the "base" string is shorter than the [param to] string. Keep in mind this length is determined by the number of Unicode codepoints, [i]not[/i] the actual visible characters.
[b]Behavior with empty strings:[/b] Returns [code]-1[/code] if the "base" string is empty, [code]1[/code] if the [param to] string is empty or [code]0[/code] if both strings are empty.
To get a boolean result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to] and [method casecmp_to].
Performs a [b]case-insensitive[/b], [i]natural order[/i] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters are converted to uppercase for the comparison.
When used for sorting, natural order comparison orders sequences of numbers by the combined value of each digit as is often expected, instead of the single digit's value. A sorted sequence of numbered strings will be [code]["1", "2", "3", ...][/code], not [code]["1", "10", "2", "3", ...][/code].
With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code].
To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method nocasecmp_to] and [method casecmp_to].
</description>
</method>
<method name="nocasecmp_to" qualifiers="const">
<return type="int" />
<param index="0" name="to" type="String" />
<description>
Performs a case-insensitive comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters will be converted to uppercase during the comparison.
[b]Behavior with different string lengths:[/b] Returns [code]1[/code] if the "base" string is longer than the [param to] string or [code]-1[/code] if the "base" string is shorter than the [param to] string. Keep in mind this length is determined by the number of Unicode codepoints, [i]not[/i] the actual visible characters.
[b]Behavior with empty strings:[/b] Returns [code]-1[/code] if the "base" string is empty, [code]1[/code] if the [param to] string is empty or [code]0[/code] if both strings are empty.
To get a boolean result from a string comparison, use the [code]==[/code] operator instead. See also [method casecmp_to] and [method naturalnocasecmp_to].
Performs a [b]case-insensitive[/b] comparison to another string. Returns [code]-1[/code] if less than, [code]1[/code] if greater than, or [code]0[/code] if equal. "Less than" or "greater than" are determined by the [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode code points[/url] of each string, which roughly matches the alphabetical order. Internally, lowercase characters are converted to uppercase for the comparison.
With different string lengths, returns [code]1[/code] if this string is longer than the [param to] string, or [code]-1[/code] if shorter. Note that the length of empty strings is [i]always[/i] [code]0[/code].
To get a [bool] result from a string comparison, use the [code]==[/code] operator instead. See also [method casecmp_to] and [method naturalnocasecmp_to].
</description>
</method>
<method name="pad_decimals" qualifiers="const">
<return type="String" />
<param index="0" name="digits" type="int" />
<description>
Formats a number to have an exact number of [param digits] after the decimal point.
Formats the string representing a number to have an exact number of [param digits] [i]after[/i] the decimal point.
</description>
</method>
<method name="pad_zeros" qualifiers="const">
<return type="String" />
<param index="0" name="digits" type="int" />
<description>
Formats a number to have an exact number of [param digits] before the decimal point.
Formats the string representing a number to have an exact number of [param digits] [i]before[/i] the decimal point.
</description>
</method>
<method name="path_join" qualifiers="const">
<return type="String" />
<param index="0" name="file" type="String" />
<description>
If the string is a path, this concatenates [param file] at the end of the string as a subpath. E.g. [code]"this/is".path_join("path") == "this/is/path"[/code].
Concatenates [param file] at the end of the string as a subpath, adding [code]/[/code] if necessary.
[b]Example:[/b] [code]"this/is".path_join("path") == "this/is/path"[/code].
</description>
</method>
<method name="repeat" qualifiers="const">
<return type="String" />
<param index="0" name="count" type="int" />
<description>
Returns original string repeated a number of times. The number of repetitions is given by the argument.
Repeats this string a number of times. [param count] needs to be greater than [code]0[/code]. Otherwise, returns an empty string.
</description>
</method>
<method name="replace" qualifiers="const">
@ -513,7 +579,7 @@
<param index="0" name="what" type="String" />
<param index="1" name="forwhat" type="String" />
<description>
Replaces occurrences of a case-sensitive substring with the given one inside the string.
Replaces all occurrences of [param what] inside the string with the given [param forwhat].
</description>
</method>
<method name="replacen" qualifiers="const">
@ -521,7 +587,7 @@
<param index="0" name="what" type="String" />
<param index="1" name="forwhat" type="String" />
<description>
Replaces occurrences of a case-insensitive substring with the given one inside the string.
Replaces all [b]case-insensitive[/b] occurrences of [param what] inside the string with the given [param forwhat].
</description>
</method>
<method name="rfind" qualifiers="const">
@ -529,7 +595,7 @@
<param index="0" name="what" type="String" />
<param index="1" name="from" type="int" default="-1" />
<description>
Returns the index of the [b]last[/b] case-sensitive occurrence of the specified string in this instance, or [code]-1[/code]. Optionally, the starting search index can be specified, continuing to the beginning of the string.
Returns the index of the [b]last[/b] occurrence of [param what] in this string, or [code]-1[/code] if there are none. The search's start can be specified with [param from], continuing to the beginning of the string. This method is the reverse of [method find].
</description>
</method>
<method name="rfindn" qualifiers="const">
@ -537,18 +603,17 @@
<param index="0" name="what" type="String" />
<param index="1" name="from" type="int" default="-1" />
<description>
Returns the index of the [b]last[/b] case-insensitive occurrence of the specified string in this instance, or [code]-1[/code]. Optionally, the starting search index can be specified, continuing to the beginning of the string.
Returns the index of the [b]last[/b] [b]case-insensitive[/b] occurrence of [param what] in this string, or [code]-1[/code] if there are none. The starting search index can be specified with [param from], continuing to the beginning of the string. This method is the reverse of [method findn].
</description>
</method>
<method name="right" qualifiers="const">
<return type="String" />
<param index="0" name="length" type="int" />
<description>
Returns a number of characters from the right of the string. If negative [param length] is used, the characters are counted downwards from [String]'s length.
[b]Example:[/b]
Returns the last [param length] characters from the end of the string. If [param length] is negative, strips the first [param length] characters from the string's beginning.
[codeblock]
print("sample text".right(3)) #prints "ext"
print("sample text".right(-3)) #prints "ple text"
print("Hello World!".right(3)) # Prints "ld!"
print("Hello World!".right(-4)) # Prints "o World!"
[/codeblock]
</description>
</method>
@ -557,7 +622,7 @@
<param index="0" name="min_length" type="int" />
<param index="1" name="character" type="String" default="&quot; &quot;" />
<description>
Formats a string to be at least [param min_length] long by adding [param character]s to the right of the string.
Formats the string to be at least [param min_length] long, by adding [param character]s to the right of the string, if necessary. See also [method lpad].
</description>
</method>
<method name="rsplit" qualifiers="const">
@ -566,21 +631,21 @@
<param index="1" name="allow_empty" type="bool" default="true" />
<param index="2" name="maxsplit" type="int" default="0" />
<description>
Splits the string by a [param delimiter] string and returns an array of the substrings, starting from right. If [param delimiter] is an empty string, each substring will be a single character.
The splits in the returned array are sorted in the same order as the original string, from left to right.
If [param allow_empty] is [code]true[/code], and there are two adjacent delimiters in the string, it will add an empty string to the array of substrings at this position.
If [param maxsplit] is specified, it defines the number of splits to do from the right up to [param maxsplit]. The default value of 0 means that all items are split, thus giving the same result as [method split].
Splits the string using a [param delimiter] and returns an array of the substrings, starting from the end of the string. The splits in the returned array appear in the same order as the original string. If [param delimiter] is an empty string, each substring will be a single character.
If [param allow_empty] is [code]false[/code], empty strings between adjacent delimiters are excluded from the array.
If [param maxsplit] is greater than [code]0[/code], the number of splits may not exceed [param maxsplit]. By default, the entire string is split, which is mostly identical to [method split].
[b]Example:[/b]
[codeblocks]
[gdscript]
var some_string = "One,Two,Three,Four"
var some_array = some_string.rsplit(",", true, 1)
print(some_array.size()) # Prints 2
print(some_array[0]) # Prints "One,Two,Three"
print(some_array[1]) # Prints "Four"
[/gdscript]
[csharp]
// There is no Rsplit.
// In C#, there is no String.RSplit() method.
[/csharp]
[/codeblocks]
</description>
@ -589,51 +654,55 @@
<return type="String" />
<param index="0" name="chars" type="String" />
<description>
Returns a copy of the string with characters removed from the right. The [param chars] argument is a string specifying the set of characters to be removed.
[b]Note:[/b] The [param chars] is not a suffix. See [method trim_suffix] method that will remove a single suffix string rather than a set of characters.
Removes a set of characters defined in [param chars] from the string's end. See also [method lstrip].
[b]Note:[/b] [param chars] is not a suffix. Use [method trim_suffix] to remove a single suffix, rather than a set of characters.
</description>
</method>
<method name="sha1_buffer" qualifiers="const">
<return type="PackedByteArray" />
<description>
Returns the SHA-1 hash of the string as an array of bytes.
Returns the [url=https://en.wikipedia.org/wiki/SHA-1]SHA-1[/url] hash of the string as a [PackedByteArray].
</description>
</method>
<method name="sha1_text" qualifiers="const">
<return type="String" />
<description>
Returns the SHA-1 hash of the string as a string.
Returns the [url=https://en.wikipedia.org/wiki/SHA-1]SHA-1[/url] hash of the string as another [String].
</description>
</method>
<method name="sha256_buffer" qualifiers="const">
<return type="PackedByteArray" />
<description>
Returns the SHA-256 hash of the string as an array of bytes.
Returns the [url=https://en.wikipedia.org/wiki/SHA-2]SHA-256[/url] hash of the string as a [PackedByteArray].
</description>
</method>
<method name="sha256_text" qualifiers="const">
<return type="String" />
<description>
Returns the SHA-256 hash of the string as a string.
Returns the [url=https://en.wikipedia.org/wiki/SHA-2]SHA-256[/url] hash of the string as another [String].
</description>
</method>
<method name="similarity" qualifiers="const">
<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 1.0 means totally similar, while 0.0 means totally dissimilar.
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.
[codeblock]
print("ABC123".similarity("ABC123")) # Prints "1"
print("ABC123".similarity("XYZ456")) # Prints "0"
print("ABC123".similarity("123ABC")) # Prints "0.8"
print("ABC123".similarity("abc123")) # Prints "0.4"
print("ABC123".similarity("ABC123")) # Prints 1.0
print("ABC123".similarity("XYZ456")) # Prints 0.0
print("ABC123".similarity("123ABC")) # Prints 0.8
print("ABC123".similarity("abc123")) # Prints 0.4
[/codeblock]
</description>
</method>
<method name="simplify_path" qualifiers="const">
<return type="String" />
<description>
Returns a simplified canonical path.
If the string is a valid file path, converts the string into a canonical path. This is the shortest possible path, without [code]"./"[/code], and all the unnecessary [code]".."[/code] and [code]"/"[/code].
[codeblock]
var simple_path = "./path/to///../file".simplify_path()
print(simple_path) # Prints "path/file"
[/codeblock]
</description>
</method>
<method name="split" qualifiers="const">
@ -642,27 +711,29 @@
<param index="1" name="allow_empty" type="bool" default="true" />
<param index="2" name="maxsplit" type="int" default="0" />
<description>
Splits the string by a [param delimiter] string and returns an array of the substrings. The [param delimiter] can be of any length. If [param delimiter] is an empty string, each substring will be a single character.
If [param allow_empty] is [code]true[/code], and there are two adjacent delimiters in the string, it will add an empty string to the array of substrings at this position.
If [param maxsplit] is specified, it defines the number of splits to do from the left up to [param maxsplit]. The default value of [code]0[/code] means that all items are split.
If you need only one element from the array at a specific index, [method get_slice] is a more performant option.
Splits the string using a [param delimiter] and returns an array of the substrings. If [param delimiter] is an empty string, each substring will be a single character. This method is the opposite of [method join].
If [param allow_empty] is [code]false[/code], empty strings between adjacent delimiters are excluded from the array.
If [param maxsplit] is greater than [code]0[/code], the number of splits may not exceed [param maxsplit]. By default, the entire string is split.
[b]Example:[/b]
[codeblocks]
[gdscript]
var some_string = "One,Two,Three,Four"
var some_array = some_string.split(",", true, 1)
print(some_array.size()) # Prints 2
print(some_array[0]) # Prints "Four"
print(some_array[1]) # Prints "Three,Two,One"
var some_array = "One,Two,Three,Four".split(",", true, 2)
print(some_array.size()) # Prints 3
print(some_array[0]) # Prints "One"
print(some_array[1]) # Prints "Two"
print(some_array[2]) # Prints "Three,Four"
[/gdscript]
[csharp]
var someString = "One,Two,Three,Four";
var someArray = someString.Split(",", true); // This is as close as it gets to Godots API.
GD.Print(someArray[0]); // Prints "Four"
GD.Print(someArray[1]); // Prints "Three,Two,One"
// C#'s `Split()` does not support the `maxsplit` parameter.
var someArray = "One,Two,Three".Split(",");
GD.Print(someArray[0]); // Prints "One"
GD.Print(someArray[1]); // Prints "Two"
GD.Print(someArray[2]); // Prints "Three"
[/csharp]
[/codeblocks]
If you need to split strings with more complex rules, use the [RegEx] class instead.
[b]Note:[/b] If you only need one substring from the array, consider using [method get_slice] which is faster. If you need to split strings with more complex rules, use the [RegEx] class instead.
</description>
</method>
<method name="split_floats" qualifiers="const">
@ -670,9 +741,13 @@
<param index="0" name="delimiter" type="String" />
<param index="1" name="allow_empty" type="bool" default="true" />
<description>
Splits the string in floats by using a delimiter string and returns an array of the substrings.
For example, [code]"1,2.5,3"[/code] will return [code][1,2.5,3][/code] if split by [code]","[/code].
If [param allow_empty] is [code]true[/code], and there are two adjacent delimiters in the string, it will add an empty string to the array of substrings at this position.
Splits the string into floats by using a [param delimiter] and returns a [PackedFloat64Array].
If [param allow_empty] is [code]false[/code], empty or invalid [float] conversions between adjacent delimiters are excluded.
[codeblock]
var a = "1,2,4.5".split_floats(",") # a is [1.0, 2.0, 4.5]
var c = "1| ||4.5".split_floats("|") # c is [1.0, 0.0, 0.0, 4.5]
var b = "1| ||4.5".split_floats("|", false) # b is [1.0, 4.5]
[/codeblock]
</description>
</method>
<method name="strip_edges" qualifiers="const">
@ -680,13 +755,14 @@
<param index="0" name="left" type="bool" default="true" />
<param index="1" name="right" type="bool" default="true" />
<description>
Returns a copy of the string stripped of any non-printable character (including tabulations, spaces and line breaks) at the beginning and the end. The optional arguments are used to toggle stripping on the left and right edges respectively.
Strips all non-printable characters from the beginning and the end of the string. These include spaces, tabulations ([code]\t[/code]), and newlines ([code]\n[/code] [code]\r[/code]).
If [param left] is [code]false[/code], ignores the string's beginning. Likewise, if [param right] is [code]false[/code], ignores the string's end.
</description>
</method>
<method name="strip_escapes" qualifiers="const">
<return type="String" />
<description>
Returns a copy of the string stripped of any escape character. These include all non-printable control characters of the first page of the ASCII table (&lt; 32), such as tabulation ([code]\t[/code] in C) and newline ([code]\n[/code] and [code]\r[/code]) characters, but not spaces.
Strips all escape characters from the string. These include all non-printable control characters of the first page of the ASCII table (values from 0 to 31), such as tabulation ([code]\t[/code]) and newline ([code]\n[/code], [code]\r[/code]) characters, but [i]not[/i] spaces.
</description>
</method>
<method name="substr" qualifiers="const">
@ -694,13 +770,13 @@
<param index="0" name="from" type="int" />
<param index="1" name="len" type="int" default="-1" />
<description>
Returns part of the string from the position [param from] with length [param len]. Argument [param len] is optional and using [code]-1[/code] will return remaining characters from given position.
Returns part of the string from the position [param from] with length [param len]. If [param len] is [code]-1[/code] (as by default), returns the rest of the string starting from the given position.
</description>
</method>
<method name="to_ascii_buffer" qualifiers="const">
<return type="PackedByteArray" />
<description>
Converts the String (which is a character array) to ASCII/Latin-1 encoded [PackedByteArray] (which is an array of bytes). The conversion is faster compared to [method to_utf8_buffer], as this method assumes that all the characters in the String are ASCII/Latin-1 characters, unsupported characters are replaced 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.
</description>
</method>
<method name="to_camel_case" qualifiers="const">
@ -712,23 +788,25 @@
<method name="to_float" qualifiers="const">
<return type="float" />
<description>
Converts a string containing a decimal number into a [code]float[/code]. The method will stop on the first non-number character except the first [code].[/code] (decimal point), and [code]e[/code] which is used for exponential.
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]
print("12.3".to_float()) # 12.3
print("1.2.3".to_float()) # 1.2
print("12ab3".to_float()) # 12
print("1e3".to_float()) # 1000
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]
</description>
</method>
<method name="to_int" qualifiers="const">
<return type="int" />
<description>
Converts a string containing an integer number into an [code]int[/code]. The method will remove any non-number character and stop if it encounters a [code].[/code].
Converts the string representing an integer number into an [int]. This method removes any non-number character and stops at the first decimal point ([code].[/code]). See also [method is_valid_int].
[codeblock]
print("123".to_int()) # 123
print("a1b2c3".to_int()) # 123
print("1.2.3".to_int()) # 1
var a = "123".to_int() # a is 123
var b = "x1y2z3".to_int() # b is 123
var c = "-1.2.3".to_int() # c is -1
var d = "Hello!".to_int() # d is 0
[/codeblock]
</description>
</method>
@ -759,33 +837,33 @@
<method name="to_utf16_buffer" qualifiers="const">
<return type="PackedByteArray" />
<description>
Converts the String (which is an array of characters) to UTF-16 encoded [PackedByteArray] (which is an array of bytes).
Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-16]UTF-16[/url] encoded [PackedByteArray].
</description>
</method>
<method name="to_utf32_buffer" qualifiers="const">
<return type="PackedByteArray" />
<description>
Converts the String (which is an array of characters) to UTF-32 encoded [PackedByteArray] (which is an array of bytes).
Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-32]UTF-32[/url] encoded [PackedByteArray].
</description>
</method>
<method name="to_utf8_buffer" qualifiers="const">
<return type="PackedByteArray" />
<description>
Converts the String (which is an array of characters) to UTF-8 encode [PackedByteArray] (which is an array of bytes). The conversion is a bit slower than [method to_ascii_buffer], but supports all UTF-8 characters. Therefore, you should prefer this function over [method to_ascii_buffer].
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.
</description>
</method>
<method name="trim_prefix" qualifiers="const">
<return type="String" />
<param index="0" name="prefix" type="String" />
<description>
Removes a given string from the start if it starts with it or leaves the string unchanged.
Removes the given [param prefix] from the start of the string, or returns the string unchanged.
</description>
</method>
<method name="trim_suffix" qualifiers="const">
<return type="String" />
<param index="0" name="suffix" type="String" />
<description>
Removes a given string from the end if it ends with it or leaves the string unchanged.
Removes the given [param suffix] from the end of the string, or returns the string unchanged.
</description>
</method>
<method name="unicode_at" qualifiers="const">
@ -798,13 +876,15 @@
<method name="uri_decode" qualifiers="const">
<return type="String" />
<description>
Decodes a string in URL encoded format. This is meant to decode 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.
[codeblocks]
[gdscript]
print("https://example.org/?escaped=" + "Godot%20Engine%3A%27docs%27".uri_decode())
var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs"
print(url.uri_decode()) # Prints "$DOCS_URL/?hightlight=Godot Engine:docs"
[/gdscript]
[csharp]
GD.Print("https://example.org/?escaped=" + "Godot%20Engine%3a%27Docs%27".URIDecode());
var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs"
GD.Print(url.URIDecode()) // Prints "$DOCS_URL/?hightlight=Godot Engine:docs"
[/csharp]
[/codeblocks]
</description>
@ -812,13 +892,19 @@
<method name="uri_encode" qualifiers="const">
<return type="String" />
<description>
Encodes a string to URL friendly format. This is meant to encode 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.
[codeblocks]
[gdscript]
print("https://example.org/?escaped=" + "Godot Engine:'docs'".uri_encode())
var prefix = "$DOCS_URL/?hightlight="
var url = prefix + "Godot Engine:docs".uri_encode()
print(url) # Prints "$DOCS_URL/?highlight=Godot%20Engine%3%docs"
[/gdscript]
[csharp]
GD.Print("https://example.org/?escaped=" + "Godot Engine:'docs'".URIEncode());
var prefix = "$DOCS_URL/?hightlight=";
var url = prefix + "Godot Engine:docs".URIEncode();
GD.Print(url); // Prints "$DOCS_URL/?highlight=Godot%20Engine%3%docs"
[/csharp]
[/codeblocks]
</description>
@ -826,7 +912,7 @@
<method name="validate_node_name" qualifiers="const">
<return type="String" />
<description>
Removes any characters from the string that are prohibited in [Node] names ([code].[/code] [code]:[/code] [code]@[/code] [code]/[/code] [code]"[/code]).
Removes all characters that are not allowed in [member Node.name] from the string ([code].[/code] [code]:[/code] [code]@[/code] [code]/[/code] [code]"[/code] [code]%[/code]).
</description>
</method>
<method name="xml_escape" qualifiers="const">