Attention

You are reading the latest (unstable) version of this documentation, which may document features not available or compatible with Godot 3.x.

Checking the stable version of the documentation...

Work in progress

Godot documentation is being updated to reflect the latest changes in version 4.0. Some documentation pages may still state outdated information. This banner will tell you if you're reading one of such pages.

The contents of this page are up to date. If you can still find outdated information, please open an issue.

StringName

An optimized string type for unique names.

Description

StringNames 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 StringNames with the same value are the same object). Comparing them is much faster than with regular Strings, 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 the StringName constructor or, in GDScript, the literal syntax &"example".

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 n (countn, findn, replacen, etc.) are case-insensitive (they make no distinction between uppercase and lowercase letters). Method variations prefixed with r (rfind, rsplit, etc.) are reversed, and start from the end of the string, instead of the beginning.

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

Constructors

StringName

StringName ( )

StringName

StringName ( StringName from )

StringName

StringName ( String from )

Methods

bool

begins_with ( String text ) const

PackedStringArray

bigrams ( ) const

int

bin_to_int ( ) const

String

c_escape ( ) const

String

c_unescape ( ) const

String

capitalize ( ) const

int

casecmp_to ( String to ) const

bool

contains ( String what ) const

int

count ( String what, int from=0, int to=0 ) const

int

countn ( String what, int from=0, int to=0 ) const

String

dedent ( ) const

bool

ends_with ( String text ) const

int

find ( String what, int from=0 ) const

int

findn ( String what, int from=0 ) const

String

format ( Variant values, String placeholder="{_}" ) const

String

get_base_dir ( ) const

String

get_basename ( ) const

String

get_extension ( ) const

String

get_file ( ) const

String

get_slice ( String delimiter, int slice ) const

int

get_slice_count ( String delimiter ) const

String

get_slicec ( int delimiter, int slice ) const

int

hash ( ) const

int

hex_to_int ( ) const

String

indent ( String prefix ) const

String

insert ( int position, String what ) const

bool

is_absolute_path ( ) const

bool

is_empty ( ) const

bool

is_relative_path ( ) const

bool

is_subsequence_of ( String text ) const

bool

is_subsequence_ofn ( String text ) const

bool

is_valid_filename ( ) const

bool

is_valid_float ( ) const

bool

is_valid_hex_number ( bool with_prefix=false ) const

bool

is_valid_html_color ( ) const

bool

is_valid_identifier ( ) const

bool

is_valid_int ( ) const

bool

is_valid_ip_address ( ) const

String

join ( PackedStringArray parts ) const

String

json_escape ( ) const

String

left ( int length ) const

int

length ( ) const

String

lpad ( int min_length, String character=" " ) const

String

lstrip ( String chars ) const

bool

match ( String expr ) const

bool

matchn ( String expr ) const

PackedByteArray

md5_buffer ( ) const

String

md5_text ( ) const

int

naturalnocasecmp_to ( String to ) const

int

nocasecmp_to ( String to ) const

String

pad_decimals ( int digits ) const

String

pad_zeros ( int digits ) const

String

path_join ( String file ) const

String

repeat ( int count ) const

String

replace ( String what, String forwhat ) const

String

replacen ( String what, String forwhat ) const

int

rfind ( String what, int from=-1 ) const

int

rfindn ( String what, int from=-1 ) const

String

right ( int length ) const

String

rpad ( int min_length, String character=" " ) const

PackedStringArray

rsplit ( String delimiter="", bool allow_empty=true, int maxsplit=0 ) const

String

rstrip ( String chars ) const

PackedByteArray

sha1_buffer ( ) const

String

sha1_text ( ) const

PackedByteArray

sha256_buffer ( ) const

String

sha256_text ( ) const

float

similarity ( String text ) const

String

simplify_path ( ) const

PackedStringArray

split ( String delimiter="", bool allow_empty=true, int maxsplit=0 ) const

PackedFloat64Array

split_floats ( String delimiter, bool allow_empty=true ) const

String

strip_edges ( bool left=true, bool right=true ) const

String

strip_escapes ( ) const

String

substr ( int from, int len=-1 ) const

PackedByteArray

to_ascii_buffer ( ) const

String

to_camel_case ( ) const

float

to_float ( ) const

int

to_int ( ) const

String

to_lower ( ) const

String

to_pascal_case ( ) const

String

to_snake_case ( ) const

String

to_upper ( ) const

PackedByteArray

to_utf16_buffer ( ) const

PackedByteArray

to_utf32_buffer ( ) const

PackedByteArray

to_utf8_buffer ( ) const

String

trim_prefix ( String prefix ) const

String

trim_suffix ( String suffix ) const

int

unicode_at ( int at ) const

String

uri_decode ( ) const

String

uri_encode ( ) const

String

validate_filename ( ) const

String

validate_node_name ( ) const

String

xml_escape ( bool escape_quotes=false ) const

String

xml_unescape ( ) const

Operators

bool

operator != ( String right )

bool

operator != ( StringName right )

String

operator % ( Variant right )

String

operator + ( String right )

String

operator + ( StringName right )

bool

operator < ( StringName right )

bool

operator <= ( StringName right )

bool

operator == ( String right )

bool

operator == ( StringName right )

bool

operator > ( StringName right )

bool

operator >= ( StringName right )

Constructor Descriptions

StringName StringName ( )

Constructs an empty StringName.

StringName StringName ( StringName from )

Constructs a StringName as a copy of the given StringName.

StringName StringName ( String from )

Creates a new StringName from the given String. In GDScript, StringName("example") is equivalent to &"example".

Method Descriptions

bool begins_with ( String text ) const

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

PackedStringArray bigrams ( ) 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!"]

int bin_to_int ( ) 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

String c_escape ( ) const

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

String c_unescape ( ) 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 capitalize ( ) 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"

Note: This method not the same as the default appearance of properties in the Inspector dock, as it does not capitalize acronyms ("2D", "FPS", "PNG", etc.) as you may expect.

int casecmp_to ( String to ) 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 nocasecmp_to and naturalnocasecmp_to.

bool contains ( String what ) 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 find.

int count ( String what, int from=0, int to=0 ) 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 countn ( String what, int from=0, int to=0 ) 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.

String dedent ( ) const

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

bool ends_with ( String text ) const

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

int find ( String what, int from=0 ) 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 contains. In GDScript, you may also use the in operator.

int findn ( String what, int from=0 ) 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.

String format ( Variant values, String placeholder="{_}" ) const

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

values can be a Dictionary or an Array. 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"]]))

See also the GDScript format string tutorial.

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

String get_base_dir ( ) 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_basename ( ) const

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