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
.
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§
Trait Implementations§
§impl ArrayElement for GString
impl ArrayElement for GString
fn debug_validate_elements(_array: &Array<Self>) -> Result<(), ConvertError>
§impl Export for GString
impl Export for GString
§fn export_hint() -> PropertyHintInfo
fn export_hint() -> PropertyHintInfo
§fn as_node_class() -> Option<ClassName>
fn as_node_class() -> Option<ClassName>
§impl Extend<GString> for PackedStringArray
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>,
fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = GString>,
Source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)Source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)§impl From<&GString> for StringName
impl From<&GString> for StringName
§fn from(string: &GString) -> StringName
fn from(string: &GString) -> StringName
§impl From<&StringName> for GString
impl From<&StringName> for GString
§fn from(string: &StringName) -> GString
fn from(string: &StringName) -> GString
§impl From<GString> for StringName
impl From<GString> for StringName
§fn from(string: GString) -> 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<StringName> for GString
impl From<StringName> for GString
§fn from(string_name: StringName) -> 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
impl FromGodot for GString
§fn try_from_godot(
via: <GString as GodotConvert>::Via,
) -> Result<GString, ConvertError>
fn try_from_godot( via: <GString as GodotConvert>::Via, ) -> Result<GString, ConvertError>
Err
on failure.§fn from_godot(via: Self::Via) -> Self
fn from_godot(via: Self::Via) -> Self
§fn try_from_variant(variant: &Variant) -> Result<Self, ConvertError>
fn try_from_variant(variant: &Variant) -> Result<Self, ConvertError>
Variant
, returning Err
on failure.§fn from_variant(variant: &Variant) -> Self
fn from_variant(variant: &Variant) -> Self
§impl FromIterator<GString> for PackedStringArray
impl FromIterator<GString> for PackedStringArray
Creates a PackedStringArray
from an iterator.
§fn from_iter<I>(iter: I) -> PackedStringArraywhere
I: IntoIterator<Item = GString>,
fn from_iter<I>(iter: I) -> PackedStringArraywhere
I: IntoIterator<Item = GString>,
§impl GodotConvert for GString
impl GodotConvert for GString
§impl Ord for GString
impl Ord for GString
§impl PartialOrd for GString
impl PartialOrd for GString
§impl ToGodot for GString
impl ToGodot for GString
§type ToVia<'v> = <GString as GodotConvert>::Via
type ToVia<'v> = <GString as GodotConvert>::Via
to_godot()
, which differs from Via
for pass-by-reference types.§fn to_godot(&self) -> <GString as ToGodot>::ToVia<'_>
fn to_godot(&self) -> <GString as ToGodot>::ToVia<'_>
§fn to_variant(&self) -> Variant
fn to_variant(&self) -> Variant
§impl Var for GString
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
fn var_hint() -> PropertyHintInfo
GodotType::property_info
, e.g. for enums/newtypes.impl Eq for GString
impl GodotType for GString
impl PackedArrayElement for GString
Auto Trait Implementations§
impl Freeze for GString
impl RefUnwindSafe for GString
impl !Send for GString
impl !Sync for GString
impl Unpin for GString
impl UnwindSafe for GString
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)