godot::prelude

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 caseString type
General purposeGString
Interned namesStringName
Scene-node pathsNodePath

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

Trait Implementations§

§

impl Clone for GString

§

fn clone(&self) -> GString

Returns a copy of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
§

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

impl Default for GString

§

fn default() -> GString

Returns the “default value” for a type. Read more
§

impl Display for GString

§

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

Formats the value using the given formatter. Read more
§

impl Drop for GString

§

fn drop(&mut self)

Executes the destructor for this type. Read more
§

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

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. Read more
Source§

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)
Extends a collection with exactly one element.
Source§

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

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

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

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

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

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. Read more
1.3.0 · Source§

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

Feeds a slice of this type into the given Hasher. Read more
§

impl Ord for GString

§

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

This method returns an Ordering between self and other. Read more
1.21.0 · Source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · Source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · Source§

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

Restrict a value to a certain interval. Read more
§

impl ParamType for GString

§

fn owned_to_arg<'v>(self) -> <GString as ParamType>::Arg<'v>

Converts an owned value to the canonical argument type, which can be passed to impl AsArg<T>. Read more
§

impl PartialEq for GString

§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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. Read more
1.0.0 · Source§

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

Tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · Source§

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

Tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · Source§

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

Tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · Source§

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

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

impl ToGodot for GString

§

type ToVia<'v> = <GString as GodotConvert>::Via

Target type of to_godot(), which can differ from Via for pass-by-reference types. Read more
§

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 ArrayElement for GString

§

impl<'r> AsArg<GString> for &'r GString

§

impl AsArg<GString> for &String

§

impl AsArg<GString> for &str

§

impl Eq for GString

§

impl GodotType for GString

§

impl PackedArrayElement for GString

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.