Struct GString

pub struct GString { /* private fields */ }

Expand description

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 len(&self) -> usize

Number of characters in the string.

Godot equivalent: length

pub fn hash(&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.

pub fn arg<T>(&self) -> impl AsArg<T>
where T: for<'a> From<&'a GString> + for<'a> ParamType<Arg<'a> = CowArg<'a, T>> + 'a,

Use as argument for an impl AsArg<StringName|NodePath> parameter.

This is a convenient way to convert arguments of similar string types.

§Example

Node::has_node() takes NodePath, let’s pass a GString:

let name = GString::from("subnode");

let node = Node::new_alloc();
if node.has_node(name.arg()) {
    // ...
}

§Generic bounds

The bounds are implementation-defined and may change at any time. Do not use this function in a generic context requiring T – use the From trait or ParamType in that case.

§

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

In debug builds, if index is out of bounds. In Release builds, 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, ) -> ExGStringFind<'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>) -> PackedStringArray

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, ) -> ExGStringSplit<'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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

§