mirror of
https://github.com/godotengine/godot.git
synced 2025-11-03 23:21:15 +00:00
8235005c99
(and a little improvement to wording that was bugging me)
(cherry picked from commit 05718796db)
885 lines
38 KiB
XML
885 lines
38 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="String" version="3.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
|
<brief_description>
|
|
Built-in string class.
|
|
</brief_description>
|
|
<description>
|
|
This is the built-in string class (and the one used by GDScript). It supports Unicode and provides all necessary means for string handling. Strings are reference-counted and use a copy-on-write approach, so passing them around is cheap in resources.
|
|
</description>
|
|
<tutorials>
|
|
<link>$DOCS_URL/tutorials/scripting/gdscript/gdscript_format_string.html</link>
|
|
</tutorials>
|
|
<methods>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="bool" />
|
|
<description>
|
|
Constructs a new String from the given [bool].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="int" />
|
|
<description>
|
|
Constructs a new String from the given [int].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="float" />
|
|
<description>
|
|
Constructs a new String from the given [float].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="Vector2" />
|
|
<description>
|
|
Constructs a new String from the given [Vector2].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="Rect2" />
|
|
<description>
|
|
Constructs a new String from the given [Rect2].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="Vector3" />
|
|
<description>
|
|
Constructs a new String from the given [Vector3].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="Transform2D" />
|
|
<description>
|
|
Constructs a new String from the given [Transform2D].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="Plane" />
|
|
<description>
|
|
Constructs a new String from the given [Plane].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="Quat" />
|
|
<description>
|
|
Constructs a new String from the given [Quat].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="AABB" />
|
|
<description>
|
|
Constructs a new String from the given [AABB].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="Basis" />
|
|
<description>
|
|
Constructs a new String from the given [Basis].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="Transform" />
|
|
<description>
|
|
Constructs a new String from the given [Transform].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="Color" />
|
|
<description>
|
|
Constructs a new String from the given [Color].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="NodePath" />
|
|
<description>
|
|
Constructs a new String from the given [NodePath].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="RID" />
|
|
<description>
|
|
Constructs a new String from the given [RID].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="Dictionary" />
|
|
<description>
|
|
Constructs a new String from the given [Dictionary].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="Array" />
|
|
<description>
|
|
Constructs a new String from the given [Array].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="PoolByteArray" />
|
|
<description>
|
|
Constructs a new String from the given [PoolByteArray].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="PoolIntArray" />
|
|
<description>
|
|
Constructs a new String from the given [PoolIntArray].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="PoolRealArray" />
|
|
<description>
|
|
Constructs a new String from the given [PoolRealArray].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="PoolStringArray" />
|
|
<description>
|
|
Constructs a new String from the given [PoolStringArray].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="PoolVector2Array" />
|
|
<description>
|
|
Constructs a new String from the given [PoolVector2Array].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="PoolVector3Array" />
|
|
<description>
|
|
Constructs a new String from the given [PoolVector3Array].
|
|
</description>
|
|
</method>
|
|
<method name="String">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="PoolColorArray" />
|
|
<description>
|
|
Constructs a new String from the given [PoolColorArray].
|
|
</description>
|
|
</method>
|
|
<method name="begins_with">
|
|
<return type="bool" />
|
|
<argument index="0" name="text" type="String" />
|
|
<description>
|
|
Returns [code]true[/code] if the string begins with the given string.
|
|
</description>
|
|
</method>
|
|
<method name="bigrams">
|
|
<return type="PoolStringArray" />
|
|
<description>
|
|
Returns an array containing the bigrams (pairs of consecutive letters) of this string.
|
|
[codeblock]
|
|
print("Bigrams".bigrams()) # Prints "[Bi, ig, gr, ra, am, ms]"
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="c_escape">
|
|
<return type="String" />
|
|
<description>
|
|
Returns a copy of the string with special characters escaped using the C language standard.
|
|
</description>
|
|
</method>
|
|
<method name="c_unescape">
|
|
<return type="String" />
|
|
<description>
|
|
Returns a copy of the string with escaped characters replaced by their meanings. Supported escape sequences are [code]\'[/code], [code]\"[/code], [code]\?[/code], [code]\\[/code], [code]\a[/code], [code]\b[/code], [code]\f[/code], [code]\n[/code], [code]\r[/code], [code]\t[/code], [code]\v[/code].
|
|
[b]Note:[/b] Unlike the GDScript parser, this method doesn't support the [code]\uXXXX[/code] escape sequence.
|
|
</description>
|
|
</method>
|
|
<method name="capitalize">
|
|
<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].
|
|
</description>
|
|
</method>
|
|
<method name="casecmp_to">
|
|
<return type="int" />
|
|
<argument 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 [code]to[/code] string or [code]-1[/code] if the "base" string is shorter than the [code]to[/code] 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 [code]to[/code] 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].
|
|
</description>
|
|
</method>
|
|
<method name="count">
|
|
<return type="int" />
|
|
<argument index="0" name="what" type="String" />
|
|
<argument index="1" name="from" type="int" default="0" />
|
|
<argument index="2" name="to" type="int" default="0" />
|
|
<description>
|
|
Returns the number of occurrences of substring [code]what[/code] between [code]from[/code] and [code]to[/code] positions. If [code]from[/code] and [code]to[/code] equals 0 the whole string will be used. If only [code]to[/code] equals 0 the remained substring will be used.
|
|
</description>
|
|
</method>
|
|
<method name="countn">
|
|
<return type="int" />
|
|
<argument index="0" name="what" type="String" />
|
|
<argument index="1" name="from" type="int" default="0" />
|
|
<argument index="2" name="to" type="int" default="0" />
|
|
<description>
|
|
Returns the number of occurrences of substring [code]what[/code] (ignoring case) between [code]from[/code] and [code]to[/code] positions. If [code]from[/code] and [code]to[/code] equals 0 the whole string will be used. If only [code]to[/code] equals 0 the remained substring will be used.
|
|
</description>
|
|
</method>
|
|
<method name="dedent">
|
|
<return type="String" />
|
|
<description>
|
|
Returns a copy of the string with indentation (leading tabs and spaces) removed. See also [method indent] to add indentation.
|
|
</description>
|
|
</method>
|
|
<method name="empty">
|
|
<return type="bool" />
|
|
<description>
|
|
Returns [code]true[/code] if the length of the string equals [code]0[/code].
|
|
</description>
|
|
</method>
|
|
<method name="ends_with">
|
|
<return type="bool" />
|
|
<argument index="0" name="text" type="String" />
|
|
<description>
|
|
Returns [code]true[/code] if the string ends with the given string.
|
|
</description>
|
|
</method>
|
|
<method name="erase">
|
|
<argument index="0" name="position" type="int" />
|
|
<argument index="1" name="chars" type="int" />
|
|
<description>
|
|
Erases [code]chars[/code] characters from the string starting from [code]position[/code].
|
|
</description>
|
|
</method>
|
|
<method name="find">
|
|
<return type="int" />
|
|
<argument index="0" name="what" type="String" />
|
|
<argument index="1" name="from" type="int" default="0" />
|
|
<description>
|
|
Finds the first occurrence of a substring. Returns the starting position of the substring or [code]-1[/code] if not found. Optionally, the initial search index can be passed.
|
|
[b]Note:[/b] If you just want to know whether a string contains a substring, use the [code]in[/code] operator as follows:
|
|
[codeblock]
|
|
# Will evaluate to `false`.
|
|
if "i" in "team":
|
|
pass
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="find_last">
|
|
<return type="int" />
|
|
<argument index="0" name="what" type="String" />
|
|
<description>
|
|
Finds the last occurrence of a substring. Returns the starting position of the substring or [code]-1[/code] if not found.
|
|
</description>
|
|
</method>
|
|
<method name="findn">
|
|
<return type="int" />
|
|
<argument index="0" name="what" type="String" />
|
|
<argument index="1" name="from" type="int" default="0" />
|
|
<description>
|
|
Finds the first occurrence of a substring, ignoring case. Returns the starting position of the substring or [code]-1[/code] if not found. Optionally, the initial search index can be passed.
|
|
</description>
|
|
</method>
|
|
<method name="format">
|
|
<return type="String" />
|
|
<argument index="0" name="values" type="Variant" />
|
|
<argument index="1" name="placeholder" type="String" default=""{_}"" />
|
|
<description>
|
|
Formats the string by replacing all occurrences of [code]placeholder[/code] with [code]values[/code].
|
|
</description>
|
|
</method>
|
|
<method name="get_base_dir">
|
|
<return type="String" />
|
|
<description>
|
|
If the string is a valid file path, returns the base directory name.
|
|
</description>
|
|
</method>
|
|
<method name="get_basename">
|
|
<return type="String" />
|
|
<description>
|
|
If the string is a valid file path, returns the full file path without the extension.
|
|
</description>
|
|
</method>
|
|
<method name="get_extension">
|
|
<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.
|
|
[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)
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="get_file">
|
|
<return type="String" />
|
|
<description>
|
|
If the string is a valid file path, returns the filename.
|
|
</description>
|
|
</method>
|
|
<method name="get_slice">
|
|
<return type="String" />
|
|
<argument index="0" name="delimiter" type="String" />
|
|
<argument index="1" name="slice" type="int" />
|
|
<description>
|
|
Splits a string using a [code]delimiter[/code] and returns a substring at index [code]slice[/code]. 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.
|
|
Example:
|
|
[codeblock]
|
|
print("i/am/example/string".get_slice("/", 2)) # Prints 'example'.
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="hash">
|
|
<return type="int" />
|
|
<description>
|
|
Returns the 32-bit hash value representing the string's contents.
|
|
[b]Note:[/b] [String]s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does [i]not[/i] imply the strings are equal, because different strings can have identical hash values due to hash collisions.
|
|
</description>
|
|
</method>
|
|
<method name="hex_to_int">
|
|
<return type="int" />
|
|
<description>
|
|
Converts a string containing a hexadecimal number into an integer. Hexadecimal strings are expected to be prefixed with "[code]0x[/code]" otherwise [code]0[/code] is returned.
|
|
[codeblock]
|
|
print("0xff".hex_to_int()) # Print "255"
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="http_escape">
|
|
<return type="String" />
|
|
<description>
|
|
Escapes (encodes) a string to URL friendly format. Also referred to as 'URL encode'.
|
|
[codeblock]
|
|
print("https://example.org/?escaped=" + "Godot Engine:'docs'".http_escape())
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="http_unescape">
|
|
<return type="String" />
|
|
<description>
|
|
Unescapes (decodes) a string in URL encoded format. Also referred to as 'URL decode'.
|
|
[codeblock]
|
|
print("https://example.org/?escaped=" + "Godot%20Engine%3A%27docs%27".http_unescape())
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="humanize_size">
|
|
<return type="String" />
|
|
<argument index="0" name="size" type="int" />
|
|
<description>
|
|
Converts [code]size[/code] represented as number of bytes to human-readable format using internationalized set of data size units, namely: B, KiB, MiB, GiB, TiB, PiB, EiB. Note that the next smallest unit is picked automatically to hold at most 1024 units.
|
|
[codeblock]
|
|
var bytes = 133790307
|
|
var size = String.humanize_size(bytes)
|
|
print(size) # prints "127.5 MiB"
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="indent">
|
|
<return type="String" />
|
|
<argument index="0" name="prefix" type="String" />
|
|
<description>
|
|
Returns a copy of the string with lines indented with [code]prefix[/code].
|
|
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.
|
|
</description>
|
|
</method>
|
|
<method name="insert">
|
|
<return type="String" />
|
|
<argument index="0" name="position" type="int" />
|
|
<argument index="1" name="what" type="String" />
|
|
<description>
|
|
Returns a copy of the string with the substring [code]what[/code] inserted at the given position.
|
|
</description>
|
|
</method>
|
|
<method name="is_abs_path">
|
|
<return type="bool" />
|
|
<description>
|
|
If the string is a path to a file or directory, returns [code]true[/code] if the path is absolute.
|
|
</description>
|
|
</method>
|
|
<method name="is_rel_path">
|
|
<return type="bool" />
|
|
<description>
|
|
If the string is a path to a file or directory, returns [code]true[/code] if the path is relative.
|
|
</description>
|
|
</method>
|
|
<method name="is_subsequence_of">
|
|
<return type="bool" />
|
|
<argument index="0" name="text" type="String" />
|
|
<description>
|
|
Returns [code]true[/code] if this string is a subsequence of the given string.
|
|
</description>
|
|
</method>
|
|
<method name="is_subsequence_ofi">
|
|
<return type="bool" />
|
|
<argument index="0" name="text" type="String" />
|
|
<description>
|
|
Returns [code]true[/code] if this string is a subsequence of the given string, without considering case.
|
|
</description>
|
|
</method>
|
|
<method name="is_valid_filename">
|
|
<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]: / \ ? * " | % < >[/code]
|
|
</description>
|
|
</method>
|
|
<method name="is_valid_float">
|
|
<return type="bool" />
|
|
<description>
|
|
Returns [code]true[/code] if this string contains a valid float. This is inclusive of integers, and also supports exponents:
|
|
[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"
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="is_valid_hex_number">
|
|
<return type="bool" />
|
|
<argument index="0" name="with_prefix" type="bool" default="false" />
|
|
<description>
|
|
Returns [code]true[/code] if this string contains a valid hexadecimal number. If [code]with_prefix[/code] is [code]true[/code], then a validity of the hexadecimal number is determined by [code]0x[/code] prefix, for instance: [code]0xDEADC0DE[/code].
|
|
</description>
|
|
</method>
|
|
<method name="is_valid_html_color">
|
|
<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].
|
|
</description>
|
|
</method>
|
|
<method name="is_valid_identifier">
|
|
<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.
|
|
[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"
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="is_valid_integer">
|
|
<return type="bool" />
|
|
<description>
|
|
Returns [code]true[/code] if this string contains a valid integer.
|
|
[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"
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="is_valid_ip_address">
|
|
<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.
|
|
</description>
|
|
</method>
|
|
<method name="join">
|
|
<return type="String" />
|
|
<argument index="0" name="parts" type="PoolStringArray" />
|
|
<description>
|
|
Return a [String] which is the concatenation of the [code]parts[/code]. The separator between elements is the string providing this method.
|
|
Example:
|
|
[codeblock]
|
|
print(", ".join(["One", "Two", "Three", "Four"]))
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="json_escape">
|
|
<return type="String" />
|
|
<description>
|
|
Returns a copy of the string with special characters escaped using the JSON standard.
|
|
</description>
|
|
</method>
|
|
<method name="left">
|
|
<return type="String" />
|
|
<argument index="0" name="position" type="int" />
|
|
<description>
|
|
Returns a number of characters from the left of the string.
|
|
</description>
|
|
</method>
|
|
<method name="length">
|
|
<return type="int" />
|
|
<description>
|
|
Returns the string's amount of characters.
|
|
</description>
|
|
</method>
|
|
<method name="lstrip">
|
|
<return type="String" />
|
|
<argument index="0" name="chars" type="String" />
|
|
<description>
|
|
Returns a copy of the string with characters removed from the left. The [code]chars[/code] argument is a string specifying the set of characters to be removed.
|
|
[b]Note:[/b] The [code]chars[/code] is not a prefix. See [method trim_prefix] method that will remove a single prefix string rather than a set of characters.
|
|
</description>
|
|
</method>
|
|
<method name="match">
|
|
<return type="bool" />
|
|
<argument 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].
|
|
</description>
|
|
</method>
|
|
<method name="matchn">
|
|
<return type="bool" />
|
|
<argument 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].
|
|
</description>
|
|
</method>
|
|
<method name="md5_buffer">
|
|
<return type="PoolByteArray" />
|
|
<description>
|
|
Returns the MD5 hash of the string as an array of bytes.
|
|
</description>
|
|
</method>
|
|
<method name="md5_text">
|
|
<return type="String" />
|
|
<description>
|
|
Returns the MD5 hash of the string as a string.
|
|
</description>
|
|
</method>
|
|
<method name="naturalnocasecmp_to">
|
|
<return type="int" />
|
|
<argument 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 [code]to[/code] string or [code]-1[/code] if the "base" string is shorter than the [code]to[/code] 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 [code]to[/code] 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].
|
|
</description>
|
|
</method>
|
|
<method name="nocasecmp_to">
|
|
<return type="int" />
|
|
<argument 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 [code]to[/code] string or [code]-1[/code] if the "base" string is shorter than the [code]to[/code] 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 [code]to[/code] 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].
|
|
</description>
|
|
</method>
|
|
<method name="ord_at">
|
|
<return type="int" />
|
|
<argument index="0" name="at" type="int" />
|
|
<description>
|
|
Returns the character code at position [code]at[/code].
|
|
</description>
|
|
</method>
|
|
<method name="pad_decimals">
|
|
<return type="String" />
|
|
<argument index="0" name="digits" type="int" />
|
|
<description>
|
|
Formats a number to have an exact number of [code]digits[/code] after the decimal point.
|
|
</description>
|
|
</method>
|
|
<method name="pad_zeros">
|
|
<return type="String" />
|
|
<argument index="0" name="digits" type="int" />
|
|
<description>
|
|
Formats a number to have an exact number of [code]digits[/code] before the decimal point.
|
|
</description>
|
|
</method>
|
|
<method name="percent_decode">
|
|
<return type="String" />
|
|
<description>
|
|
Decode a percent-encoded string. See [method percent_encode].
|
|
</description>
|
|
</method>
|
|
<method name="percent_encode">
|
|
<return type="String" />
|
|
<description>
|
|
Percent-encodes a string. Encodes parameters in a URL when sending a HTTP GET request (and bodies of form-urlencoded POST requests).
|
|
</description>
|
|
</method>
|
|
<method name="plus_file">
|
|
<return type="String" />
|
|
<argument index="0" name="file" type="String" />
|
|
<description>
|
|
If the string is a path, this concatenates [code]file[/code] at the end of the string as a subpath. E.g. [code]"this/is".plus_file("path") == "this/is/path"[/code].
|
|
</description>
|
|
</method>
|
|
<method name="repeat">
|
|
<return type="String" />
|
|
<argument index="0" name="count" type="int" />
|
|
<description>
|
|
Returns original string repeated a number of times. The number of repetitions is given by the argument.
|
|
</description>
|
|
</method>
|
|
<method name="replace">
|
|
<return type="String" />
|
|
<argument index="0" name="what" type="String" />
|
|
<argument index="1" name="forwhat" type="String" />
|
|
<description>
|
|
Replaces occurrences of a case-sensitive substring with the given one inside the string.
|
|
</description>
|
|
</method>
|
|
<method name="replacen">
|
|
<return type="String" />
|
|
<argument index="0" name="what" type="String" />
|
|
<argument index="1" name="forwhat" type="String" />
|
|
<description>
|
|
Replaces occurrences of a case-insensitive substring with the given one inside the string.
|
|
</description>
|
|
</method>
|
|
<method name="rfind">
|
|
<return type="int" />
|
|
<argument index="0" name="what" type="String" />
|
|
<argument index="1" name="from" type="int" default="-1" />
|
|
<description>
|
|
Performs a case-sensitive search for a substring, but starts from the end of the string instead of the beginning.
|
|
</description>
|
|
</method>
|
|
<method name="rfindn">
|
|
<return type="int" />
|
|
<argument index="0" name="what" type="String" />
|
|
<argument index="1" name="from" type="int" default="-1" />
|
|
<description>
|
|
Performs a case-insensitive search for a substring, but starts from the end of the string instead of the beginning.
|
|
</description>
|
|
</method>
|
|
<method name="right">
|
|
<return type="String" />
|
|
<argument index="0" name="position" type="int" />
|
|
<description>
|
|
Returns the right side of the string from a given position.
|
|
</description>
|
|
</method>
|
|
<method name="rsplit">
|
|
<return type="PoolStringArray" />
|
|
<argument index="0" name="delimiter" type="String" />
|
|
<argument index="1" name="allow_empty" type="bool" default="true" />
|
|
<argument index="2" name="maxsplit" type="int" default="0" />
|
|
<description>
|
|
Splits the string by a [code]delimiter[/code] string and returns an array of the substrings, starting from right.
|
|
The splits in the returned array are sorted in the same order as the original string, from left to right.
|
|
If [code]maxsplit[/code] is specified, it defines the number of splits to do from the right up to [code]maxsplit[/code]. The default value of 0 means that all items are split, thus giving the same result as [method split].
|
|
Example:
|
|
[codeblock]
|
|
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"
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="rstrip">
|
|
<return type="String" />
|
|
<argument index="0" name="chars" type="String" />
|
|
<description>
|
|
Returns a copy of the string with characters removed from the right. The [code]chars[/code] argument is a string specifying the set of characters to be removed.
|
|
[b]Note:[/b] The [code]chars[/code] is not a suffix. See [method trim_suffix] method that will remove a single suffix string rather than a set of characters.
|
|
</description>
|
|
</method>
|
|
<method name="sha1_buffer">
|
|
<return type="PoolByteArray" />
|
|
<description>
|
|
Returns the SHA-1 hash of the string as an array of bytes.
|
|
</description>
|
|
</method>
|
|
<method name="sha1_text">
|
|
<return type="String" />
|
|
<description>
|
|
Returns the SHA-1 hash of the string as a string.
|
|
</description>
|
|
</method>
|
|
<method name="sha256_buffer">
|
|
<return type="PoolByteArray" />
|
|
<description>
|
|
Returns the SHA-256 hash of the string as an array of bytes.
|
|
</description>
|
|
</method>
|
|
<method name="sha256_text">
|
|
<return type="String" />
|
|
<description>
|
|
Returns the SHA-256 hash of the string as a string.
|
|
</description>
|
|
</method>
|
|
<method name="similarity">
|
|
<return type="float" />
|
|
<argument 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.
|
|
[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"
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="simplify_path">
|
|
<return type="String" />
|
|
<description>
|
|
Returns a simplified canonical path.
|
|
</description>
|
|
</method>
|
|
<method name="split">
|
|
<return type="PoolStringArray" />
|
|
<argument index="0" name="delimiter" type="String" />
|
|
<argument index="1" name="allow_empty" type="bool" default="true" />
|
|
<argument index="2" name="maxsplit" type="int" default="0" />
|
|
<description>
|
|
Splits the string by a [code]delimiter[/code] string and returns an array of the substrings. The [code]delimiter[/code] can be of any length.
|
|
If [code]maxsplit[/code] is specified, it defines the number of splits to do from the left up to [code]maxsplit[/code]. 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.
|
|
Example:
|
|
[codeblock]
|
|
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 "One"
|
|
print(some_array[1]) # Prints "Two,Three,Four"
|
|
[/codeblock]
|
|
If you need to split strings with more complex rules, use the [RegEx] class instead.
|
|
</description>
|
|
</method>
|
|
<method name="split_floats">
|
|
<return type="PoolRealArray" />
|
|
<argument index="0" name="delimiter" type="String" />
|
|
<argument 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].
|
|
</description>
|
|
</method>
|
|
<method name="strip_edges">
|
|
<return type="String" />
|
|
<argument index="0" name="left" type="bool" default="true" />
|
|
<argument 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.
|
|
</description>
|
|
</method>
|
|
<method name="strip_escapes">
|
|
<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 (< 32), such as tabulation ([code]\t[/code] in C) and newline ([code]\n[/code] and [code]\r[/code]) characters, but not spaces.
|
|
</description>
|
|
</method>
|
|
<method name="substr">
|
|
<return type="String" />
|
|
<argument index="0" name="from" type="int" />
|
|
<argument index="1" name="len" type="int" default="-1" />
|
|
<description>
|
|
Returns part of the string from the position [code]from[/code] with length [code]len[/code]. Argument [code]len[/code] is optional and using [code]-1[/code] will return remaining characters from given position.
|
|
</description>
|
|
</method>
|
|
<method name="to_ascii">
|
|
<return type="PoolByteArray" />
|
|
<description>
|
|
Converts the String (which is a character array) to [PoolByteArray] (which is an array of bytes). The conversion is faster compared to [method to_utf8], as this method assumes that all the characters in the String are ASCII characters.
|
|
</description>
|
|
</method>
|
|
<method name="to_float">
|
|
<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.
|
|
[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
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="to_int">
|
|
<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].
|
|
[codeblock]
|
|
print("123".to_int()) # 123
|
|
print("a1b2c3".to_int()) # 123
|
|
print("1.2.3".to_int()) # 1
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="to_lower">
|
|
<return type="String" />
|
|
<description>
|
|
Returns the string converted to lowercase.
|
|
</description>
|
|
</method>
|
|
<method name="to_upper">
|
|
<return type="String" />
|
|
<description>
|
|
Returns the string converted to uppercase.
|
|
</description>
|
|
</method>
|
|
<method name="to_utf8">
|
|
<return type="PoolByteArray" />
|
|
<description>
|
|
Converts the String (which is an array of characters) to [PoolByteArray] (which is an array of bytes). The conversion is a bit slower than [method to_ascii], but supports all UTF-8 characters. Therefore, you should prefer this function over [method to_ascii].
|
|
</description>
|
|
</method>
|
|
<method name="to_wchar">
|
|
<return type="PoolByteArray" />
|
|
<description>
|
|
Converts the String (which is an array of characters) to [PoolByteArray] (which is an array of bytes).
|
|
</description>
|
|
</method>
|
|
<method name="trim_prefix">
|
|
<return type="String" />
|
|
<argument index="0" name="prefix" type="String" />
|
|
<description>
|
|
Removes a given string from the start if it starts with it or leaves the string unchanged.
|
|
</description>
|
|
</method>
|
|
<method name="trim_suffix">
|
|
<return type="String" />
|
|
<argument index="0" name="suffix" type="String" />
|
|
<description>
|
|
Removes a given string from the end if it ends with it or leaves the string unchanged.
|
|
</description>
|
|
</method>
|
|
<method name="validate_node_name">
|
|
<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]).
|
|
</description>
|
|
</method>
|
|
<method name="xml_escape">
|
|
<return type="String" />
|
|
<description>
|
|
Returns a copy of the string with special characters escaped using the XML standard.
|
|
</description>
|
|
</method>
|
|
<method name="xml_unescape">
|
|
<return type="String" />
|
|
<description>
|
|
Returns a copy of the string with escaped characters replaced by their meanings according to the XML standard.
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<constants>
|
|
</constants>
|
|
</class>
|