Struct StringName

pub struct StringName { /* private fields */ }

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 case	String type
General purpose	GString
Interned names	StringName
Scene-node paths	NodePath

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

fn debug_validate_elements(_array: &Array<Self>) -> Result<(), ConvertError>

impl Clone for StringName

fn clone(&self) -> StringName

Returns a copy of the value.

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

Performs copy-assignment from source.

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.

impl Default for StringName

fn default() -> StringName

Returns the “default value” for a type.

impl Display for StringName

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

Formats the value using the given formatter.

impl Drop for StringName

fn drop(&mut self)

Executes the destructor for this type.

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.

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.

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.

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.

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.

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

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