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

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 internal chars slice from a GString.

Trait Implementations

impl ArrayElement for GString

fn debug_validate_elements(_array: &Array<Self>) -> Result<(), ConvertError>

impl Clone for GString

fn clone(&self) -> GString

Returns a copy 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 Export for GString

fn export_hint() -> PropertyHintInfo

The export info to use for an exported field of this type, if no other export info is specified.

fn as_node_class() -> Option<ClassName>

If this is a class inheriting Node, returns the ClassName; otherwise None.

impl Extend<GString> for PackedStringArray

Extends aPackedStringArray with the contents of an iterator

fn extend<I>(&mut self, iter: I)

where I: IntoIterator<Item = GString>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

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

Converts to this type from the input type.

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 From<GString> for NodePath

fn from(string: GString) -> NodePath

Converts this GString to a NodePath.

This is identical to NodePath::from(&string), and as such there is no performance benefit.

impl From<GString> for StringName

fn from(string: GString) -> StringName

Converts this GString to a StringName.

This is identical to StringName::from(&string), and as such there is no performance benefit.

impl From<NodePath> for GString

fn from(path: NodePath) -> GString

Converts this NodePath to a GString.

This is identical to GString::from(&path), and as such there is no performance benefit.

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_name: StringName) -> GString

Converts this StringName to a GString.

This is identical to GString::from(&string_name), and as such there is no performance benefit.

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 FromIterator<GString> for PackedStringArray

Creates a PackedStringArray from an iterator.

fn from_iter<I>(iter: I) -> PackedStringArray

where I: IntoIterator<Item = GString>,

Creates a value from an iterator.

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.

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 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 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 ToVia<'v> = <GString as GodotConvert>::Via

Target type of to_godot(), which differs from Via for pass-by-reference types.

fn to_godot(&self) -> <GString as ToGodot>::ToVia<'_>

Converts this type to the Godot type by reference, usually by cloning.

fn to_variant(&self) -> Variant

Converts this type to a Variant.

impl Var for GString

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

fn set_property(&mut self, value: <GString as GodotConvert>::Via)

fn var_hint() -> PropertyHintInfo

Specific property hints, only override if they deviate from GodotType::property_info, e.g. for enums/newtypes.

impl Eq for GString

impl GodotType for GString

impl PackedArrayElement for GString