godot::builtin

Struct StringName

pub struct StringName { /* private fields */ }
Expand description

A string optimized for unique names.

StringNames are immutable strings designed for representing unique names. StringName ensures that only one instance of a given name exists.

§Ordering

In Godot, StringNames are not ordered lexicographically, and the ordering relation is not stable across multiple runs of your application. Therefore, this type does not implement PartialOrd and Ord, as it would be very easy to introduce bugs by accidentally relying on lexicographical ordering.

Instead, we provide transient_ord() for ordering relations.

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

§Performance

The fastest way to create string names is by using null-terminated C-string literals such as c"MyClass". These have 'static lifetime and can be used directly by Godot, without allocation or conversion. The encoding is limited to Latin-1, however. See the corresponding From<&'static CStr> impl.

§All string types

Intended use caseString type
General purposeGString
Interned namesStringName
Scene-node pathsNodePath

Implementations§

§

impl StringName

pub fn len(&self) -> usize

Returns the number of characters in the string.

Godot equivalent: length

pub fn is_empty(&self) -> bool

Returns true if this is the empty string.

Godot equivalent: is_empty

pub fn hash(&self) -> u32

Returns a 32-bit integer hash value representing the string.

pub fn transient_ord(&self) -> TransientStringNameOrd<'_>

O(1), non-lexicographic, non-stable ordering relation.

The result of the comparison is not lexicographic and not stable across multiple runs of your application.

However, it is very fast. It doesn’t depend on the length of the strings, but on the memory location of string names. This can still be useful if you need to establish an ordering relation, but are not interested in the actual order of the strings (example: binary search).

For lexicographical ordering, convert to GString (significantly slower).

Trait Implementations§

§

impl ArrayElement for StringName

§

impl Clone for StringName

§

fn clone(&self) -> StringName

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 StringName

Uses literal syntax from GDScript: &"string_name"

§

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

Formats the value using the given formatter. Read more
§

impl Default for StringName

§

fn default() -> StringName

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

impl Display for StringName

§

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

Formats the value using the given formatter. Read more
§

impl Drop for StringName

§

fn drop(&mut self)

Executes the destructor for this type. Read more
§

impl Export for StringName

§

fn export_hint() -> PropertyHintInfo

The export info to use for an exported field of this type, if no other export info is specified.
§

fn as_node_class() -> Option<ClassName>

If this is a class inheriting Node, returns the ClassName; otherwise None. Read more
§

impl From<&'static CStr> for StringName

Available on since_api="4.2" only.
§

fn from(c_str: &'static CStr) -> StringName

Creates a StringName from a static ASCII/Latin-1 c"string".

This avoids unnecessary copies and allocations and directly uses the backing buffer. Useful for literals.

Note that while Latin-1 encoding is the most common encoding for c-strings, it isn’t a requirement. So if your c-string uses a different encoding (e.g. UTF-8), it is possible that some characters will not show up as expected.

§Example
use godot::builtin::StringName;

// '±' is a Latin-1 character with codepoint 0xB1. Note that this is not UTF-8, where it would need two bytes.
let sname = StringName::from(c"\xb1 Latin-1 string");
§

impl From<&GString> for StringName

§

fn from(string: &GString) -> StringName

Converts to this type from the input type.
§

impl From<&NodePath> for StringName

§

fn from(path: &NodePath) -> StringName

Converts to this type from the input type.
§

impl From<&String> for StringName

§

fn from(value: &String) -> StringName

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<&StringName> for NodePath

§

fn from(string_name: &StringName) -> NodePath

Converts to this type from the input type.
§

impl From<&str> for StringName

§

fn from(string: &str) -> StringName

Converts to this type from the input type.
§

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 StringName

§

fn from(path: NodePath) -> StringName

Converts this NodePath to a StringName.

This is identical to StringName::from(&path), and as such there is no performance benefit.

§

impl From<String> for StringName

§

fn from(value: String) -> StringName

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 From<StringName> for NodePath

§

fn from(string_name: StringName) -> NodePath

Converts this StringName to a NodePath.

This is identical to NodePath::from(&string_name), and as such there is no performance benefit.

§

impl FromGodot for StringName

§

fn try_from_godot( via: <StringName as GodotConvert>::Via, ) -> Result<StringName, 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 FromStr for StringName

§

type Err = Infallible

The associated error which can be returned from parsing.
§

fn from_str(string: &str) -> Result<StringName, <StringName as FromStr>::Err>

Parses a string s to return a value of this type. Read more
§

impl GodotConvert for StringName

§

type Via = StringName

The type through which Self is represented in Godot.
§

impl Hash for StringName

§

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 PartialEq for StringName

§

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

§

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

Target type of to_godot(), which differs from Via for pass-by-reference types.
§

fn to_godot(&self) -> <StringName 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 StringName

§

fn get_property(&self) -> <StringName as GodotConvert>::Via

§

fn set_property(&mut self, value: <StringName 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 Eq for StringName

§

impl GodotType for StringName

§

impl Send for StringName

§

impl Sync for StringName

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

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