Struct godot::builtin::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::engine, both parameters and return types are GString. In the future, we will likely declare parameters as impl Into<GString>, allowing String or &str to be passed.

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’s encoding is platform-dependent and unspecified)

§Other string types

Godot also provides two separate string classes with slightly different semantics: StringName and NodePath.

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

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_checked(&self) -> &[char]

Gets the internal chars slice from a GString.

Note: This operation is O(n). Consider using chars_unchecked if you can make sure the string is a valid UTF-32.

pub unsafe fn chars_unchecked(&self) -> &[char]

Gets the internal chars slice from a GString.

§Safety

Make sure the string only contains valid unicode scalar values, currently Godot allows for unpaired surrogates and out of range code points to be appended into the string.