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

Godot docs

StringName (stable)

Implementations

impl StringName

pub fn len(&self) -> usize

Number of characters in the string.

Godot equivalent: length

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

impl StringName

Manually-declared, shared methods between GString and StringName.

pub fn unicode_at(&self, index: usize) -> char

Returns the Unicode code point (“character”) at position index.

Panics

In debug builds, if index is out of bounds. In Release builds, 0 is returned instead.

pub fn find(&self, what: impl AsArg<GString>) -> Option<usize>

Find first occurrence of what and return index, or None if not found.

Check find_ex() for all custom options.

pub fn find_ex<'s, 'w>( &'s self, what: impl AsArg<GString> + 'w, ) -> ExStringNameFind<'s, 'w>

Returns a builder for finding substrings, with various configuration options.

The builder struct offers methods to configure 3 dimensions, which map to different Godot functions in the back:

Method	Default behavior	Behavior after method call
r()	forward search (find*)	backward search (rfind*)
n()	case-sensitive search (*find)	case-insensitive search (*findn)
from(index)	search from beginning (or end if reverse)	search from specified index

Returns Some(index) of the first occurrence, or None if not found.

Example

To find the substring "O" in "Hello World", not considering case and starting from position 5, you can write:

let s = GString::from("Hello World");
if let Some(found) = s.find_ex("O").n().from(5).done() {
   do_sth_with_index(found)
}

This is equivalent to the following GDScript code:

var s: GString = "Hello World"
var found = s.findn("O", 5)
if found != -1:
    do_sth_with_index(found)

pub fn count( &self, what: impl AsArg<GString>, range: impl RangeBounds<usize>, ) -> usize

Count how many times what appears within range. Use .. for full string search.

pub fn countn( &self, what: impl AsArg<GString>, range: impl RangeBounds<usize>, ) -> usize

Count how many times what appears within range, case-insensitively. Use .. for full string search.

pub fn split(&self, delimiter: impl AsArg<GString>) -> PackedStringArray

Splits the string according to delimiter.

See split_ex() if you need further configuration.

pub fn split_ex<'s, 'w>( &'s self, delimiter: impl AsArg<GString> + 'w, ) -> ExStringNameSplit<'s, 'w>

Returns a builder that splits this string into substrings using delimiter.

If delimiter is an empty string, each substring will be a single character.

The builder struct offers methods to configure multiple dimensions. Note that rsplit in Godot is not useful without the maxsplit argument, so the two are combined in Rust as maxsplit_r.

Method	Default behavior	Behavior after method call
disallow_empty()	allows empty parts	empty parts are removed from result
maxsplit(n)	entire string is split	splits n times -> n+1 parts
maxsplit_r(n)	entire string is split	splits n times -> n+1 parts (start from back)

pub fn substr(&self, range: impl RangeBounds<usize>) -> GString

Returns a substring of this, as another GString.

pub fn get_slice( &self, delimiter: impl AsArg<GString>, slice: usize, ) -> Option<GString>

Splits the string using a string delimiter and returns the substring at index slice.

Returns the original string if delimiter does not occur in the string. Returns None if slice is out of bounds.

This is faster than split(), if you only need one substring.

pub fn get_slicec(&self, delimiter: char, slice: usize) -> Option<GString>

Splits the string using a Unicode char delimiter and returns the substring at index slice.

Returns the original string if delimiter does not occur in the string. Returns None if slice is out of bounds.

This is faster than split(), if you only need one substring.

pub fn get_slice_count(&self, delimiter: impl AsArg<GString>) -> usize

Returns the total number of slices, when the string is split with the given delimiter.

See also split() and get_slice().

pub fn erase(&self, range: impl RangeBounds<usize>) -> GString

Returns a copy of the string without the specified index range.

pub fn insert(&self, position: usize, what: impl AsArg<GString>) -> GString

Returns a copy of the string with an additional string inserted at the given position.

If the position is out of bounds, the string will be inserted at the end.

Consider using format() for more flexibility.

pub fn format(&self, array_or_dict: &Variant) -> GString

Format a string using substitutions from an array or dictionary.

See Godot’s String.format().

pub fn format_with_placeholder( &self, array_or_dict: &Variant, placeholder: impl AsArg<GString>, ) -> GString

Format a string using substitutions from an array or dictionary + custom placeholder.

See Godot’s String.format().

pub fn lpad(&self, min_length: usize, character: char) -> GString

Formats the string to be at least min_length long, by adding characters to the left of the string, if necessary.

Godot itself allows padding with multiple characters, but that behavior is not very useful, because min_length isn’t respected in that case. The parameter in Godot is even called character. In Rust, we directly expose char instead.

