Table of Contents

Class String

A built-in type for strings.

String

Remarks

This is the built-in string Variant type (and the one used by GDScript). Strings may contain any number of Unicode characters, and expose methods useful for manipulating and generating strings. Strings are reference-counted and use a copy-on-write approach (every modification to a string returns a new String), so passing them around is cheap in resources.

Some string methods have corresponding variations. Variations suffixed with n (String.countn, String.findn, String.replacen, etc.) are case-insensitive (they make no distinction between uppercase and lowercase letters). Method variations prefixed with r (String.rfind, String.rsplit, etc.) are reversed, and start from the end of the string, instead of the beginning.

To convert any Variant to or from a string, see @GlobalScope.str, @GlobalScope.str_to_var, and @GlobalScope.var_to_str.

Note: In a boolean context, a string will evaluate to false if it is empty (""). Otherwise, a string will always evaluate to true.

See Also

GDScript format strings

Constructors

String

Constructs an empty String ("").

String String

String(String)

Constructs a String as a copy of the given String.

String String(String from)

Parameters

from String

String(NodePath)

Constructs a new String from the given NodePath.

String String(NodePath from)

Parameters

from NodePath

String(StringName)

Constructs a new String from the given StringName.

String String(StringName from)

Parameters

from StringName

Methods

begins_with(String)

Qualifiers: const

Returns true if the string begins with the given text. See also String.ends_with.

bool begins_with(String text)

Parameters

text String

bigrams

Qualifiers: const

Returns an array containing the bigrams (pairs of consecutive characters) of this string.

print("Get up!".bigrams()) # Prints ["Ge", "et", "t ", " u", "up", "p!"]


PackedStringArray bigrams

bin_to_int

Qualifiers: const

Converts the string representing a binary number into an int. The string may optionally be prefixed with "0b", and an additional - prefix for negative numbers.

print("101".bin_to_int())   # Prints 5
print("0b101".bin_to_int()) # Prints 5
print("-0b10".bin_to_int()) # Prints -2


int bin_to_int

c_escape

Qualifiers: const

Returns a copy of the string with special characters escaped using the C language standard.

String c_escape

c_unescape

Qualifiers: const

Returns a copy of the string with escaped characters replaced by their meanings. Supported escape sequences are \', \", \\, \a, \b, \f, \n, \r, \t, \v.

Note: Unlike the GDScript parser, this method doesn't support the \uXXXX escape sequence.

String c_unescape

capitalize

Qualifiers: const

Changes the appearance of the string: replaces underscores (_) 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.

"move_local_x".capitalize()   # Returns "Move Local X"
"sceneFile_path".capitalize() # Returns "Scene File Path"
"2D, FPS, PNG".capitalize()   # Returns "2d, Fps, Png"


String capitalize

casecmp_to(String)

Qualifiers: const

Performs a case-sensitive comparison to another string. Returns -1 if less than, 1 if greater than, or 0 if equal. "Less than" and "greater than" are determined by the Unicode code points of each string, which roughly matches the alphabetical order.

With different string lengths, returns 1 if this string is longer than the to string, or -1 if shorter. Note that the length of empty strings is always 0.

To get a bool result from a string comparison, use the == operator instead. See also String.nocasecmp_to, String.filecasecmp_to, and String.naturalcasecmp_to.

int casecmp_to(String to)

Parameters

to String

chr(int)

Qualifiers: static

Returns a single Unicode character from the decimal char. You may use unicodelookup.com or unicode.org as points of reference.

print(String.chr(65))     # Prints "A"
print(String.chr(129302)) # Prints "🤖" (robot face emoji)


String chr(int char)

Parameters

char int

contains(String)

Qualifiers: const

Returns true if the string contains what. In GDScript, this corresponds to the in operator.

print("Node".contains("de")) # Prints true
print("team".contains("I"))  # Prints false
print("I" in "team")         # Prints false

If you need to know where what is within the string, use String.find. See also String.containsn.

bool contains(String what)

Parameters

what String

containsn(String)

Qualifiers: const

Returns true if the string contains what, ignoring case.

If you need to know where what is within the string, use String.findn. See also String.contains.

bool containsn(String what)

Parameters

what String

count(String, int, int)

Qualifiers: const

Returns the number of occurrences of the substring what between from and to positions. If to is 0, the search continues until the end of the string.

int count(String what, int from, int to)

