Struct gdnative::core_types::GodotString

pub struct GodotString(/* 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.

GodotString is reference-counted like most types in godot-rust. Thus, its clone() method does not return a copy of the string, but simply another instance which shares the same backing string. Furthermore, GodotString is immutable and does not offer any write APIs. If you need to modify Godot strings, convert them to Rust strings, perform the modifications and convert back. In GDScript, strings have copy-on-write semantics, which guarantees that GodotString instances in Rust are independent of their GDScript counterparts. A modification of a string in GDScript (which was previously passed to Rust) will not be reflected in Rust.

When interfacing with the Godot engine API through godot-rust, you often have the choice between std::string::String and gdnative::core_types::GodotString. In user methods that are exposed to Godot through the #[export] macro, both types can be used as parameters and return types, and any conversions are done transparently. For auto-generated binding APIs in gdnative::api, return types are GodotString, but parameters are declared impl Into<GodotString>, allowing String or &str to be passed. In addition, the two types can always be explicitly converted using GodotString::from_str() and GodotString::display/to_string().

As a general guideline, use GodotString 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 (GodotString’s encoding is platform-dependent and unspecified)

Implementations

impl GodotString

pub fn new() -> GodotString

pub fn from_str<S>(s: S) -> GodotString

where S: AsRef<str>,

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn is_numeric(&self) -> bool

pub fn is_valid_float(&self) -> bool

pub fn is_valid_html_color(&self) -> bool

pub fn is_valid_identifier(&self) -> bool

pub fn is_valid_integer(&self) -> bool

pub fn is_valid_ip_address(&self) -> bool

pub fn is_resource_file(&self) -> bool

pub fn is_absolute_path(&self) -> bool

pub fn is_relative_path(&self) -> bool

pub fn to_f32(&self) -> f32

pub fn to_f64(&self) -> f64

pub fn to_i32(&self) -> i32

pub fn u32_hash(&self) -> u32

pub fn u64_hash(&self) -> u64

pub fn hex_to_int(&self) -> i32

pub fn hex_to_int_without_prefix(&self) -> i32

pub fn camelcase_to_underscore(&self) -> GodotString

pub fn camelcase_to_underscore_lowercased(&self) -> GodotString

pub fn capitalize(&self) -> GodotString

pub fn to_lowercase(&self) -> GodotString

pub fn to_uppercase(&self) -> GodotString

pub fn get_file(&self) -> GodotString

pub fn get_base_dir(&self) -> GodotString

pub fn get_basename(&self) -> GodotString

pub fn get_extension(&self) -> GodotString

pub fn simplify_path(&self) -> GodotString

pub fn sha256_text(&self) -> GodotString

pub fn md5_text(&self) -> GodotString

pub fn c_escape(&self) -> GodotString

pub fn c_escape_multiline(&self) -> GodotString

pub fn c_unescape(&self) -> GodotString

pub fn http_escape(&self) -> GodotString

pub fn http_unescape(&self) -> GodotString

pub fn json_escape(&self) -> GodotString

pub fn xml_escape(&self) -> GodotString

pub fn xml_escape_with_quotes(&self) -> GodotString

pub fn xml_unescape(&self) -> GodotString

pub fn percent_decode(&self) -> GodotString

pub fn percent_encode(&self) -> GodotString

pub fn is_valid_hex_number(&self, with_prefix: bool) -> bool

pub fn begins_with(&self, s: &GodotString) -> bool

pub fn ends_with(&self, s: &GodotString) -> bool

pub fn begins_with_c_str(&self, s: &CStr) -> bool

pub fn sub_string(&self, range: Range<usize>) -> GodotString

pub fn find(&self, what: &GodotString) -> i32

pub fn find_from(&self, what: &GodotString, from: i32) -> i32

pub fn find_last(&self, what: &GodotString) -> i32

pub fn format(&self, values: &Variant) -> GodotString

Formats the string by replacing all occurrences of a key in the string with the corresponding value. The method can handle arrays or dictionaries for the key/value pairs.

Arrays can be used as key, index, or mixed style (see below examples). Order only matters when the index or mixed style of Array is used.

Examples

// Array values, index style
let template = GodotString::from("{0} {1}");
let data = VariantArray::new();
data.push("foo");
data.push("bar");

let formatted = template.format(&data.into_shared().to_variant());
godot_print!("{}", formatted); // "foo bar"

// Dictionary values
let template = GodotString::from("foo {bar}");
let data = Dictionary::new();
data.insert("bar", "baz");

let formatted = template.format(&data.into_shared().to_variant());
godot_print!("{}", formatted); // "foo baz"

Trait Implementations

impl Add<&GodotString> for &GodotString

type Output = GodotString

The resulting type after applying the + operator.

fn add(self, other: &GodotString) -> GodotString

Performs the + operation.

impl<S> Add<S> for &GodotString

where S: AsRef<str>,

type Output = GodotString

The resulting type after applying the + operator.

fn add(self, other: S) -> GodotString

Performs the + operation.

impl Add for GodotString

type Output = GodotString

The resulting type after applying the + operator.

fn add(self, other: GodotString) -> GodotString

Performs the + operation.

impl AddAssign<&GodotString> for GodotString

AddAssign implementations copy the strings’ contents since GodotString is immutable.

fn add_assign(&mut self, other: &GodotString)

Performs the += operation.

impl<S> AddAssign<S> for GodotString

where S: AsRef<str>,

AddAssign implementations copy the strings’ contents since GodotString is immutable.

fn add_assign(&mut self, other: S)

Performs the += operation.

impl AddAssign for GodotString

AddAssign implementations copy the strings’ contents since GodotString is immutable.

fn add_assign(&mut self, other: GodotString)

Performs the += operation.

impl Clone for GodotString

fn clone(&self) -> GodotString

Returns a copy of the value.

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

Performs copy-assignment from source.

impl CoerceFromVariant for GodotString

fn coerce_from_variant(v: &Variant) -> GodotString

impl Debug for GodotString

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

Formats the value using the given formatter.

impl Default for GodotString

fn default() -> GodotString

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for GodotString

fn deserialize<D>( deserializer: D, ) -> Result<GodotString, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for GodotString

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

Formats the value using the given formatter.

impl Drop for GodotString

fn drop(&mut self)

Executes the destructor for this type.

impl Export for GodotString

type Hint = StringHint

A type-specific hint type that is valid for the type being exported.

fn export_info(hint: Option<<GodotString as Export>::Hint>) -> ExportInfo

Returns ExportInfo given an optional typed hint.

impl From<GodotString> for NodePath

fn from(s: GodotString) -> NodePath

Converts to this type from the input type.

impl From<NodePath> for GodotString

fn from(p: NodePath) -> GodotString

Converts to this type from the input type.

impl<S> From<S> for GodotString

where S: AsRef<str>,

fn from(s: S) -> GodotString

Converts to this type from the input type.

impl FromVariant for GodotString

fn from_variant(variant: &Variant) -> Result<GodotString, FromVariantError>

impl Hash for GodotString

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 Index<usize> for GodotString

The index operator provides a low-level view of characters in Godot’s native encoding that doesn’t always correspond to Unicode code points one-to-one. This operation goes through FFI. For intensive string operations, consider converting to a Rust String first to avoid this cost.

type Output = GodotChar

The returned type after indexing.

fn index(&self, index: usize) -> &<GodotString as Index<usize>>::Output

Performs the indexing (container[index]) operation.

impl NewRef for GodotString

fn new_ref(&self) -> GodotString

Creates a new reference to the underlying object.

impl Ord for GodotString

fn cmp(&self, other: &GodotString) -> 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 + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for GodotString

fn eq(&self, other: &GodotString) -> 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 GodotString

fn partial_cmp(&self, other: &GodotString) -> 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 Serialize for GodotString

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl ToVariant for GodotString

fn to_variant(&self) -> Variant

impl Eq for GodotString

impl PoolElement for GodotString

impl ToVariantEq for GodotString