Struct GString 

pub struct GString { /* private fields */ }

Godot’s reference counted string type.

This is the Rust binding of GDScript’s String type. It represents the native string class used within the Godot engine, and as such has different memory layout and characteristics than std::string::String.

GString uses copy-on-write semantics and is cheap to clone. Modifying a string may trigger a copy, if that instance shares its backing storage with other strings.

Note that GString is not immutable, but it offers a very limited set of write APIs. Most operations return new strings. In order to modify Godot strings, it’s often easiest to convert them to Rust strings, perform the modifications and convert back.

GString vs. String

When interfacing with the Godot engine API, you often have the choice between String and GString. In user-declared methods exposed to Godot through the #[func] attribute, both types can be used as parameters and return types, and conversions are done transparently. For auto-generated binding APIs in godot::classes, both parameters and return types are GString. Parameters are declared as impl AsArg<GString>, allowing you to be more flexible with arguments such as "some_string".

As a general guideline, use GString if:

• your strings are very large, so you can avoid copying them
• you need specific operations only available in Godot (e.g. sha256_text(), c_escape(), …)
• you primarily pass them between different Godot APIs, without string processing in user code

Use Rust’s String if:

• you need to modify the string
• you would like to decouple part of your code from Godot (e.g. independent game logic, standalone tests)
• you want a standard type for interoperability with third-party code (e.g. regex crate)
• you have a large number of method calls per string instance (which are more expensive due to indirectly calling into Godot)
• you need UTF-8 encoding (GString uses UTF-32)

Null bytes

Note that Godot ignores any bytes after a null-byte. This means that for instance "hello, world!" and "hello, world!\0 ignored by Godot" will be treated as the same string if converted to a GString.

All string types

Intended use case	String type
General purpose	GString
Interned names	StringName
Scene-node paths	NodePath

Godot docs

String (stable)

Implementations

impl GString

pub fn new() -> GString

Construct a new empty GString.

pub fn try_from_bytes( bytes: &[u8], encoding: Encoding, ) -> Result<GString, StringError>

Convert string from bytes with given encoding, returning Err on validation errors.

Intermediate NUL characters are not accepted in Godot and always return Err.

Some notes on the encodings:

• Latin-1: Since every byte is a valid Latin-1 character, no validation besides the NUL byte is performed. It is your responsibility to ensure that the input is meaningful under Latin-1.
• ASCII: Subset of Latin-1, which is additionally validated to be valid, non-NUL ASCII characters.
• UTF-8: The input is validated to be UTF-8.

Specifying incorrect encoding is safe, but may result in unintended string values.

pub fn try_from_cstr( cstr: &CStr, encoding: Encoding, ) -> Result<GString, StringError>

Convert string from C-string with given encoding, returning Err on validation errors.

Convenience function for try_from_bytes(); see its docs for more information.

pub fn len(&self) -> usize

Number of characters in the string.

Godot equivalent: length

pub fn hash_u32(&self) -> u32

Returns a 32-bit integer hash value representing the string.

pub fn chars(&self) -> &[char]

Gets the UTF-32 character slice from a GString.

impl GString

Manually-declared, shared methods between GString and StringName.

pub fn unicode_at(&self, index: usize) -> char

Returns the Unicode code point (“character”) at position index.

Panics (safeguards-balanced)

If index is out of bounds. In disengaged level, 0 is returned instead.

pub fn find(&self, what: impl AsArg<GString>) -> Option<usize>

Find first occurrence of what and return index, or None if not found.

Check find_ex() for all custom options.

pub fn find_ex<'s, 'w>( &'s self, what: impl AsArg<GString> + 'w, ) -> ExFind<'s, 'w>

Returns a builder for finding substrings, with various configuration options.

The builder struct offers methods to configure 3 dimensions, which map to different Godot functions in the back:

Method	Default behavior	Behavior after method call
r()	forward search (find*)	backward search (rfind*)
n()	case-sensitive search (*find)	case-insensitive search (*findn)
from(index)	search from beginning (or end if reverse)	search from specified index

Returns Some(index) of the first occurrence, or None if not found.

Example

To find the substring "O" in "Hello World", not considering case and starting from position 5, you can write:

let s = GString::from("Hello World");
if let Some(found) = s.find_ex("O").n().from(5).done() {
   do_sth_with_index(found)
}

This is equivalent to the following GDScript code:

var s: GString = "Hello World"
var found = s.findn("O", 5)
if found != -1:
    do_sth_with_index(found)

pub fn count( &self, what: impl AsArg<GString>, range: impl RangeBounds<usize>, ) -> usize

