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 from ) |
|
StringName ( String from ) |
Methods¶
begins_with ( String text ) const |
|
bigrams ( ) const |
|
bin_to_int ( ) const |
|
c_escape ( ) const |
|
c_unescape ( ) const |
|
capitalize ( ) const |
|
casecmp_to ( String to ) const |
|
dedent ( ) const |
|
get_base_dir ( ) const |
|
get_basename ( ) const |
|
get_extension ( ) const |
|
get_file ( ) const |
|
get_slice_count ( String delimiter ) const |
|
get_slicec ( int delimiter, int slice ) const |
|
hash ( ) const |
|
hex_to_int ( ) const |
|
is_absolute_path ( ) const |
|
is_empty ( ) const |
|
is_relative_path ( ) const |
|
is_subsequence_of ( String text ) const |
|
is_subsequence_ofn ( String text ) const |
|
is_valid_filename ( ) const |
|
is_valid_float ( ) const |
|
is_valid_hex_number ( bool with_prefix=false ) const |
|
is_valid_html_color ( ) const |
|
is_valid_identifier ( ) const |
|
is_valid_int ( ) const |
|
is_valid_ip_address ( ) const |
|
join ( PackedStringArray parts ) const |
|
json_escape ( ) const |
|
length ( ) const |
|
md5_buffer ( ) const |
|
md5_text ( ) const |
|
naturalnocasecmp_to ( String to ) const |
|
nocasecmp_to ( String to ) const |
|
pad_decimals ( int digits ) const |
|
rsplit ( String delimiter="", bool allow_empty=true, int maxsplit=0 ) const |
|
sha1_buffer ( ) const |
|
sha1_text ( ) const |
|
sha256_buffer ( ) const |
|
sha256_text ( ) const |
|
similarity ( String text ) const |
|
simplify_path ( ) const |
|
split ( String delimiter="", bool allow_empty=true, int maxsplit=0 ) const |
|
split_floats ( String delimiter, bool allow_empty=true ) const |
|
strip_edges ( bool left=true, bool right=true ) const |
|
strip_escapes ( ) const |
|
to_ascii_buffer ( ) const |
|
to_camel_case ( ) const |
|
to_float ( ) const |
|
to_int ( ) const |
|
to_lower ( ) const |
|
to_pascal_case ( ) const |
|
to_snake_case ( ) const |
|
to_upper ( ) const |
|
to_utf16_buffer ( ) const |
|
to_utf32_buffer ( ) const |
|
to_utf8_buffer ( ) const |
|
trim_prefix ( String prefix ) const |
|
trim_suffix ( String suffix ) const |
|
unicode_at ( int at ) const |
|
uri_decode ( ) const |
|
uri_encode ( ) const |
|
validate_filename ( ) const |
|
validate_node_name ( ) const |
|
xml_escape ( bool escape_quotes=false ) const |
|
xml_unescape ( ) const |
Operators¶
operator != ( String right ) |
|
operator != ( StringName right ) |
|
operator % ( Variant right ) |
|
operator + ( String right ) |
|
operator + ( StringName right ) |
|
operator < ( StringName right ) |
|
operator <= ( StringName right ) |
|
operator == ( String right ) |
|
operator == ( StringName right ) |
|
operator > ( StringName right ) |
|
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
GD.Print("101".BinToInt()); // Prints 5
GD.Print("0b101".BinToInt()); // Prints 5
GD.Print("-0b10".BinToInt()); // 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"
"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
GD.Print("Node".Contains("de")); // Prints true
GD.Print("team".Contains("I")); // 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
GD.Print("Team".Find("I")); // Prints -1
GD.Print("Potato".Find("t")); // Prints 2
GD.Print("Potato".Find("t", 3)); // Prints 4
GD.Print("Potato".Find("t", 5)); // Prints -1
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.