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`

Implementations§

§

impl GString

pub fn new() -> GString

Construct a new empty GString.

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

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> ApiParam<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 ApiParam in that case.