Count how many times what appears within range. Use .. for full string search.

pub fn countn( &self, what: impl AsArg<GString>, range: impl RangeBounds<usize>, ) -> usize

Count how many times what appears within range, case-insensitively. Use .. for full string search.

pub fn split(&self, delimiter: impl AsArg<GString>) -> PackedArray<GString>

Splits the string according to delimiter.

See split_ex() if you need further configuration.

pub fn split_ex<'s, 'w>( &'s self, delimiter: impl AsArg<GString> + 'w, ) -> ExSplit<'s, 'w>

Returns a builder that splits this string into substrings using delimiter.

If delimiter is an empty string, each substring will be a single character.

The builder struct offers methods to configure multiple dimensions. Note that rsplit in Godot is not useful without the maxsplit argument, so the two are combined in Rust as maxsplit_r.

Method	Default behavior	Behavior after method call
disallow_empty()	allows empty parts	empty parts are removed from result
maxsplit(n)	entire string is split	splits n times -> n+1 parts
maxsplit_r(n)	entire string is split	splits n times -> n+1 parts (start from back)

pub fn substr(&self, range: impl RangeBounds<usize>) -> GString

Returns a substring of this, as another GString.

pub fn get_slice( &self, delimiter: impl AsArg<GString>, slice: usize, ) -> Option<GString>

Splits the string using a string delimiter and returns the substring at index slice.

Returns the original string if delimiter does not occur in the string. Returns None if slice is out of bounds.

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

pub fn get_slicec(&self, delimiter: char, slice: usize) -> Option<GString>

Splits the string using a Unicode char delimiter and returns the substring at index slice.

Returns the original string if delimiter does not occur in the string. Returns None if slice is out of bounds.

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

pub fn get_slice_count(&self, delimiter: impl AsArg<GString>) -> usize

Returns the total number of slices, when the string is split with the given delimiter.

See also split() and get_slice().

pub fn erase(&self, range: impl RangeBounds<usize>) -> GString

Returns a copy of the string without the specified index range.

pub fn insert(&self, position: usize, what: impl AsArg<GString>) -> GString

Returns a copy of the string with an additional string inserted at the given position.

If the position is out of bounds, the string will be inserted at the end.

Consider using format() for more flexibility.

pub fn format(&self, array_or_dict: &Variant) -> GString

Format a string using substitutions from an array or dictionary.

See Godot’s String.format().

pub fn format_with_placeholder( &self, array_or_dict: &Variant, placeholder: impl AsArg<GString>, ) -> GString

Format a string using substitutions from an array or dictionary + custom placeholder.

See Godot’s String.format().

pub fn lpad(&self, min_length: usize, character: char) -> GString

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

Godot itself allows padding with multiple characters, but that behavior is not very useful, because min_length isn’t respected in that case. The parameter in Godot is even called character. In Rust, we directly expose char instead.

See also rpad().

pub fn rpad(&self, min_length: usize, character: char) -> GString

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

Godot itself allows padding with multiple characters, but that behavior is not very useful, because min_length isn’t respected in that case. The parameter in Godot is even called character. In Rust, we directly expose char instead.

See also lpad().

pub fn pad_decimals(&self, digits: usize) -> GString

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

pub fn pad_zeros(&self, digits: usize) -> GString

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

pub fn casecmp_to(&self, to: impl AsArg<GString>) -> Ordering

Case-sensitive, lexicographic comparison to another string.

Returns the Ordering relation of self towards to. Ordering is determined by the Unicode code points of each string, which roughly matches the alphabetical order.

See also nocasecmp_to(), naturalcasecmp_to(), filecasecmp_to().

pub fn nocasecmp_to(&self, to: impl AsArg<GString>) -> Ordering

Case-insensitive, lexicographic comparison to another string.

Returns the Ordering relation of self towards to. Ordering is determined by the Unicode code points of each string, which roughly matches the alphabetical order.

See also casecmp_to(), naturalcasecmp_to(), filecasecmp_to().

pub fn naturalcasecmp_to(&self, to: impl AsArg<GString>) -> Ordering

Case-sensitive, natural-order comparison to another string.

Returns the Ordering relation of self towards to. Ordering is 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 Ordering::Greater if this string is longer than the to string, or Ordering::Less if shorter.

See also casecmp_to(), naturalnocasecmp_to(), filecasecmp_to().

pub fn naturalnocasecmp_to(&self, to: impl AsArg<GString>) -> Ordering

Case-insensitive, natural-order comparison to another string.

Returns the Ordering relation of self towards to. Ordering is 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 Ordering::Greater if this string is longer than the to string, or Ordering::Less if shorter.