See also rpad().

pub fn rpad(&self, min_length: usize, character: char) -> GString

Formats the string to be at least min_length long, by adding characters to the right of the string, if necessary.

Godot itself allows padding with multiple characters, but that behavior is not very useful, because min_length isn’t respected in that case. The parameter in Godot is even called character. In Rust, we directly expose char instead.

See also lpad().

pub fn pad_decimals(&self, digits: usize) -> GString

Formats the string representing a number to have an exact number of digits after the decimal point.

pub fn pad_zeros(&self, digits: usize) -> GString

Formats the string representing a number to have an exact number of digits before the decimal point.

pub fn casecmp_to(&self, to: impl AsArg<GString>) -> Ordering

Case-sensitive, lexicographic comparison to another string.

Returns the Ordering relation of self towards to. Ordering is determined by the Unicode code points of each string, which roughly matches the alphabetical order.

See also nocasecmp_to(), naturalcasecmp_to(), filecasecmp_to().

pub fn nocasecmp_to(&self, to: impl AsArg<GString>) -> Ordering

Case-insensitive, lexicographic comparison to another string.

Returns the Ordering relation of self towards to. Ordering is determined by the Unicode code points of each string, which roughly matches the alphabetical order.

See also casecmp_to(), naturalcasecmp_to(), filecasecmp_to().

pub fn naturalcasecmp_to(&self, to: impl AsArg<GString>) -> Ordering

Case-sensitive, natural-order comparison to another string.

Returns the Ordering relation of self towards to. Ordering is determined by the Unicode code points of each string, which roughly matches the alphabetical order.

When used for sorting, natural order comparison orders sequences of numbers by the combined value of each digit as is often expected, instead of the single digit’s value. A sorted sequence of numbered strings will be ["1", "2", "3", ...], not ["1", "10", "2", "3", ...].

With different string lengths, returns Ordering::Greater if this string is longer than the to string, or Ordering::Less if shorter.

See also casecmp_to(), naturalnocasecmp_to(), filecasecmp_to().

pub fn naturalnocasecmp_to(&self, to: impl AsArg<GString>) -> Ordering

Case-insensitive, natural-order comparison to another string.

Returns the Ordering relation of self towards to. Ordering is determined by the Unicode code points of each string, which roughly matches the alphabetical order.

When used for sorting, natural order comparison orders sequences of numbers by the combined value of each digit as is often expected, instead of the single digit’s value. A sorted sequence of numbered strings will be ["1", "2", "3", ...], not ["1", "10", "2", "3", ...].

With different string lengths, returns Ordering::Greater if this string is longer than the to string, or Ordering::Less if shorter.

See also casecmp_to(), naturalcasecmp_to(), filecasecmp_to().

pub fn filecasecmp_to(&self, to: impl AsArg<GString>) -> Ordering

Available on since_api="4.3" only.

Case-sensitive, filename-oriented comparison to another string.

Like naturalcasecmp_to(), but prioritizes strings that begin with periods (.) and underscores (_) before any other character. Useful when sorting folders or file names.

See also casecmp_to(), naturalcasecmp_to(), filenocasecmp_to().

pub fn filenocasecmp_to(&self, to: impl AsArg<GString>) -> Ordering

Available on since_api="4.3" only.

Case-insensitive, filename-oriented comparison to another string.

Like naturalnocasecmp_to(), but prioritizes strings that begin with periods (.) and underscores (_) before any other character. Useful when sorting folders or file names.

See also casecmp_to(), naturalcasecmp_to(), filecasecmp_to().

pub fn match_glob(&self, pattern: impl AsArg<GString>) -> bool

Simple expression match (also called “glob” or “globbing”), where * matches zero or more arbitrary characters and ? matches any single character except a period (.).

An empty string or empty expression always evaluates to false.

Renamed from match because of collision with Rust keyword + possible confusion with String::matches() that can match regex.

pub fn matchn_glob(&self, pattern: impl AsArg<GString>) -> bool

Simple case-insensitive expression match (also called “glob” or “globbing”), where * matches zero or more arbitrary characters and ? matches any single character except a period (.).

An empty string or empty expression always evaluates to false.

Renamed from matchn because of collision with Rust keyword + possible confusion with String::matches() that can match regex.

impl StringName

pub fn begins_with(&self, text: impl AsArg<GString>) -> bool

pub fn ends_with(&self, text: impl AsArg<GString>) -> bool

pub fn is_subsequence_of(&self, text: impl AsArg<GString>) -> bool

