- github_url
hide
A built-in type for strings.
classref-introduction-group
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
(countn<class_String_method_countn>
, findn<class_String_method_findn>
, replacen<class_String_method_replacen>
, etc.) are case-insensitive (they make no distinction between uppercase and lowercase letters). Method variations prefixed with r
(rfind<class_String_method_rfind>
, rsplit<class_String_method_rsplit>
, etc.) are reversed, and start from the end of the string, instead of the beginning.
Note: In a boolean context, a string will evaluate to false
if it is empty (""
). Otherwise, a string will always evaluate to true
. The not
operator cannot be used. Instead, is_empty<class_String_method_is_empty>
should be used to check for empty strings.
Note
There are notable differences when using this API with C#. See doc_c_sharp_differences
for more information.
classref-introduction-group
GDScript format strings <../tutorials/scripting/gdscript/gdscript_format_string>
classref-reftable-group
String<class_String> |
String<class_String_constructor_String> ( ) |
String<class_String> |
String<class_String_constructor_String> ( String<class_String> from ) |
String<class_String> |
String<class_String_constructor_String> ( NodePath<class_NodePath> from ) |
String<class_String> |
String<class_String_constructor_String> ( StringName<class_StringName> from ) |
classref-reftable-group
bool<class_bool> |
begins_with<class_String_method_begins_with> ( String<class_String> text ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedStringArray<class_PackedStringArray> |
bigrams<class_String_method_bigrams> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
bin_to_int<class_String_method_bin_to_int> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
c_escape<class_String_method_c_escape> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
c_unescape<class_String_method_c_unescape> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
capitalize<class_String_method_capitalize> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
casecmp_to<class_String_method_casecmp_to> ( String<class_String> to ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
chr<class_String_method_chr> ( int<class_int> char ) static (This method doesn't need an instance to be called, so it can be called directly using the class name.) |
bool<class_bool> |
contains<class_String_method_contains> ( String<class_String> what ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
count<class_String_method_count> ( String<class_String> what, int<class_int> from=0, int<class_int> to=0 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
countn<class_String_method_countn> ( String<class_String> what, int<class_int> from=0, int<class_int> to=0 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
dedent<class_String_method_dedent> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
ends_with<class_String_method_ends_with> ( String<class_String> text ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
erase<class_String_method_erase> ( int<class_int> position, int<class_int> chars=1 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
find<class_String_method_find> ( String<class_String> what, int<class_int> from=0 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
findn<class_String_method_findn> ( String<class_String> what, int<class_int> from=0 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
format<class_String_method_format> ( Variant<class_Variant> values, String<class_String> placeholder="{_}" ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
get_base_dir<class_String_method_get_base_dir> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
get_basename<class_String_method_get_basename> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
get_extension<class_String_method_get_extension> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
get_file<class_String_method_get_file> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
get_slice<class_String_method_get_slice> ( String<class_String> delimiter, int<class_int> slice ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
get_slice_count<class_String_method_get_slice_count> ( String<class_String> delimiter ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
get_slicec<class_String_method_get_slicec> ( int<class_int> delimiter, int<class_int> slice ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
hash<class_String_method_hash> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedByteArray<class_PackedByteArray> |
hex_decode<class_String_method_hex_decode> ( *)* const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
hex_to_int<class_String_method_hex_to_int> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
humanize_size<class_String_method_humanize_size> ( int<class_int> size ) static (This method doesn't need an instance to be called, so it can be called directly using the class name.) |
String<class_String> |
indent<class_String_method_indent> ( String<class_String> prefix ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
insert<class_String_method_insert> ( int<class_int> position, String<class_String> what ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
is_absolute_path<class_String_method_is_absolute_path> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
is_empty<class_String_method_is_empty> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
is_relative_path<class_String_method_is_relative_path> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
is_subsequence_of<class_String_method_is_subsequence_of> ( String<class_String> text ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
is_subsequence_ofn<class_String_method_is_subsequence_ofn> ( String<class_String> text ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
is_valid_filename<class_String_method_is_valid_filename> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
is_valid_float<class_String_method_is_valid_float> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
is_valid_hex_number<class_String_method_is_valid_hex_number> ( bool<class_bool> with_prefix=false ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
is_valid_html_color<class_String_method_is_valid_html_color> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
is_valid_identifier<class_String_method_is_valid_identifier> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
is_valid_int<class_String_method_is_valid_int> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
is_valid_ip_address<class_String_method_is_valid_ip_address> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
join<class_String_method_join> ( PackedStringArray<class_PackedStringArray> parts ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
json_escape<class_String_method_json_escape> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
left<class_String_method_left> ( int<class_int> length ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
length<class_String_method_length> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
lpad<class_String_method_lpad> ( int<class_int> min_length, String<class_String> character=" " ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
lstrip<class_String_method_lstrip> ( String<class_String> chars ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
match<class_String_method_match> ( String<class_String> expr ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
bool<class_bool> |
matchn<class_String_method_matchn> ( String<class_String> expr ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedByteArray<class_PackedByteArray> |
md5_buffer<class_String_method_md5_buffer> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
md5_text<class_String_method_md5_text> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
naturalcasecmp_to<class_String_method_naturalcasecmp_to> *(* String<class_String> to ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
naturalnocasecmp_to<class_String_method_naturalnocasecmp_to> ( String<class_String> to ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
nocasecmp_to<class_String_method_nocasecmp_to> ( String<class_String> to ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
num<class_String_method_num> ( float<class_float> number, int<class_int> decimals=-1 ) static (This method doesn't need an instance to be called, so it can be called directly using the class name.) |
String<class_String> |
num_int64<class_String_method_num_int64> ( int<class_int> number, int<class_int> base=10, bool<class_bool> capitalize_hex=false ) static (This method doesn't need an instance to be called, so it can be called directly using the class name.) |
String<class_String> |
num_scientific<class_String_method_num_scientific> ( float<class_float> number ) static (This method doesn't need an instance to be called, so it can be called directly using the class name.) |
String<class_String> |
num_uint64<class_String_method_num_uint64> ( int<class_int> number, int<class_int> base=10, bool<class_bool> capitalize_hex=false ) static (This method doesn't need an instance to be called, so it can be called directly using the class name.) |
String<class_String> |
pad_decimals<class_String_method_pad_decimals> ( int<class_int> digits ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
pad_zeros<class_String_method_pad_zeros> ( int<class_int> digits ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
path_join<class_String_method_path_join> ( String<class_String> file ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
repeat<class_String_method_repeat> ( int<class_int> count ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
replace<class_String_method_replace> ( String<class_String> what, String<class_String> forwhat ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
replacen<class_String_method_replacen> ( String<class_String> what, String<class_String> forwhat ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
reverse<class_String_method_reverse> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
rfind<class_String_method_rfind> ( String<class_String> what, int<class_int> from=-1 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
rfindn<class_String_method_rfindn> ( String<class_String> what, int<class_int> from=-1 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
right<class_String_method_right> ( int<class_int> length ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
rpad<class_String_method_rpad> ( int<class_int> min_length, String<class_String> character=" " ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedStringArray<class_PackedStringArray> |
rsplit<class_String_method_rsplit> ( String<class_String> delimiter="", bool<class_bool> allow_empty=true, int<class_int> maxsplit=0 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
rstrip<class_String_method_rstrip> ( String<class_String> chars ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedByteArray<class_PackedByteArray> |
sha1_buffer<class_String_method_sha1_buffer> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
sha1_text<class_String_method_sha1_text> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedByteArray<class_PackedByteArray> |
sha256_buffer<class_String_method_sha256_buffer> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
sha256_text<class_String_method_sha256_text> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
float<class_float> |
similarity<class_String_method_similarity> ( String<class_String> text ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
simplify_path<class_String_method_simplify_path> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedStringArray<class_PackedStringArray> |
split<class_String_method_split> ( String<class_String> delimiter="", bool<class_bool> allow_empty=true, int<class_int> maxsplit=0 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedFloat64Array<class_PackedFloat64Array> |
split_floats<class_String_method_split_floats> ( String<class_String> delimiter, bool<class_bool> allow_empty=true ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
strip_edges<class_String_method_strip_edges> ( bool<class_bool> left=true, bool<class_bool> right=true ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
strip_escapes<class_String_method_strip_escapes> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
substr<class_String_method_substr> ( int<class_int> from, int<class_int> len=-1 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedByteArray<class_PackedByteArray> |
to_ascii_buffer<class_String_method_to_ascii_buffer> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
to_camel_case<class_String_method_to_camel_case> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
float<class_float> |
to_float<class_String_method_to_float> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
to_int<class_String_method_to_int> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
to_lower<class_String_method_to_lower> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
to_pascal_case<class_String_method_to_pascal_case> ( *)* const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
to_snake_case<class_String_method_to_snake_case> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
to_upper<class_String_method_to_upper> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedByteArray<class_PackedByteArray> |
to_utf8_buffer<class_String_method_to_utf8_buffer> ( *)* const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedByteArray<class_PackedByteArray> |
to_utf16_buffer<class_String_method_to_utf16_buffer> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedByteArray<class_PackedByteArray> |
to_utf32_buffer<class_String_method_to_utf32_buffer> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
PackedByteArray<class_PackedByteArray> |
to_wchar_buffer<class_String_method_to_wchar_buffer> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
trim_prefix<class_String_method_trim_prefix> ( String<class_String> prefix ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
trim_suffix<class_String_method_trim_suffix> ( String<class_String> suffix ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
int<class_int> |
unicode_at<class_String_method_unicode_at> ( int<class_int> at ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
uri_decode<class_String_method_uri_decode> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
uri_encode<class_String_method_uri_encode> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
validate_filename<class_String_method_validate_filename> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
validate_node_name<class_String_method_validate_node_name> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
xml_escape<class_String_method_xml_escape> ( bool<class_bool> escape_quotes=false ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
String<class_String> |
xml_unescape<class_String_method_xml_unescape> ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.) |
classref-reftable-group
bool<class_bool> |
operator !=<class_String_operator_neq_String> ( String<class_String> right ) |
bool<class_bool> |
operator !=<class_String_operator_neq_StringName> ( StringName<class_StringName> right ) |
String<class_String> |
operator %<class_String_operator_mod_Variant> ( Variant<class_Variant> right ) |
String<class_String> |
operator +<class_String_operator_sum_String> ( String<class_String> right ) |
String<class_String> |
operator +<class_String_operator_sum_StringName> ( StringName<class_StringName> right ) |
bool<class_bool> |
operator \<<class_String_operator_lt_String> ( String<class_String> right ) |
bool<class_bool> |
operator \<=<class_String_operator_lte_String> ( String<class_String> right ) |
bool<class_bool> |
operator ==<class_String_operator_eq_String> ( String<class_String> right ) |
bool<class_bool> |
operator ==<class_String_operator_eq_StringName> ( StringName<class_StringName> right ) |
bool<class_bool> |
operator ><class_String_operator_gt_String> ( String<class_String> right ) |
bool<class_bool> |
operator >=<class_String_operator_gte_String> ( String<class_String> right ) |
String<class_String> |
operator []<class_String_operator_idx_int> ( int<class_int> index ) |
classref-section-separator
classref-descriptions-group
classref-constructor
String<class_String>
String ( )
Constructs an empty String (""
).
classref-item-separator
classref-constructor
String<class_String>
String ( String<class_String>
from )
Constructs a String as a copy of the given String.
classref-item-separator
classref-constructor
String<class_String>
String ( NodePath<class_NodePath>
from )
Constructs a new String from the given NodePath<class_NodePath>
.
classref-item-separator
classref-constructor
String<class_String>
String ( StringName<class_StringName>
from )
Constructs a new String from the given StringName<class_StringName>
.
classref-section-separator
classref-descriptions-group
classref-method
bool<class_bool>
begins_with ( String<class_String>
text ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns true
if the string begins with the given text
. See also ends_with<class_String_method_ends_with>
.
classref-item-separator
classref-method
PackedStringArray<class_PackedStringArray>
bigrams ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns an array containing the bigrams (pairs of consecutive characters) of this string.
print("Get up!".bigrams()) # Prints ["Ge", "et", "t ", " u", "up", "p!"]
classref-item-separator
classref-method
int<class_int>
bin_to_int ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Converts the string representing a binary number into an int<class_int>
. The string may optionally be prefixed with "0b"
, and an additional -
prefix for negative numbers.
gdscript
print("101".bin_to_int()) # Prints 5 print("0b101".bin_to_int()) # Prints 5 print("-0b10".bin_to_int()) # Prints -2
csharp
GD.Print("101".BinToInt()); // Prints 5 GD.Print("0b101".BinToInt()); // Prints 5 GD.Print("-0b10".BinToInt()); // Prints -2
classref-item-separator
classref-method
String<class_String>
c_escape ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns a copy of the string with special characters escaped using the C language standard.
classref-item-separator
classref-method
String<class_String>
c_unescape ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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.
classref-item-separator
classref-method
String<class_String>
capitalize ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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.
gdscript
"move_local_x".capitalize() # Returns "Move Local X" "sceneFile_path".capitalize() # Returns "Scene File Path"
csharp
"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.
classref-item-separator
classref-method
int<class_int>
casecmp_to ( String<class_String>
to ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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<class_bool>
result from a string comparison, use the ==
operator instead. See also nocasecmp_to<class_String_method_nocasecmp_to>
, naturalcasecmp_to<class_String_method_naturalcasecmp_to>
, and naturalnocasecmp_to<class_String_method_naturalnocasecmp_to>
.
classref-item-separator
classref-method
String<class_String>
chr ( int<class_int>
char ) static (This method doesn't need an instance to be called, so it can be called directly using the class name.)
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)
classref-item-separator
classref-method
bool<class_bool>
contains ( String<class_String>
what ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns true
if the string contains what
. In GDScript, this corresponds to the in
operator.
gdscript
print("Node".contains("de")) # Prints true print("team".contains("I")) # Prints false print("I" in "team") # Prints false
csharp
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<class_String_method_find>
.
classref-item-separator
classref-method
int<class_int>
count ( String<class_String>
what, int<class_int>
from=0, int<class_int>
to=0 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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.
classref-item-separator
classref-method
int<class_int>
countn ( String<class_String>
what, int<class_int>
from=0, int<class_int>
to=0 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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.
classref-item-separator
classref-method
String<class_String>
dedent ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns a copy of the string with indentation (leading tabs and spaces) removed. See also indent<class_String_method_indent>
to add indentation.
classref-item-separator
classref-method
bool<class_bool>
ends_with ( String<class_String>
text ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns true
if the string ends with the given text
. See also begins_with<class_String_method_begins_with>
.
classref-item-separator
classref-method
String<class_String>
erase ( int<class_int>
position, int<class_int>
chars=1 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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
.
classref-item-separator
classref-method
int<class_int>
find ( String<class_String>
what, int<class_int>
from=0 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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.
gdscript
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
csharp
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<class_String_method_contains>
. In GDScript, you may also use the in
operator.
classref-item-separator
classref-method
int<class_int>
findn ( String<class_String>
what, int<class_int>
from=0 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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.
classref-item-separator
classref-method
String<class_String>
format ( Variant<class_Variant>
values, String<class_String>
placeholder="{_}" ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Formats the string by replacing all occurrences of placeholder
with the elements of values
.
values
can be a Dictionary<class_Dictionary>
or an Array<class_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<class_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 <../tutorials/scripting/gdscript/gdscript_format_string>
tutorial.
Note: In C#, it's recommended to interpolate strings with "$", instead.
classref-item-separator
classref-method
String<class_String>
get_base_dir ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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"
classref-item-separator
classref-method
String<class_String>
get_basename ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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"
classref-item-separator
classref-method
String<class_String>
get_extension ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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 ""
classref-item-separator
classref-method
String<class_String>
get_file ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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"
classref-item-separator
classref-method
String<class_String>
get_slice ( String<class_String>
delimiter, int<class_int>
slice ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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 split<class_String_method_split>
, if you only need one substring.
Example:
print("i/am/example/hi".get_slice("/", 2)) # Prints "example"
classref-item-separator
classref-method
int<class_int>
get_slice_count ( String<class_String>
delimiter ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the total number of slices when the string is split with the given delimiter
(see split<class_String_method_split>
).
classref-item-separator
classref-method
String<class_String>
get_slicec ( int<class_int>
delimiter, int<class_int>
slice ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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 split<class_String_method_split>
, if you only need one substring.
classref-item-separator
classref-method
int<class_int>
hash ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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 countrary, strings with different hash values are guaranteed to be different.
classref-item-separator
classref-method
PackedByteArray<class_PackedByteArray>
hex_decode ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Decodes a hexadecimal string as a PackedByteArray<class_PackedByteArray>
.
gdscript
var text = "hello world" var encoded = text.to_utf8_buffer().hex_encode() # outputs "68656c6c6f20776f726c64" print(buf.hex_decode().get_string_from_utf8())
csharp
var text = "hello world"; var encoded = text.ToUtf8Buffer().HexEncode(); // outputs "68656c6c6f20776f726c64" GD.Print(buf.HexDecode().GetStringFromUtf8());
classref-item-separator
classref-method
int<class_int>
hex_to_int ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Converts the string representing a hexadecimal number into an int<class_int>
. The string may be optionally prefixed with "0x"
, and an additional -
prefix for negative numbers.
gdscript
print("0xff".hex_to_int()) # Prints 255 print("ab".hex_to_int()) # Prints 171
csharp
GD.Print("0xff".HexToInt()); // Prints 255 GD.Print("ab".HexToInt()); // Prints 171
classref-item-separator
classref-method
String<class_String>
humanize_size ( int<class_int>
size ) static (This method doesn't need an instance to be called, so it can be called directly using the class name.)
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"
.
classref-item-separator
classref-method
String<class_String>
indent ( String<class_String>
prefix ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Indents every line of the string with the given prefix
. Empty lines are not indented. See also dedent<class_String_method_dedent>
to remove indentation.
For example, the string can be indented with two tabulations using "\t\t"
, or four spaces using " "
.
classref-item-separator
classref-method
String<class_String>
insert ( int<class_int>
position, String<class_String>
what ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Inserts what
at the given position
in the string.
classref-item-separator
classref-method
bool<class_bool>
is_absolute_path ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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<class_String_method_is_relative_path>
.
This includes all paths starting with "res://"
, "user://"
, "C:\"
, "/"
, etc.
classref-item-separator
classref-method
bool<class_bool>
is_empty ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns true
if the string's length is 0
(""
). See also length<class_String_method_length>
.
classref-item-separator
classref-method
bool<class_bool>
is_relative_path ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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<class_Node>
(if the string is derived from a NodePath<class_NodePath>
), and may sometimes be prefixed with "./"
. This method is the opposite of is_absolute_path<class_String_method_is_absolute_path>
.
classref-item-separator
classref-method
bool<class_bool>
is_subsequence_of ( String<class_String>
text ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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
classref-item-separator
classref-method
bool<class_bool>
is_subsequence_ofn ( String<class_String>
text ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns true
if all characters of this string can be found in text
in their original order, ignoring case.
classref-item-separator
classref-method
bool<class_bool>
is_valid_filename ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns true
if this string does not contain characters that are not allowed in file names (:
/
\
?
*
"
|
%
<
>
).
classref-item-separator
classref-method
bool<class_bool>
is_valid_float ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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<class_String_method_is_valid_int>
). See also to_float<class_String_method_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
classref-item-separator
classref-method
bool<class_bool>
is_valid_hex_number ( bool<class_bool>
with_prefix=false ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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
classref-item-separator
classref-method
bool<class_bool>
is_valid_html_color ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns true
if this string is a valid color in hexadecimal HTML notation. The string must be a hexadecimal value (see is_valid_hex_number<class_String_method_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<class_Color_method_html>
.
classref-item-separator
classref-method
bool<class_bool>
is_valid_identifier ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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
classref-item-separator
classref-method
bool<class_bool>
is_valid_int ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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<class_String_method_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
classref-item-separator
classref-method
bool<class_bool>
is_valid_ip_address ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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.
classref-item-separator
classref-method
String<class_String>
join ( PackedStringArray<class_PackedStringArray>
parts ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the concatenation of parts
' elements, with each element separated by the string calling this method. This method is the opposite of split<class_String_method_split>
.
Example:
gdscript
var fruits = ["Apple", "Orange", "Pear", "Kiwi"]
print(", ".join(fruits)) # Prints "Apple, Orange, Pear, Kiwi" print("---".join(fruits)) # Prints "Apple---Orange---Pear---Kiwi"
csharp
var fruits = new string[] {"Apple", "Orange", "Pear", "Kiwi"};
// In C#, this method is static. GD.Print(string.Join(", ", fruits)); // Prints "Apple, Orange, Pear, Kiwi" GD.Print(string.Join("---", fruits)); // Prints "Apple---Orange---Pear---Kiwi"
classref-item-separator
classref-method
String<class_String>
json_escape ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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<class_String_method_c_unescape>
to unescape the string, if necessary.
classref-item-separator
classref-method
String<class_String>
left ( int<class_int>
length ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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"
classref-item-separator
classref-method
int<class_int>
length ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the number of characters in the string. Empty strings (""
) always return 0
. See also is_empty<class_String_method_is_empty>
.
classref-item-separator
classref-method
String<class_String>
lpad ( int<class_int>
min_length, String<class_String>
character=" " ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Formats the string to be at least min_length
long by adding character
s to the left of the string, if necessary. See also rpad<class_String_method_rpad>
.
classref-item-separator
classref-method
String<class_String>
lstrip ( String<class_String>
chars ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Removes a set of characters defined in chars
from the string's beginning. See also rstrip<class_String_method_rstrip>
.
Note: chars
is not a prefix. Use trim_prefix<class_String_method_trim_prefix>
to remove a single prefix, rather than a set of characters.
classref-item-separator
classref-method
bool<class_bool>
match ( String<class_String>
expr ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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
.
classref-item-separator
classref-method
bool<class_bool>
matchn ( String<class_String>
expr ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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
.
classref-item-separator
classref-method
PackedByteArray<class_PackedByteArray>
md5_buffer ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the MD5 hash of the string as a PackedByteArray<class_PackedByteArray>
.
classref-item-separator
classref-method
String<class_String>
md5_text ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the MD5 hash of the string as another String.
classref-item-separator
classref-method
int<class_int>
naturalcasecmp_to ( String<class_String>
to ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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<class_bool>
result from a string comparison, use the ==
operator instead. See also naturalnocasecmp_to<class_String_method_naturalnocasecmp_to>
, nocasecmp_to<class_String_method_nocasecmp_to>
, and casecmp_to<class_String_method_casecmp_to>
.
classref-item-separator
classref-method
int<class_int>
naturalnocasecmp_to ( String<class_String>
to ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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<class_bool>
result from a string comparison, use the ==
operator instead. See also naturalcasecmp_to<class_String_method_naturalcasecmp_to>
, nocasecmp_to<class_String_method_nocasecmp_to>
, and casecmp_to<class_String_method_casecmp_to>
.
classref-item-separator
classref-method
int<class_int>
nocasecmp_to ( String<class_String>
to ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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<class_bool>
result from a string comparison, use the ==
operator instead. See also casecmp_to<class_String_method_casecmp_to>
, naturalcasecmp_to<class_String_method_naturalcasecmp_to>
, and naturalnocasecmp_to<class_String_method_naturalnocasecmp_to>
.
classref-item-separator
classref-method
String<class_String>
num ( float<class_float>
number, int<class_int>
decimals=-1 ) static (This method doesn't need an instance to be called, so it can be called directly using the class name.)
Converts a float<class_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.
Example:
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"
classref-item-separator
classref-method
String<class_String>
num_int64 ( int<class_int>
number, int<class_int>
base=10, bool<class_bool>
capitalize_hex=false ) static (This method doesn't need an instance to be called, so it can be called directly using the class name.)
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.
classref-item-separator
classref-method
String<class_String>
num_scientific ( float<class_float>
number ) static (This method doesn't need an instance to be called, so it can be called directly using the class name.)
Converts the given number
to a string representation, in scientific notation.
gdscript
var n = -5.2e8 print(n) # Prints -520000000 print(String.NumScientific(n)) # Prints -5.2e+08
csharp
// This method is not implemented in C#. // Use string.ToString() with "e" to achieve similar results. var n = -5.2e8f; GD.Print(n); // Prints -520000000 GD.Print(n.ToString("e1")); // Prints -5.2e+008
Note: In C#, this method is not implemented. To achieve similar results, see C#'s Standard numeric format strings
classref-item-separator
classref-method
String<class_String>
num_uint64 ( int<class_int>
number, int<class_int>
base=10, bool<class_bool>
capitalize_hex=false ) static (This method doesn't need an instance to be called, so it can be called directly using the class name.)
Converts the given unsigned int<class_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.
classref-item-separator
classref-method
String<class_String>
pad_decimals ( int<class_int>
digits ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Formats the string representing a number to have an exact number of digits
after the decimal point.
classref-item-separator
classref-method
String<class_String>
pad_zeros ( int<class_int>
digits ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Formats the string representing a number to have an exact number of digits
before the decimal point.
classref-item-separator
classref-method
String<class_String>
path_join ( String<class_String>
file ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Concatenates file
at the end of the string as a subpath, adding /
if necessary.
Example: "this/is".path_join("path") == "this/is/path"
.
classref-item-separator
classref-method
String<class_String>
repeat ( int<class_int>
count ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Repeats this string a number of times. count
needs to be greater than 0
. Otherwise, returns an empty string.
classref-item-separator
classref-method
String<class_String>
replace ( String<class_String>
what, String<class_String>
forwhat ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Replaces all occurrences of what
inside the string with the given forwhat
.
classref-item-separator
classref-method
String<class_String>
replacen ( String<class_String>
what, String<class_String>
forwhat ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Replaces all case-insensitive occurrences of what
inside the string with the given forwhat
.
classref-item-separator
classref-method
String<class_String>
reverse ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the copy of this string in reverse order.
classref-item-separator
classref-method
int<class_int>
rfind ( String<class_String>
what, int<class_int>
from=-1 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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 find<class_String_method_find>
.
classref-item-separator
classref-method
int<class_int>
rfindn ( String<class_String>
what, int<class_int>
from=-1 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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 findn<class_String_method_findn>
.
classref-item-separator
classref-method
String<class_String>
right ( int<class_int>
length ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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!"
classref-item-separator
classref-method
String<class_String>
rpad ( int<class_int>
min_length, String<class_String>
character=" " ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Formats the string to be at least min_length
long, by adding character
s to the right of the string, if necessary. See also lpad<class_String_method_lpad>
.
classref-item-separator
classref-method
PackedStringArray<class_PackedStringArray>
rsplit ( String<class_String>
delimiter="", bool<class_bool>
allow_empty=true, int<class_int>
maxsplit=0 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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 split<class_String_method_split>
.
Example:
gdscript
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"
csharp
// In C#, there is no String.RSplit() method.
classref-item-separator
classref-method
String<class_String>
rstrip ( String<class_String>
chars ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Removes a set of characters defined in chars
from the string's end. See also lstrip<class_String_method_lstrip>
.
Note: chars
is not a suffix. Use trim_suffix<class_String_method_trim_suffix>
to remove a single suffix, rather than a set of characters.
classref-item-separator
classref-method
PackedByteArray<class_PackedByteArray>
sha1_buffer ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the SHA-1 hash of the string as a PackedByteArray<class_PackedByteArray>
.
classref-item-separator
classref-method
String<class_String>
sha1_text ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the SHA-1 hash of the string as another String.
classref-item-separator
classref-method
PackedByteArray<class_PackedByteArray>
sha256_buffer ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the SHA-256 hash of the string as a PackedByteArray<class_PackedByteArray>
.
classref-item-separator
classref-method
String<class_String>
sha256_text ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the SHA-256 hash of the string as another String.
classref-item-separator
classref-method
float<class_float>
similarity ( String<class_String>
text ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the similarity index (Sorensen-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
classref-item-separator
classref-method
String<class_String>
simplify_path ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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"
classref-item-separator
classref-method
PackedStringArray<class_PackedStringArray>
split ( String<class_String>
delimiter="", bool<class_bool>
allow_empty=true, int<class_int>
maxsplit=0 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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 join<class_String_method_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.
Example:
gdscript
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"
csharp
// C#'s Split() does not support the maxsplit parameter. var someArray = "One,Two,Three".Split(",");
GD.Print(someArray[0]); // Prints "One" GD.Print(someArray[1]); // Prints "Two" GD.Print(someArray[2]); // Prints "Three"
Note: If you only need one substring from the array, consider using get_slice<class_String_method_get_slice>
which is faster. If you need to split strings with more complex rules, use the RegEx<class_RegEx>
class instead.
classref-item-separator
classref-method
PackedFloat64Array<class_PackedFloat64Array>
split_floats ( String<class_String>
delimiter, bool<class_bool>
allow_empty=true ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Splits the string into floats by using a delimiter
and returns a PackedFloat64Array<class_PackedFloat64Array>
.
If allow_empty
is false
, empty or invalid float<class_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]
classref-item-separator
classref-method
String<class_String>
strip_edges ( bool<class_bool>
left=true, bool<class_bool>
right=true ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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.
classref-item-separator
classref-method
String<class_String>
strip_escapes ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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.
classref-item-separator
classref-method
String<class_String>
substr ( int<class_int>
from, int<class_int>
len=-1 ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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.
classref-item-separator
classref-method
PackedByteArray<class_PackedByteArray>
to_ascii_buffer ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Converts the string to an ASCII/Latin-1 encoded PackedByteArray<class_PackedByteArray>
. This method is slightly faster than to_utf8_buffer<class_String_method_to_utf8_buffer>
, but replaces all unsupported characters with spaces. This is the inverse of PackedByteArray.get_string_from_ascii<class_PackedByteArray_method_get_string_from_ascii>
.
classref-item-separator
classref-method
String<class_String>
to_camel_case ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the string converted to camelCase
.
classref-item-separator
classref-method
float<class_float>
to_float ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Converts the string representing a decimal number into a float<class_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<class_String_method_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
classref-item-separator
classref-method
int<class_int>
to_int ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Converts the string representing an integer number into an int<class_int>
. This method removes any non-number character and stops at the first decimal point (.
). See also is_valid_int<class_String_method_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
classref-item-separator
classref-method
String<class_String>
to_lower ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the string converted to lowercase.
classref-item-separator
classref-method
String<class_String>
to_pascal_case ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the string converted to PascalCase
.
classref-item-separator
classref-method
String<class_String>
to_snake_case ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the string converted to snake_case
.
classref-item-separator
classref-method
String<class_String>
to_upper ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the string converted to uppercase.
classref-item-separator
classref-method
PackedByteArray<class_PackedByteArray>
to_utf8_buffer ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Converts the string to a UTF-8 encoded PackedByteArray<class_PackedByteArray>
. This method is slightly slower than to_ascii_buffer<class_String_method_to_ascii_buffer>
, but supports all UTF-8 characters. For most cases, prefer using this method. This is the inverse of PackedByteArray.get_string_from_utf8<class_PackedByteArray_method_get_string_from_utf8>
.
classref-item-separator
classref-method
PackedByteArray<class_PackedByteArray>
to_utf16_buffer ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Converts the string to a UTF-16 encoded PackedByteArray<class_PackedByteArray>
. This is the inverse of PackedByteArray.get_string_from_utf16<class_PackedByteArray_method_get_string_from_utf16>
.
classref-item-separator
classref-method
PackedByteArray<class_PackedByteArray>
to_utf32_buffer ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Converts the string to a UTF-32 encoded PackedByteArray<class_PackedByteArray>
. This is the inverse of PackedByteArray.get_string_from_utf32<class_PackedByteArray_method_get_string_from_utf32>
.
classref-item-separator
classref-method
PackedByteArray<class_PackedByteArray>
to_wchar_buffer ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Converts the string to a wide character (wchar_t
, UTF-16 on Windows, UTF-32 on other platforms) encoded PackedByteArray<class_PackedByteArray>
. This is the inverse of PackedByteArray.get_string_from_wchar<class_PackedByteArray_method_get_string_from_wchar>
.
classref-item-separator
classref-method
String<class_String>
trim_prefix ( String<class_String>
prefix ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Removes the given prefix
from the start of the string, or returns the string unchanged.
classref-item-separator
classref-method
String<class_String>
trim_suffix ( String<class_String>
suffix ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Removes the given suffix
from the end of the string, or returns the string unchanged.
classref-item-separator
classref-method
int<class_int>
unicode_at ( int<class_int>
at ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns the character code at position at
.
classref-item-separator
classref-method
String<class_String>
uri_decode ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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<class_String_method_uri_encode>
.
gdscript
var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs" print(url.uri_decode()) # Prints "$DOCS_URL/?highlight=Godot Engine:docs"
csharp
var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs" GD.Print(url.URIDecode()) // Prints "$DOCS_URL/?highlight=Godot Engine:docs"
classref-item-separator
classref-method
String<class_String>
uri_encode ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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<class_String_method_uri_decode>
.
gdscript
var prefix = "$DOCS_URL/?highlight=" var url = prefix + "Godot Engine:docs".uri_encode()
print(url) # Prints "$DOCS_URL/?highlight=Godot%20Engine%3%docs"
csharp
var prefix = "$DOCS_URL/?highlight="; var url = prefix + "Godot Engine:docs".URIEncode();
GD.Print(url); // Prints "$DOCS_URL/?highlight=Godot%20Engine%3%docs"
classref-item-separator
classref-method
String<class_String>
validate_filename ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns a copy of the string with all characters that are not allowed in is_valid_filename<class_String_method_is_valid_filename>
replaced with underscores.
classref-item-separator
classref-method
String<class_String>
validate_node_name ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns a copy of the string with all characters that are not allowed in Node.name<class_Node_property_name>
(.
:
@
/
"
%
) replaced with underscores.
classref-item-separator
classref-method
String<class_String>
xml_escape ( bool<class_bool>
escape_quotes=false ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
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.
classref-item-separator
classref-method
String<class_String>
xml_unescape ( ) const (This method has no side effects. It doesn't modify any of the instance's member variables.)
Returns a copy of the string with escaped characters replaced by their meanings according to the XML standard.
classref-section-separator
classref-descriptions-group
classref-operator
bool<class_bool>
operator != ( String<class_String>
right )
Returns true
if both strings do not contain the same sequence of characters.
classref-item-separator
classref-operator
bool<class_bool>
operator != ( StringName<class_StringName>
right )
Returns true
if this String is not equivalent to the given StringName<class_StringName>
.
classref-item-separator
classref-operator
String<class_String>
operator % ( Variant<class_Variant>
right )
Formats the String, replacing the placeholders with one or more parameters. To pass multiple parameters, right
needs to be an Array<class_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 <../tutorials/scripting/gdscript/gdscript_format_string>
tutorial.
Note: In C#, this operator is not available. Instead, see how to interpolate strings with "$".
classref-item-separator
classref-operator
String<class_String>
operator + ( String<class_String>
right )
Appends right
at the end of this String, also known as a string concatenation.
classref-item-separator
classref-operator
String<class_String>
operator + ( StringName<class_StringName>
right )
Appends right
at the end of this String, returning a String. This is also known as a string concatenation.
classref-item-separator
classref-operator
bool<class_bool>
operator < ( String<class_String>
right )
Returns true
if the left String comes before right
in Unicode order, which roughly matches the alphabetical order. Useful for sorting.
classref-item-separator
classref-operator
bool<class_bool>
operator <= ( String<class_String>
right )
Returns true
if the left String comes before right
in Unicode order, which roughly matches the alphabetical order, or if both are equal.
classref-item-separator
classref-operator
bool<class_bool>
operator == ( String<class_String>
right )
Returns true
if both strings contain the same sequence of characters.
classref-item-separator
classref-operator
bool<class_bool>
operator == ( StringName<class_StringName>
right )
Returns true
if this String is equivalent to the given StringName<class_StringName>
.
classref-item-separator
classref-operator
bool<class_bool>
operator > ( String<class_String>
right )
Returns true
if the left String comes after right
in Unicode order, which roughly matches the alphabetical order. Useful for sorting.
classref-item-separator
classref-operator
bool<class_bool>
operator >= ( String<class_String>
right )
Returns true
if the left String comes after right
in Unicode order, which roughly matches the alphabetical order, or if both are equal.
classref-item-separator
classref-operator
String<class_String>
operator [] ( int<class_int>
index )
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.