Parameters

what String
from int
to int

countn(String, int, int)

Qualifiers: const

Returns the number of occurrences of the substring what between from and to positions, ignoring case. If to is 0, the search continues until the end of the string.

int countn(String what, int from, int to)

Parameters

what String
from int
to int

dedent

Qualifiers: const

Returns a copy of the string with indentation (leading tabs and spaces) removed. See also String.indent to add indentation.

String dedent

ends_with(String)

Qualifiers: const

Returns true if the string ends with the given text. See also String.begins_with.

bool ends_with(String text)

Parameters

text String

erase(int, int)

Qualifiers: const

Returns a string with chars characters erased starting from position. If chars goes beyond the string's length given the specified position, fewer characters will be erased from the returned string. Returns an empty string if either position or chars is negative. Returns the original string unmodified if chars is 0.

String erase(int position, int chars)

Parameters

position int
chars int

filecasecmp_to(String)

Qualifiers: const

Like String.naturalcasecmp_to but prioritizes strings that begin with periods (.) and underscores (_) before any other character. Useful when sorting folders or file names.

To get a bool result from a string comparison, use the == operator instead. See also String.filenocasecmp_to, String.naturalcasecmp_to, and String.casecmp_to.

int filecasecmp_to(String to)

Parameters

to String

filenocasecmp_to(String)

Qualifiers: const

Like String.naturalnocasecmp_to but prioritizes strings that begin with periods (.) and underscores (_) before any other character. Useful when sorting folders or file names.

To get a bool result from a string comparison, use the == operator instead. See also String.filecasecmp_to, String.naturalnocasecmp_to, and String.nocasecmp_to.

int filenocasecmp_to(String to)

Parameters

to String

find(String, int)

Qualifiers: const

Returns the index of the first occurrence of what in this string, or -1 if there are none. The search's start can be specified with from, continuing to the end of the string.

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

Note: If you just want to know whether the string contains what, use String.contains. In GDScript, you may also use the in operator.

int find(String what, int from)

Parameters

what String
from int

findn(String, int)

Qualifiers: const

Returns the index of the first case-insensitive occurrence of what in this string, or -1 if there are none. The starting search index can be specified with from, continuing to the end of the string.

int findn(String what, int from)

Parameters

what String
from int

format(Variant, String)

Qualifiers: const

Formats the string by replacing all occurrences of placeholder with the elements of values.

values can be a Dictionary, an Array, or an Object. Any underscores in placeholder will be replaced with the corresponding keys in advance. Array elements use their index as keys.

# Prints "Waiting for Godot is a play by Samuel Beckett, and Godot Engine is named after it."
var use_array_values = "Waiting for {0} is a play by {1}, and {0} Engine is named after it."
print(use_array_values.format(["Godot", "Samuel Beckett"]))

# Prints "User 42 is Godot."
print("User {id} is {name}.".format({"id": 42, "name": "Godot"}))

Some additional handling is performed when values is an Array. If placeholder does not contain an underscore, the elements of the values array will be used to replace one occurrence of the placeholder in order; If an element of values is another 2-element array, it'll be interpreted as a key-value pair.

# Prints "User 42 is Godot."
print("User {} is {}.".format([42, "Godot"], "{}"))
print("User {id} is {name}.".format([["id", 42], ["name", "Godot"]]))

When passing an Object, the property names from get_property_list are used as keys.

# Prints "Visible true, position (0, 0)"
var node = Node2D.new()
print("Visible {visible}, position {position}".format(node))

See also the GDScript format string tutorial.

Note: Each replacement is done sequentially for each element of values, not all at once. This means that if any element is inserted and it contains another placeholder, it may be changed by the next replacement. While this can be very useful, it often causes unexpected results. If not necessary, make sure values's elements do not contain placeholders.

print("{0} {1}".format(["{1}", "x"]))           # Prints "x x"
print("{0} {1}".format(["x", "{0}"]))           # Prints "x {0}"
print("{a} {b}".format({"a": "{b}", "b": "c"})) # Prints "c c"
print("{a} {b}".format({"b": "c", "a": "{b}"})) # Prints "{b} c"

Note: In C#, it's recommended to interpolate strings with "$", instead.

String format(Variant values, String placeholder)

Parameters

values Variant
placeholder String

get_base_dir

Qualifiers: const

If the string is a valid file path, returns the base directory name.