See also casecmp_to(), naturalcasecmp_to(), filecasecmp_to().

pub fn filecasecmp_to(&self, to: impl AsArg<GString>) -> Ordering

Available on since_api=4.3 only.

Case-sensitive, filename-oriented comparison to another string.

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

See also casecmp_to(), naturalcasecmp_to(), filenocasecmp_to().

pub fn filenocasecmp_to(&self, to: impl AsArg<GString>) -> Ordering

Available on since_api=4.3 only.

Case-insensitive, filename-oriented comparison to another string.

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

See also casecmp_to(), naturalcasecmp_to(), filecasecmp_to().

pub fn match_glob(&self, pattern: impl AsArg<GString>) -> bool

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.

Renamed from match because of collision with Rust keyword + possible confusion with String::matches() that can match regex.

pub fn matchn_glob(&self, pattern: impl AsArg<GString>) -> bool

Simple case-insensitive 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.

Renamed from matchn because of collision with Rust keyword + possible confusion with String::matches() that can match regex.

impl GString

pub fn begins_with(&self, text: impl AsArg<GString>) -> bool

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

pub fn ends_with(&self, text: impl AsArg<GString>) -> bool

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

pub fn is_subsequence_of(&self, text: impl AsArg<GString>) -> bool

Returns true if all characters of this string can be found in text in their original order. This is not the same as [method contains].

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

pub fn is_subsequence_ofn(&self, text: impl AsArg<GString>) -> bool

Returns true if all characters of this string can be found in text in their original order, ignoring case. This is not the same as [method containsn].

pub fn bigrams(&self) -> PackedArray<GString>

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

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

pub fn similarity(&self, text: impl AsArg<GString>) -> f64

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

print("ABC123".similarity("ABC123")) # Prints 1.0
print("ABC123".similarity("XYZ456")) # Prints 0.0
print("ABC123".similarity("123ABC")) # Prints 0.8
print("ABC123".similarity("abc123")) # Prints 0.4

pub fn replace( &self, what: impl AsArg<GString>, forwhat: impl AsArg<GString>, ) -> GString

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

pub fn replacen( &self, what: impl AsArg<GString>, forwhat: impl AsArg<GString>, ) -> GString

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

pub fn repeat(&self, count: i64) -> GString

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

pub fn reverse(&self) -> GString

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

pub fn capitalize(&self) -> GString

Changes the appearance of the string: replaces underscores (_) with spaces, adds spaces before uppercase letters in the middle of a word, converts all letters to lowercase, then converts the first one and each one following a space to uppercase.

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

pub fn to_camel_case(&self) -> GString

Returns the string converted to camelCase.

pub fn to_pascal_case(&self) -> GString

Returns the string converted to PascalCase.

pub fn to_snake_case(&self) -> GString

Returns the string converted to snake_case.

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

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

pub fn split_floats(&self, delimiter: impl AsArg<GString>) -> PackedArray<f64>

To set the default parameters, use split_floats_ex and its builder methods. See the book for detailed usage instructions. Splits the string into floats by using a delimiter and returns a PackedFloat64Array.

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

var a = "1,2,4.5".split_floats(",")         # a is [1.0, 2.0, 4.5]
var c = "1| ||4.5".split_floats("|")        # c is [1.0, 0.0, 0.0, 4.5]
var b = "1| ||4.5".split_floats("|", false) # b is [1.0, 4.5]

pub fn split_floats_ex<'ex>( &'ex self, delimiter: impl AsArg<GString> + 'ex, ) -> ExSplitFloats<'ex>

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

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

var a = "1,2,4.5".split_floats(",")         # a is [1.0, 2.0, 4.5]
var c = "1| ||4.5".split_floats("|")        # c is [1.0, 0.0, 0.0, 4.5]
var b = "1| ||4.5".split_floats("|", false) # b is [1.0, 4.5]

pub fn join(&self, parts: &PackedArray<GString>) -> GString

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

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

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

pub fn to_upper(&self) -> GString

Returns the string converted to UPPERCASE.

pub fn to_lower(&self) -> GString

Returns the string converted to lowercase.

pub fn left(&self, length: i64) -> GString

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"

pub fn right(&self, length: i64) -> GString

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!"

pub fn strip_edges(&self) -> GString

To set the default parameters, use strip_edges_ex and its builder methods. See the book for detailed usage instructions. 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.

pub fn strip_edges_ex<'ex>(&'ex self) -> ExStripEdges<'ex>

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.

pub fn strip_escapes(&self) -> GString

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.