pub fn is_subsequence_ofn(&self, text: impl AsArg<GString>) -> bool

pub fn bigrams(&self) -> PackedStringArray

pub fn similarity(&self, text: impl AsArg<GString>) -> f64

pub fn replace( &self, what: impl AsArg<GString>, forwhat: impl AsArg<GString>, ) -> GString

pub fn replacen( &self, what: impl AsArg<GString>, forwhat: impl AsArg<GString>, ) -> GString

pub fn repeat(&self, count: i64) -> GString

pub fn reverse(&self) -> GString

pub fn capitalize(&self) -> GString

pub fn to_camel_case(&self) -> GString

pub fn to_pascal_case(&self) -> GString

pub fn to_snake_case(&self) -> GString

pub fn split_floats( &self, delimiter: impl AsArg<GString>, allow_empty: bool, ) -> PackedFloat64Array

pub fn join(&self, parts: &PackedStringArray) -> GString

pub fn to_upper(&self) -> GString

pub fn to_lower(&self) -> GString

pub fn left(&self, length: i64) -> GString

pub fn right(&self, length: i64) -> GString

pub fn strip_edges(&self, left: bool, right: bool) -> GString

pub fn strip_escapes(&self) -> GString

pub fn lstrip(&self, chars: impl AsArg<GString>) -> GString

pub fn rstrip(&self, chars: impl AsArg<GString>) -> GString

pub fn get_extension(&self) -> GString

pub fn get_basename(&self) -> GString

pub fn path_join(&self, file: impl AsArg<GString>) -> GString

pub fn indent(&self, prefix: impl AsArg<GString>) -> GString

pub fn dedent(&self) -> GString

pub fn md5_text(&self) -> GString

pub fn sha1_text(&self) -> GString

pub fn sha256_text(&self) -> GString

pub fn md5_buffer(&self) -> PackedByteArray

pub fn sha1_buffer(&self) -> PackedByteArray

pub fn sha256_buffer(&self) -> PackedByteArray

pub fn is_empty(&self) -> bool

pub fn contains(&self, what: impl AsArg<GString>) -> bool

pub fn containsn(&self, what: impl AsArg<GString>) -> bool

pub fn is_absolute_path(&self) -> bool

pub fn is_relative_path(&self) -> bool

pub fn simplify_path(&self) -> GString

pub fn get_base_dir(&self) -> GString

pub fn get_file(&self) -> GString

pub fn xml_escape(&self, escape_quotes: bool) -> GString

pub fn xml_unescape(&self) -> GString

pub fn uri_encode(&self) -> GString

pub fn uri_decode(&self) -> GString

pub fn c_escape(&self) -> GString

pub fn c_unescape(&self) -> GString

pub fn json_escape(&self) -> GString

pub fn validate_node_name(&self) -> GString

pub fn validate_filename(&self) -> GString

pub fn is_valid_identifier(&self) -> bool

pub fn is_valid_int(&self) -> bool

pub fn is_valid_float(&self) -> bool

pub fn is_valid_hex_number(&self, with_prefix: bool) -> bool

pub fn is_valid_html_color(&self) -> bool

pub fn is_valid_ip_address(&self) -> bool

pub fn is_valid_filename(&self) -> bool

pub fn to_int(&self) -> i64

pub fn to_float(&self) -> f64

pub fn hex_to_int(&self) -> i64

pub fn bin_to_int(&self) -> i64

pub fn trim_prefix(&self, prefix: impl AsArg<GString>) -> GString

pub fn trim_suffix(&self, suffix: impl AsArg<GString>) -> GString

pub fn to_ascii_buffer(&self) -> PackedByteArray

pub fn to_utf8_buffer(&self) -> PackedByteArray

pub fn to_utf16_buffer(&self) -> PackedByteArray

pub fn to_utf32_buffer(&self) -> PackedByteArray

pub fn hex_decode(&self) -> PackedByteArray

pub fn to_wchar_buffer(&self) -> PackedByteArray

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

impl From<&GString> for StringName

fn from(string: &GString) -> StringName

See also [GString::to_string_name()].

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

fn owned_to_arg<'v>(self) -> <StringName as ParamType>::Arg<'v>

Converts an owned value to the canonical argument type, which can be passed to impl AsArg<T>.

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 can differ 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 ArrayElement for StringName

impl AsArg<StringName> for &'static CStr

Available on since_api="4.2" only.

impl AsArg<StringName> for &String

impl<'r> AsArg<StringName> for &'r StringName

impl AsArg<StringName> for &str

impl Eq for StringName

impl GodotType for StringName

impl Send for StringName

impl Sync for StringName