Struct gdnative_core::core_types::GodotString
source · pub struct GodotString(_);
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
.
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§
source§impl GodotString
impl GodotString
pub fn new() -> Self
pub fn from_str<S>(s: S) -> Selfwhere
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) -> Self
pub fn camelcase_to_underscore_lowercased(&self) -> Self
pub fn capitalize(&self) -> Self
pub fn to_lowercase(&self) -> Self
pub fn to_uppercase(&self) -> Self
pub fn get_file(&self) -> Self
pub fn get_base_dir(&self) -> Self
pub fn get_basename(&self) -> Self
pub fn get_extension(&self) -> Self
pub fn simplify_path(&self) -> Self
pub fn sha256_text(&self) -> Self
pub fn md5_text(&self) -> Self
pub fn c_escape(&self) -> Self
pub fn c_escape_multiline(&self) -> Self
pub fn c_unescape(&self) -> Self
pub fn http_escape(&self) -> Self
pub fn http_unescape(&self) -> Self
pub fn json_escape(&self) -> Self
pub fn xml_escape(&self) -> Self
pub fn xml_escape_with_quotes(&self) -> Self
pub fn xml_unescape(&self) -> Self
pub fn percent_decode(&self) -> Self
pub fn percent_encode(&self) -> Self
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>) -> Self
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
sourcepub fn format(&self, values: &Variant) -> Self
pub fn format(&self, values: &Variant) -> Self
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§
source§impl Add<&GodotString> for &GodotString
impl Add<&GodotString> for &GodotString
§type Output = GodotString
type Output = GodotString
+
operator.source§fn add(self, other: &GodotString) -> GodotString
fn add(self, other: &GodotString) -> GodotString
+
operation. Read moresource§impl Add<GodotString> for GodotString
impl Add<GodotString> for GodotString
§type Output = GodotString
type Output = GodotString
+
operator.source§fn add(self, other: GodotString) -> GodotString
fn add(self, other: GodotString) -> GodotString
+
operation. Read moresource§impl<S> Add<S> for &GodotStringwhere
S: AsRef<str>,
impl<S> Add<S> for &GodotStringwhere
S: AsRef<str>,
§type Output = GodotString
type Output = GodotString
+
operator.source§fn add(self, other: S) -> GodotString
fn add(self, other: S) -> GodotString
+
operation. Read moresource§impl AddAssign<&GodotString> for GodotString
impl AddAssign<&GodotString> for GodotString
AddAssign
implementations copy the strings’ contents since GodotString
is immutable.
source§fn add_assign(&mut self, other: &Self)
fn add_assign(&mut self, other: &Self)
+=
operation. Read moresource§impl AddAssign<GodotString> for GodotString
impl AddAssign<GodotString> for GodotString
AddAssign
implementations copy the strings’ contents since GodotString
is immutable.
source§fn add_assign(&mut self, other: Self)
fn add_assign(&mut self, other: Self)
+=
operation. Read moresource§impl<S> AddAssign<S> for GodotStringwhere
S: AsRef<str>,
impl<S> AddAssign<S> for GodotStringwhere
S: AsRef<str>,
AddAssign
implementations copy the strings’ contents since GodotString
is immutable.
source§fn add_assign(&mut self, other: S)
fn add_assign(&mut self, other: S)
+=
operation. Read moresource§impl Clone for GodotString
impl Clone for GodotString
source§impl CoerceFromVariant for GodotString
impl CoerceFromVariant for GodotString
fn coerce_from_variant(v: &Variant) -> Self
source§impl Debug for GodotString
impl Debug for GodotString
source§impl Default for GodotString
impl Default for GodotString
source§impl Display for GodotString
impl Display for GodotString
source§impl Drop for GodotString
impl Drop for GodotString
source§impl Export for GodotString
impl Export for GodotString
§type Hint = StringHint
type Hint = StringHint
source§fn export_info(hint: Option<Self::Hint>) -> ExportInfo
fn export_info(hint: Option<Self::Hint>) -> ExportInfo
ExportInfo
given an optional typed hint.source§impl From<GodotString> for NodePath
impl From<GodotString> for NodePath
source§fn from(s: GodotString) -> NodePath
fn from(s: GodotString) -> NodePath
source§impl From<NodePath> for GodotString
impl From<NodePath> for GodotString
source§fn from(p: NodePath) -> GodotString
fn from(p: NodePath) -> GodotString
source§impl<S> From<S> for GodotStringwhere
S: AsRef<str>,
impl<S> From<S> for GodotStringwhere
S: AsRef<str>,
source§fn from(s: S) -> GodotString
fn from(s: S) -> GodotString
source§impl FromVariant for GodotString
impl FromVariant for GodotString
fn from_variant(variant: &Variant) -> Result<Self, FromVariantError>
source§impl Hash for GodotString
impl Hash for GodotString
source§impl Index<usize> for GodotString
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.
source§impl NewRef for GodotString
impl NewRef for GodotString
source§fn new_ref(&self) -> GodotString
fn new_ref(&self) -> GodotString
source§impl Ord for GodotString
impl Ord for GodotString
source§impl PartialEq<GodotString> for GodotString
impl PartialEq<GodotString> for GodotString
source§impl PartialOrd<GodotString> for GodotString
impl PartialOrd<GodotString> for GodotString
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl ToVariant for GodotString
impl ToVariant for GodotString
fn to_variant(&self) -> Variant
impl Eq for GodotString
impl PoolElement for GodotString
impl ToVariantEq for GodotString
Auto Trait Implementations§
impl RefUnwindSafe for GodotString
impl Send for GodotString
impl Sync for GodotString
impl Unpin for GodotString
impl UnwindSafe for GodotString
Blanket Implementations§
source§impl<Q, K> Equivalent<K> for Qwhere
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
impl<Q, K> Equivalent<K> for Qwhere
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.