var dir_path = "/path/to/file.txt".get_base_dir() # dir_path is "/path/to"


String get_base_dir

get_basename

Qualifiers: const

If the string is a valid file path, returns the full file path, without the extension.

var base = "/path/to/file.txt".get_basename() # base is "/path/to/file"


String get_basename

get_extension

Qualifiers: const

If the string is a valid file name or path, returns the file extension without the leading period (.). Otherwise, returns an 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 ""


String get_extension

get_file

Qualifiers: const

If the string is a valid file path, returns the file name, including the extension.

var file = "/path/to/icon.png".get_file() # file is "icon.png"


String get_file

get_slice(String, int)

Qualifiers: const

Splits the string using a delimiter and returns the substring at index slice. Returns the original string if delimiter does not occur in the string. Returns an empty string if the slice does not exist.

This is faster than String.split, if you only need one substring.

print("i/am/example/hi".get_slice("/", 2)) # Prints "example"


String get_slice(String delimiter, int slice)

Parameters

delimiter String
slice int

get_slice_count(String)

Qualifiers: const

Returns the total number of slices when the string is split with the given delimiter (see String.split).

int get_slice_count(String delimiter)

Parameters

delimiter String

get_slicec(int, int)

Qualifiers: const

Splits the string using a Unicode character with code delimiter and returns the substring at index slice. Returns an empty string if the slice does not exist.

This is faster than String.split, if you only need one substring.

String get_slicec(int delimiter, int slice)

Parameters

delimiter int
slice int

hash

Qualifiers: const

Returns the 32-bit hash value representing the string's contents.

Note: Strings with equal hash values are not guaranteed to be the same, as a result of hash collisions. On the contrary, strings with different hash values are guaranteed to be different.

int hash

hex_decode

Qualifiers: const

Decodes a hexadecimal string as a PackedByteArray.

var text = "hello world"
var encoded = text.to_utf8_buffer().hex_encode() # outputs "68656c6c6f20776f726c64"
print(buf.hex_decode().get_string_from_utf8())


PackedByteArray hex_decode

hex_to_int

Qualifiers: const

Converts the string representing a hexadecimal number into an int. The string may be optionally prefixed with "0x", and an additional - prefix for negative numbers.

print("0xff".hex_to_int()) # Prints 255
print("ab".hex_to_int())   # Prints 171


int hex_to_int

humanize_size(int)

Qualifiers: static

Converts size which represents a number of bytes into a human-readable form.

The result is in IEC prefix format, which may end in either "B", "KiB", "MiB", "GiB", "TiB", "PiB", or "EiB".

String humanize_size(int size)

Parameters

size int

indent(String)

Qualifiers: const

Indents every line of the string with the given prefix. Empty lines are not indented. See also dedent to remove indentation.

For example, the string can be indented with two tabulations using "\t\t", or four spaces using " ".

String indent(String prefix)

Parameters

prefix String

insert(int, String)

Qualifiers: const

Inserts what at the given position in the string.

String insert(int position, String what)

Parameters

position int
what String

is_absolute_path

Qualifiers: const

Returns true if the string is a path to a file or directory, and its starting point is explicitly defined. This method is the opposite of is_relative_path.

This includes all paths starting with "res://", "user://", "C:\", "/", etc.

bool is_absolute_path

is_empty

Qualifiers: const

Returns true if the string's length is 0 (""). See also length.

bool is_empty

is_relative_path

Qualifiers: const

Returns true 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 "./". This method is the opposite of is_absolute_path.

bool is_relative_path

is_subsequence_of(String)

Qualifiers: const

Returns true if all characters of this string can be found in text in their original order.

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


bool is_subsequence_of(String text)

Parameters

text String

is_subsequence_ofn(String)

Qualifiers: const

Returns true if all characters of this string can be found in text in their original order, ignoring case.

bool is_subsequence_ofn(String text)

Parameters

text String

is_valid_ascii_identifier

Qualifiers: const

Returns true if this string is a valid ASCII identifier. A valid ASCII identifier may contain only letters, digits, and underscores (_), and the first character may not be a digit.

print("node_2d".is_valid_ascii_identifier())    # Prints true
print("TYPE_FLOAT".is_valid_ascii_identifier()) # Prints true
print("1st_method".is_valid_ascii_identifier()) # Prints false
print("MyMethod#2".is_valid_ascii_identifier()) # Prints false