pub fn lstrip(&self, chars: impl AsArg<GString>) -> GString

Removes a set of characters defined in chars from the string’s beginning. See also [method rstrip].

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

pub fn rstrip(&self, chars: impl AsArg<GString>) -> GString

Removes a set of characters defined in chars from the string’s end. See also [method lstrip].

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

pub fn get_extension(&self) -> GString

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 ""

pub fn get_basename(&self) -> GString

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"

pub fn path_join(&self, path: impl AsArg<GString>) -> GString

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

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

pub fn indent(&self, prefix: impl AsArg<GString>) -> GString

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

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

pub fn dedent(&self) -> GString

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

pub fn md5_text(&self) -> GString

Returns the MD5 hash of the string as another String.

pub fn sha1_text(&self) -> GString

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

pub fn sha256_text(&self) -> GString

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

pub fn md5_buffer(&self) -> PackedArray<u8>

Returns the MD5 hash of the string as a PackedByteArray.

pub fn sha1_buffer(&self) -> PackedArray<u8>

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

pub fn sha256_buffer(&self) -> PackedArray<u8>

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

pub fn is_empty(&self) -> bool

Returns true if the string’s length is 0 (""). See also [method length].

pub fn contains(&self, what: impl AsArg<GString>) -> bool

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 [method find]. See also [method containsn].

pub fn containsn(&self, what: impl AsArg<GString>) -> bool

Returns true if the string contains what, ignoring case.

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

pub fn is_absolute_path(&self) -> bool

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 [method is_relative_path].

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

pub fn is_relative_path(&self) -> bool

Returns true if the string is a path, and its starting point is dependent on context. The path could begin from the current directory, or the current Node (if the string is derived from a NodePath), and may sometimes be prefixed with "./". This method is the opposite of [method is_absolute_path].

pub fn simplify_path(&self) -> GString

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"

pub fn get_base_dir(&self) -> GString

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"

pub fn get_file(&self) -> GString

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"

pub fn xml_escape(&self) -> GString

To set the default parameters, use xml_escape_ex and its builder methods. See the book for detailed usage instructions. 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.

pub fn xml_escape_ex<'ex>(&'ex self) -> ExXmlEscape<'ex>

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.

pub fn xml_unescape(&self) -> GString

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

pub fn uri_encode(&self) -> GString

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 [method uri_decode].

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

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

pub fn uri_decode(&self) -> GString

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 [method uri_encode].

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

Note: This method decodes + as space.

pub fn c_escape(&self) -> GString

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

pub fn c_unescape(&self) -> GString

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.

pub fn json_escape(&self) -> GString

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

pub fn validate_node_name(&self) -> GString

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

pub fn validate_filename(&self) -> GString

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

pub fn is_valid_identifier(&self) -> bool

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

pub fn is_valid_int(&self) -> bool

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 [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

pub fn is_valid_float(&self) -> bool

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 [method is_valid_int]). See also [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

pub fn is_valid_hex_number(&self) -> bool

To set the default parameters, use is_valid_hex_number_ex and its builder methods. See the book for detailed usage instructions. 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

pub fn is_valid_hex_number_ex<'ex>(&'ex self) -> ExIsValidHexNumber<'ex>

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

pub fn is_valid_html_color(&self) -> bool

