Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

StringName

A built-in type for unique strings.

Description

StringNames are immutable strings designed for general-purpose representation of unique names (also called "string interning"). Two StringNames with the same value are the same object. Comparing them is extremely fast compared to regular Strings.

You will usually pass a String to methods expecting a StringName and it will be automatically converted (often at compile time), but in rare cases you can construct a StringName ahead of time with the StringName constructor or, in GDScript, the literal syntax &"example". Manually constructing a StringName allows you to control when the conversion from String occurs or to use the literal and prevent conversions entirely.

See also NodePath, which is a similar concept specifically designed to store pre-parsed scene tree paths.

All of String's methods are available in this class too. They convert the StringName into a string, and they also return a string. This is highly inefficient and should only be used if the string is desired.

Note: In C#, an explicit conversion to System.String is required to use the methods listed on this page. Use the ToString() method to cast a StringName to a string, and then use the equivalent methods in System.String or StringExtensions.

Note: In a boolean context, a StringName will evaluate to false if it is empty (StringName("")). Otherwise, a StringName will always evaluate to true. The not operator cannot be used. Instead, is_empty should be used to check for empty StringNames.

Note

There are notable differences when using this API with C#. See C# API differences to GDScript for more information.

Constructors

StringName

StringName()

StringName

StringName(from: StringName)

StringName

StringName(from: String)

Methods

bool

begins_with(text: String) const

PackedStringArray

bigrams() const

int

bin_to_int() const

String

c_escape() const

String

c_unescape() const

String

capitalize() const

int

casecmp_to(to: String) const

bool

contains(what: String) const

int

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

int

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

String

dedent() const

bool

ends_with(text: String) const

String

erase(position: int, chars: int = 1) const

int

find(what: String, from: int = 0) const

int

findn(what: String, from: int = 0) const

String

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

String

get_base_dir() const

String

get_basename() const

String

get_extension() const

String

get_file()