See also is_valid_unicode_identifier.

bool is_valid_ascii_identifier

is_valid_filename

Qualifiers: const

Returns true if this string does not contain characters that are not allowed in file names (: / \ ? * " | % < >).

bool is_valid_filename

is_valid_float

Qualifiers: const

Returns true if this string represents a valid floating-point number. A valid float may contain only digits, one decimal point (.), and the exponent letter (e). It may also be prefixed with a positive (+) or negative (-) sign. Any valid integer is also a valid float (see is_valid_int). See also to_float.

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


bool is_valid_float

is_valid_hex_number(bool)

Qualifiers: const

Returns true if this string is a valid hexadecimal number. A valid hexadecimal number only contains digits or letters A to F (either uppercase or lowercase), and may be prefixed with a positive (+) or negative (-) sign.

If with_prefix is true, the hexadecimal number needs to prefixed by "0x" to be considered valid.

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


bool is_valid_hex_number(bool with_prefix)

Parameters

with_prefix bool

is_valid_html_color

Qualifiers: const

Returns true if this string is a valid color in hexadecimal HTML notation. The string must be a hexadecimal value (see String.is_valid_hex_number) of either 3, 4, 6 or 8 digits, and may be prefixed by a hash sign (#). Other HTML notations for colors, such as names or hsl(), are not considered valid. See also Color.html.

bool is_valid_html_color

is_valid_identifier

Qualifiers: const

Returns true if this string is a valid identifier. A valid identifier may contain only letters, digits and underscores (_), and the first character may not be a digit.

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


bool is_valid_identifier

is_valid_int

Qualifiers: const

Returns true if this string represents a valid integer. A valid integer only contains digits, and may be prefixed with a positive (+) or negative (-) sign. See also to_int.

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


bool is_valid_int

is_valid_ip_address

Qualifiers: const

Returns true if this string represents a well-formatted IPv4 or IPv6 address. This method considers reserved IP addresses such as "0.0.0.0" and "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" as valid.

bool is_valid_ip_address

is_valid_unicode_identifier

Qualifiers: const

Returns true if this string is a valid Unicode identifier.

A valid Unicode identifier must begin with a Unicode character of class XID_Start or "_", and may contain Unicode characters of class XID_Continue in the other positions.

print("node_2d".is_valid_unicode_identifier())      # Prints true
print("1st_method".is_valid_unicode_identifier())   # Prints false
print("MyMethod#2".is_valid_unicode_identifier())   # Prints false
print("állóképesség".is_valid_unicode_identifier()) # Prints true
print("выносливость".is_valid_unicode_identifier()) # Prints true
print("体力".is_valid_unicode_identifier())         # Prints true

See also is_valid_ascii_identifier.

Note: This method checks identifiers the same way as GDScript. See TextServer.is_valid_identifier for more advanced checks.

bool is_valid_unicode_identifier

join(PackedStringArray)

Qualifiers: const

Returns the concatenation of parts' elements, with each element separated by the string calling this method. This method is the opposite of String.split.

var fruits = ["Apple", "Orange", "Pear", "Kiwi"]

print(", ".join(fruits))  # Prints "Apple, Orange, Pear, Kiwi"
print("---".join(fruits)) # Prints "Apple---Orange---Pear---Kiwi"


String join(PackedStringArray parts)

Parameters

parts PackedStringArray

json_escape

Qualifiers: const

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 c_unescape to unescape the string, if necessary.

String json_escape

left(int)

Qualifiers: const

Returns the first length characters from the beginning of the string. If length is negative, strips the last length characters from the string's end.

print("Hello World!".left(3))  # Prints "Hel"
print("Hello World!".left(-4)) # Prints "Hello Wo"


String left(int length)

Parameters

length int

length

Qualifiers: const

Returns the number of characters in the string. Empty strings ("") always return 0. See also is_empty.

int length

lpad(int, String)

Qualifiers: const

Formats the string to be at least min_length long by adding characters to the left of the string, if necessary. See also String.rpad.

String lpad(int min_length, String character)

Parameters

min_length int
character String

lstrip(String)

Qualifiers: const

Removes a set of characters defined in chars from the string's beginning. See also String.rstrip.

Note: chars is not a prefix. Use String.trim_prefix to remove a single prefix, rather than a set of characters.

String lstrip(String chars)

Parameters

chars String

match(String)

Qualifiers: const

Does a simple expression match (also called "glob" or "globbing"), where * matches zero or more arbitrary characters and ? matches any single character except a period (.). An empty string or empty expression always evaluates to false.

bool match(String expr)

Parameters

expr String

matchn(String)

Qualifiers: const

Does a simple case-insensitive expression match, where * matches zero or more arbitrary characters and ? matches any single character except a period (.). An empty string or empty expression always evaluates to false.

bool matchn(String expr)

Parameters

expr String

md5_buffer

Qualifiers: const

Returns the MD5 hash of the string as a PackedByteArray.

PackedByteArray md5_buffer

md5_text

Qualifiers: const

Returns the MD5 hash of the string as another String.

String md5_text

naturalcasecmp_to(String)

Qualifiers: const

Performs a case-sensitive, natural order comparison to another string. Returns -1 if less than, 1 if greater than, or 0 if equal. "Less than" or "greater than" are determined by the Unicode code points of each string, which roughly matches the alphabetical order.

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 ["1", "2", "3", ...], not ["1", "10", "2", "3", ...].

With different string lengths, returns 1 if this string is longer than the to string, or -1 if shorter. Note that the length of empty strings is always 0.

To get a bool result from a string comparison, use the == operator instead. See also String.naturalnocasecmp_to, String.filecasecmp_to, and String.nocasecmp_to.

int naturalcasecmp_to(String to)

Parameters

to String

naturalnocasecmp_to(String)

Qualifiers: const

Performs a case-insensitive, natural order comparison to another string. Returns -1 if less than, 1 if greater than, or 0 if equal. "Less than" or "greater than" are determined by the Unicode code points 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 ["1", "2", "3", ...], not ["1", "10", "2", "3", ...].

With different string lengths, returns 1 if this string is longer than the to string, or -1 if shorter. Note that the length of empty strings is always 0.

To get a bool result from a string comparison, use the == operator instead. See also String.naturalcasecmp_to, String.filenocasecmp_to, and String.casecmp_to.

int naturalnocasecmp_to(String to)

Parameters

to String

nocasecmp_to(String)

Qualifiers: const

Performs a case-insensitive comparison to another string. Returns -1 if less than, 1 if greater than, or 0 if equal. "Less than" or "greater than" are determined by the Unicode code points of each string, which roughly matches the alphabetical order. Internally, lowercase characters are converted to uppercase for the comparison.

With different string lengths, returns 1 if this string is longer than the to string, or -1 if shorter. Note that the length of empty strings is always 0.

To get a bool result from a string comparison, use the == operator instead. See also String.casecmp_to, String.filenocasecmp_to, and String.naturalnocasecmp_to.

int nocasecmp_to(String to)

Parameters

to String

num(float, int)

Qualifiers: static

Converts a float to a string representation of a decimal number, with the number of decimal places specified in decimals.

If decimals is -1 as by default, the string representation may only have up to 14 significant digits, with digits before the decimal point having priority over digits after.

Trailing zeros are not included in the string. The last digit is rounded, not truncated.

String.num(3.141593)     # Returns "3.141593"
String.num(3.141593, 3)  # Returns "3.142"
String.num(3.14159300)   # Returns "3.141593"

# Here, the last digit will be rounded up,
# which reduces the total digit count, since trailing zeros are removed:
String.num(42.129999, 5) # Returns "42.13"

# If `decimals` is not specified, the maximum number of significant digits is 14:
String.num(-0.0000012345432123454321)     # Returns "-0.00000123454321"
String.num(-10000.0000012345432123454321) # Returns "-10000.0000012345"


String num(float number, int decimals)

Parameters

number float
decimals int

num_int64(int, int, bool)

Qualifiers: static

Converts the given number to a string representation, with the given base.

By default, base is set to decimal (10). Other common bases in programming include binary (2), octal (8), hexadecimal (16).

If capitalize_hex is true, digits higher than 9 are represented in uppercase.

String num_int64(int number, int base, bool capitalize_hex)

Parameters

number int
base int
capitalize_hex bool

num_scientific(float)

Qualifiers: static

Converts the given number to a string representation, in scientific notation.

var n = -5.2e8
print(n)                        # Prints -520000000
print(String.num_scientific(n)) # Prints -5.2e+08

Note: In C#, this method is not implemented. To achieve similar results, see C#'s Standard numeric format strings

String num_scientific(float number)

Parameters

number float

num_uint64(int, int, bool)

Qualifiers: static

Converts the given unsigned int to a string representation, with the given base.

By default, base is set to decimal (10). Other common bases in programming include binary (2), octal (8), hexadecimal (16).

If capitalize_hex is true, digits higher than 9 are represented in uppercase.

String num_uint64(int number, int base, bool capitalize_hex)

Parameters

number int
base int
capitalize_hex bool

pad_decimals(int)

Qualifiers: const

Formats the string representing a number to have an exact number of digits after the decimal point.

String pad_decimals(int digits)

Parameters

digits int

pad_zeros(int)

Qualifiers: const

Formats the string representing a number to have an exact number of digits before the decimal point.

String pad_zeros(int digits)

Parameters

digits int

path_join(String)

Qualifiers: const

Concatenates file at the end of the string as a subpath, adding / if necessary.

Example: "this/is".path_join("path") == "this/is/path".

String path_join(String file)

Parameters

file String

repeat(int)

Qualifiers: const

Repeats this string a number of times. count needs to be greater than 0. Otherwise, returns an empty string.

String repeat(int count)

Parameters

count int

replace(String, String)

Qualifiers: const

Replaces all occurrences of what inside the string with the given forwhat.

String replace(String what, String forwhat)

Parameters

what String
forwhat String

replacen(String, String)

Qualifiers: const

Replaces all case-insensitive occurrences of what inside the string with the given forwhat.

String replacen(String what, String forwhat)

Parameters

what String
forwhat String

reverse

Qualifiers: const

Returns the copy of this string in reverse order. This operation works on unicode codepoints, rather than sequences of codepoints, and may break things like compound letters or emojis.

String reverse

rfind(String, int)

Qualifiers: const

Returns the index of the last occurrence of what in this string, or -1 if there are none. The search's start can be specified with from, continuing to the beginning of the string. This method is the reverse of String.find.

int rfind(String what, int from)

Parameters

what String
from int

rfindn(String, int)

Qualifiers: const

Returns the index of the last case-insensitive occurrence of what in this string, or -1 if there are none. The starting search index can be specified with from, continuing to the beginning of the string. This method is the reverse of String.findn.

int rfindn(String what, int from)

Parameters

what String
from int

right(int)

Qualifiers: const

Returns the last length characters from the end of the string. If length is negative, strips the first length characters from the string's beginning.

print("Hello World!".right(3))  # Prints "ld!"
print("Hello World!".right(-4)) # Prints "o World!"


String right(int length)

Parameters

length int

rpad(int, String)

Qualifiers: const

Formats the string to be at least min_length long, by adding characters to the right of the string, if necessary. See also String.lpad.

String rpad(int min_length, String character)

Parameters

min_length int
character String

rsplit(String, bool, int)

Qualifiers: const

Splits the string using a 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 delimiter is an empty string, each substring will be a single character.

If allow_empty is false, empty strings between adjacent delimiters are excluded from the array.

If maxsplit is greater than 0, the number of splits may not exceed maxsplit. By default, the entire string is split, which is mostly identical to String.split.

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"


PackedStringArray rsplit(String delimiter, bool allow_empty, int maxsplit)

Parameters

delimiter String
allow_empty bool
maxsplit int

rstrip(String)

Qualifiers: const

Removes a set of characters defined in chars from the string's end. See also String.lstrip.

Note: chars is not a suffix. Use String.trim_suffix to remove a single suffix, rather than a set of characters.

String rstrip(String chars)

Parameters

chars String

sha1_buffer

Qualifiers: const

Returns the SHA-1 hash of the string as a PackedByteArray.

PackedByteArray sha1_buffer

sha1_text

Qualifiers: const

Returns the SHA-1 hash of the string as another String.

String sha1_text

sha256_buffer

Qualifiers: const

Returns the SHA-256 hash of the string as a PackedByteArray.

PackedByteArray sha256_buffer

sha256_text

Qualifiers: const

Returns the SHA-256 hash of the string as another String.

String sha256_text

similarity(String)

Qualifiers: const

Returns the similarity index (Sørensen-Dice coefficient) of this string compared to another. A result of 1.0 means totally similar, while 0.0 means totally dissimilar.

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


float similarity(String text)

Parameters

text String

simplify_path

Qualifiers: const

If the string is a valid file path, converts the string into a canonical path. This is the shortest possible path, without "./", and all the unnecessary ".." and "/".

var simple_path = "./path/to///../file".simplify_path()
print(simple_path) # Prints "path/file"


String simplify_path

split(String, bool, int)

Qualifiers: const

Splits the string using a delimiter and returns an array of the substrings. If delimiter is an empty string, each substring will be a single character. This method is the opposite of String.join.

If allow_empty is false, empty strings between adjacent delimiters are excluded from the array.

If maxsplit is greater than 0, the number of splits may not exceed maxsplit. By default, the entire string is split.

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"

Note: If you only need one substring from the array, consider using String.get_slice which is faster. If you need to split strings with more complex rules, use the RegEx class instead.

PackedStringArray split(String delimiter, bool allow_empty, int maxsplit)

Parameters

delimiter String
allow_empty bool
maxsplit int

split_floats(String, bool)

Qualifiers: const

Splits the string into floats by using a delimiter and returns a PackedFloat64Array.

If allow_empty is false, empty or invalid float conversions between adjacent delimiters are excluded.

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]


PackedFloat64Array split_floats(String delimiter, bool allow_empty)

Parameters

delimiter String
allow_empty bool

strip_edges(bool, bool)

Qualifiers: const

Strips all non-printable characters from the beginning and the end of the string. These include spaces, tabulations (\t), and newlines (\n \r).

If left is false, ignores the string's beginning. Likewise, if right is false, ignores the string's end.

String strip_edges(bool left, bool right)

Parameters

left bool
right bool

strip_escapes

Qualifiers: const

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 (\t) and newline (\n, \r) characters, but not spaces.

String strip_escapes

substr(int, int)

Qualifiers: const

Returns part of the string from the position from with length len. If len is -1 (as by default), returns the rest of the string starting from the given position.

String substr(int from, int len)

Parameters

from int
len int

to_ascii_buffer

Qualifiers: const

Converts the string to an ASCII/Latin-1 encoded PackedByteArray. This method is slightly faster than to_utf8_buffer, but replaces all unsupported characters with spaces. This is the inverse of get_string_from_ascii.

PackedByteArray to_ascii_buffer

to_camel_case

Qualifiers: const

Returns the string converted to camelCase.

String to_camel_case

to_float

Qualifiers: const

Converts the string representing a decimal number into a float. This method stops on the first non-number character, except the first decimal point (.) and the exponent letter (e). See also is_valid_float.

var a = "12.35".to_float()  # a is 12.35
var b = "1.2.3".to_float()  # b is 1.2
var c = "12xy3".to_float()  # c is 12.0
var d = "1e3".to_float()    # d is 1000.0
var e = "Hello!".to_float() # e is 0.0


float to_float

to_int

Qualifiers: const

Converts the string representing an integer number into an int. This method removes any non-number character and stops at the first decimal point (.). See also is_valid_int.

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


int to_int

to_lower

Qualifiers: const

Returns the string converted to lowercase.

String to_lower

to_pascal_case

Qualifiers: const

Returns the string converted to PascalCase.

String to_pascal_case

to_snake_case

Qualifiers: const

Returns the string converted to snake_case.

Note: Numbers followed by a single letter are not separated in the conversion to keep some words (such as "2D") together.

"Node2D".to_snake_case()               # Returns "node_2d"
"2nd place".to_snake_case()            # Returns "2_nd_place"
"Texture3DAssetFolder".to_snake_case() # Returns "texture_3d_asset_folder"


String to_snake_case

to_upper

Qualifiers: const

Returns the string converted to UPPERCASE.

String to_upper

to_utf8_buffer

Qualifiers: const

Converts the string to a UTF-8 encoded PackedByteArray. This method is slightly slower than to_ascii_buffer, but supports all UTF-8 characters. For most cases, prefer using this method. This is the inverse of get_string_from_utf8.

PackedByteArray to_utf8_buffer

to_utf16_buffer

Qualifiers: const

Converts the string to a UTF-16 encoded PackedByteArray. This is the inverse of get_string_from_utf16.

PackedByteArray to_utf16_buffer

to_utf32_buffer

Qualifiers: const

Converts the string to a UTF-32 encoded PackedByteArray. This is the inverse of get_string_from_utf32.

PackedByteArray to_utf32_buffer

to_wchar_buffer

Qualifiers: const

Converts the string to a wide character (wchar_t, UTF-16 on Windows, UTF-32 on other platforms) encoded PackedByteArray. This is the inverse of get_string_from_wchar.

PackedByteArray to_wchar_buffer

trim_prefix(String)

Qualifiers: const

Removes the given prefix from the start of the string, or returns the string unchanged.

String trim_prefix(String prefix)

Parameters

prefix String

trim_suffix(String)

Qualifiers: const

Removes the given suffix from the end of the string, or returns the string unchanged.

String trim_suffix(String suffix)

Parameters

suffix String

unicode_at(int)

Qualifiers: const

Returns the character code at position at.

int unicode_at(int at)

Parameters

at int

uri_decode

Qualifiers: const

Decodes the string from its URL-encoded format. This method is meant to properly decode the parameters in a URL when receiving an HTTP request. See also uri_encode.

var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs"
print(url.uri_decode()) # Prints "$DOCS_URL/?highlight=Godot Engine:docs"


String uri_decode

uri_encode

Qualifiers: const

Encodes the string to URL-friendly format. This method is meant to properly encode the parameters in a URL when sending an HTTP request. See also uri_decode.

var prefix = "$DOCS_URL/?highlight="
var url = prefix + "Godot Engine:docs".uri_encode()

print(url) # Prints "$DOCS_URL/?highlight=Godot%20Engine%3%docs"


String uri_encode

validate_filename

Qualifiers: const

Returns a copy of the string with all characters that are not allowed in is_valid_filename replaced with underscores.

String validate_filename

validate_node_name

Qualifiers: const

Returns a copy of the string with all characters that are not allowed in name (. : @ / " %) replaced with underscores.

String validate_node_name

xml_escape(bool)

Qualifiers: const

Returns a copy of the string with special characters escaped using the XML standard. If escape_quotes is true, the single quote (') and double quote (") characters are also escaped.

String xml_escape(bool escape_quotes)

Parameters

escape_quotes bool

xml_unescape

Qualifiers: const

Returns a copy of the string with escaped characters replaced by their meanings according to the XML standard.

String xml_unescape

Operators

!= (String)

Returns true if both strings do not contain the same sequence of characters.

bool != (String right)

Parameters

right String

!= (StringName)

Returns true if this String is not equivalent to the given StringName.

bool != (StringName right)

Parameters

right StringName

% (Variant)

Formats the String, replacing the placeholders with one or more parameters. To pass multiple parameters, right needs to be an Array.

print("I caught %d fishes!" % 2) # Prints "I caught 2 fishes!"

var my_message = "Travelling to %s, at %2.2f km/h."
var location = "Deep Valley"
var speed = 40.3485
print(my_message % [location, speed]) # Prints "Travelling to Deep Valley, at 40.35 km/h."

For more information, see the GDScript format strings tutorial.

Note: In C#, this operator is not available. Instead, see how to interpolate strings with "$".

String % (Variant right)

Parameters

right Variant

+ (String)

Appends right at the end of this String, also known as a string concatenation.

String + (String right)

Parameters

right String

+ (StringName)

Appends right at the end of this String, returning a String. This is also known as a string concatenation.

String + (StringName right)

Parameters

right StringName

< (String)

Returns true if the left String comes before right in Unicode order, which roughly matches the alphabetical order. Useful for sorting.

bool < (String right)

Parameters

right String

<= (String)

Returns true if the left String comes before right in Unicode order, which roughly matches the alphabetical order, or if both are equal.

bool <= (String right)

Parameters

right String

== (String)

Returns true if both strings contain the same sequence of characters.

bool == (String right)

Parameters

right String

== (StringName)

Returns true if this String is equivalent to the given StringName.

bool == (StringName right)

Parameters

right StringName

> (String)

Returns true if the left String comes after right in Unicode order, which roughly matches the alphabetical order. Useful for sorting.

bool > (String right)

Parameters

right String

>= (String)

Returns true if the left String comes after right in Unicode order, which roughly matches the alphabetical order, or if both are equal.

bool >= (String right)

Parameters

right String

[] (int)

Returns a new String that only contains the character at index. Indices start from 0. If index is greater or equal to 0, the character is fetched starting from the beginning of the string. If index is a negative value, it is fetched starting from the end. Accessing a string out-of-bounds will cause a run-time error, pausing the project execution if run from the editor.

String [] (int index)

Parameters

index int