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

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

👎Deprecated: Use chars() instead. Since version 4.1, Godot ensures valid UTF-32, checked and unchecked overloads are no longer needed. For details, see godotengine/godot#74760.

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]

👎Deprecated: Use chars() instead. Since version 4.1, ensures valid UTF-32, checked and unchecked overloads are no longer needed. For details, see godotengine/godot#74760.

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.

pub fn chars(&self) -> &[char]

Available on since_api="4.1" only.

Gets the internal chars slice from a GString.

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 default_export_info() -> 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<&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. 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 + PartialOrd,

Restrict a value to a certain interval. Read more
§

impl PartialEq for GString

§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

This method 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

This method 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

This method 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

This method 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

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

impl ToGodot for GString

§

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

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

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

Converts this type to the Godot type. Read more
§

fn to_variant(&self) -> Variant

Converts this type to a Variant.
§

impl TypeStringHint for GString

§

fn type_string() -> String

Returns the representation of this type as a type string. Read more
§

impl Var for GString

§

impl ArrayElement for GString

§

impl Eq for GString

§

impl GodotType 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> 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,

§

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

§

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

§

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.