Returns true if this string is a valid color in hexadecimal HTML notation. The string must be a hexadecimal value (see [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 [html][crate::builtin::Color::html].

pub fn is_valid_ip_address(&self) -> bool

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.

pub fn is_valid_filename(&self) -> bool

Returns true if this string is a valid file name. A valid file name cannot be empty, begin or end with space characters, or contain characters that are not allowed (: / \ ? * " | % < >).

pub fn to_int(&self) -> i64

Converts the string representing an integer number into an int. This method removes any non-number character and stops at the first decimal point (.). See also [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

pub fn to_float(&self) -> f64

Converts the string representing a decimal number into a float. This method stops on the first non-number character, except the first decimal point (.) and the exponent letter (e). See also [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

pub fn hex_to_int(&self) -> i64

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

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

pub fn bin_to_int(&self) -> i64

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

pub fn trim_prefix(&self, prefix: impl AsArg<GString>) -> GString

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

pub fn trim_suffix(&self, suffix: impl AsArg<GString>) -> GString

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

pub fn to_ascii_buffer(&self) -> PackedArray<u8>

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

pub fn to_utf8_buffer(&self) -> PackedArray<u8>

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

pub fn to_utf16_buffer(&self) -> PackedArray<u8>

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

pub fn to_utf32_buffer(&self) -> PackedArray<u8>

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

pub fn to_wchar_buffer(&self) -> PackedArray<u8>

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

pub fn hex_decode(&self) -> PackedArray<u8>

Decodes a hexadecimal string as a PackedByteArray.

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

pub fn num_scientific(number: f64) -> GString

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

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

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

pub fn num(number: f64) -> GString

To set the default parameters, use num_ex and its builder methods. See the book for detailed usage instructions. Converts a float to a string representation of a decimal number, with the number of decimal places specified in decimals.

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

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

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

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

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

pub fn num_ex<'ex>(number: f64) -> ExNum<'ex>

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

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

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

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

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

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

pub fn num_int64(number: i64) -> GString

To set the default parameters, use num_int64_ex and its builder methods. See the book for detailed usage instructions. 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.

pub fn num_int64_ex<'ex>(number: i64) -> ExNumInt64<'ex>

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.

pub fn num_uint64(number: i64) -> GString

To set the default parameters, use num_uint64_ex and its builder methods. See the book for detailed usage instructions. Converts the given unsigned int to a string representation, with the given base.

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

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

pub fn num_uint64_ex<'ex>(number: i64) -> ExNumUint64<'ex>

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

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

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

pub fn chr(code: i64) -> GString

Returns a single Unicode character from the integer code. 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)

See also [method unicode_at], [method @GDScript.char], and [method @GDScript.ord].

pub fn humanize_size(size: i64) -> GString

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".

Trait Implementations

impl Clone for GString

fn clone(&self) -> GString

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GString

Uses literal syntax from GDScript: "string"

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for GString

fn default() -> GString

Returns the “default value” for a type.

impl Display for GString

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Drop for GString

fn drop(&mut self)

Executes the destructor for this type.

impl From<&[char]> for GString

fn from(chars: &[char]) -> GString

Converts to this type from the input type.

impl From<&GString> for NodePath

fn from(string: &GString) -> NodePath

Converts to this type from the input type.

impl From<&GString> for StringName

fn from(string: &GString) -> StringName

See also [GString::to_string_name()].

impl From<&NodePath> for GString

fn from(path: &NodePath) -> GString

Converts to this type from the input type.

impl From<&String> for GString

fn from(value: &String) -> GString

Converts to this type from the input type.

impl From<&StringName> for GString

fn from(string: &StringName) -> GString

Converts to this type from the input type.

impl From<&str> for GString

fn from(s: &str) -> GString

Converts to this type from the input type.

impl FromGodot for GString

fn try_from_godot( via: <GString as GodotConvert>::Via, ) -> Result<GString, ConvertError>

Converts the Godot representation to this type, returning Err on failure.

fn from_godot(via: Self::Via) -> Self

⚠️ Converts the Godot representation to this type.

fn try_from_variant(variant: &Variant) -> Result<Self, ConvertError>

Performs the conversion from a Variant, returning Err on failure.

fn from_variant(variant: &Variant) -> Self

⚠️ Performs the conversion from a Variant.

impl FromStr for GString

type Err = Infallible

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<GString, <GString as FromStr>::Err>

Parses a string s to return a value of this type.

impl GodotConvert for GString

type Via = GString

The type through which Self is represented in Godot.

fn godot_shape() -> GodotShape

Which “shape” this type has for property registration (e.g. builtin, enum, …).

impl GodotImmutable for GString

fn into_runtime_immutable(self) -> Self

impl Hash for GString

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoDynamicSend for GString

type Target = ThreadConfined<GString>

fn into_dynamic_send(self) -> <GString as IntoDynamicSend>::Target

impl Ord for GString

fn cmp(&self, other: &GString) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<&str> for GString

fn eq(&self, other: &&str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for GString

fn eq(&self, other: &GString) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for GString

fn partial_cmp(&self, other: &GString) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl ToGodot for GString

type Pass = ByRef

Whether arguments of this type are passed by value or by reference.

fn to_godot(&self) -> &<GString as GodotConvert>::Via

Converts this type to Godot representation, optimizing for zero-copy when possible.

fn to_godot_owned(&self) -> Self::Via

Converts this type to owned Godot representation.

fn to_variant(&self) -> Variant

Converts this type to a Variant.

impl AsArg<GString> for &String

impl AsArg<GString> for &str

impl AsArg<Variant> for &GString

impl AsDirectElement<GString> for &String

impl AsDirectElement<GString> for &str

impl BuiltinExport for GString

impl Element for GString

impl Eq for GString

impl Export for GString

impl GodotType for GString

impl PackedElement for GString

impl Send for GString

impl SimpleVar for GString