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 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 arg<T>(&self) -> impl AsArg<T>
where T: for<'a> From<&'a StringName> + for<'a> ParamType<Arg<'a> = CowArg<'a, T>> + 'a,

Use as argument for an impl AsArg<GString|NodePath> parameter.

This is a convenient way to convert arguments of similar string types.

§Example

Node::set_name() takes GString, let’s pass a StringName:

let name = StringName::from("my cool node");

let mut node = Node::new_alloc();
node.set_name(name.arg());

§Generic bounds

The bounds are implementation-defined and may change at any time. Do not use this function in a generic context requiring T – use the From trait or ParamType in that case.

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

§

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");

§