Struct godot::builtin::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.

Implementations

impl StringName

pub fn from_latin1_with_nul(latin1_c_str: &'static [u8]) -> StringName

👎Deprecated: Since Rust 1.77, you can use c-string literals with From/Into instead of this function.

Available on since_api="4.2" only.

Creates a StringName from a static, nul-terminated ASCII/Latin-1 b"string" literal.

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

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_latin1_with_nul(b"\xb1 Latin-1 string\0");

Panics

When the string is not nul-terminated or contains interior nul bytes.

Note that every byte is valid in Latin-1, so there is no encoding validation being performed.

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 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 default_export_info() -> PropertyHintInfo

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

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl ToGodot for StringName

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

Converts this type to the Godot type by reference, usually by cloning.

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

Converts this type to the Godot type.

fn to_variant(&self) -> Variant

Converts this type to a Variant.

impl TypeStringHint for StringName

fn type_string() -> String

Returns the representation of this type as a type string.

impl Var for StringName

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

fn set_property(&mut self, value: <StringName as GodotConvert>::Via)

fn property_hint() -> PropertyHintInfo

impl ArrayElement for StringName

impl Eq for StringName

impl GodotType for StringName

impl Send for StringName

impl Sync for StringName