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.

§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 try_from_bytes( bytes: &[u8], encoding: Encoding, ) -> Result<StringName, StringError>

Convert string from bytes with given encoding, returning Err on validation errors.

Intermediate NUL characters are not accepted in Godot and always return Err.

Some notes on the encodings:

Latin-1: Since every byte is a valid Latin-1 character, no validation besides the NUL byte is performed. It is your responsibility to ensure that the input is meaningful under Latin-1.
ASCII: Subset of Latin-1, which is additionally validated to be valid, non-NUL ASCII characters.
UTF-8: The input is validated to be UTF-8.

Specifying incorrect encoding is safe, but may result in unintended string values.

pub fn try_from_cstr( cstr: &CStr, encoding: Encoding, ) -> Result<StringName, StringError>

Convert string from bytes with given encoding, returning Err on validation errors.

Convenience function for try_from_bytes(); see its docs for more information.

When called with Encoding::Latin1, this can be slightly more efficient than try_from_bytes().

pub fn len(&self) -> usize

Number of characters in the string.

Godot equivalent: length

pub fn hash_u32(&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).

pub fn chars(&self) -> &[char]

Available on since_api=4.5 only.

Gets the UTF-32 character slice from a StringName.

§Compatibility

This method is only available for Godot 4.5 and later, where StringName to GString conversions preserve the underlying buffer pointer via reference counting.

§

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 (safeguards-balanced)

If index is out of bounds. In disengaged level, 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, ) -> ExFind<'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>) -> PackedArray<GString>

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, ) -> ExSplit<'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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Returns true if the string begins with the given text. See also [method ends_with].

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

Returns true if the string ends with the given text. See also [method begins_with].

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

Returns true if all characters of this string can be found in text in their original order. This is not the same as [method contains].

var text = "Wow, incredible!"

print("inedible".is_subsequence_of(text)) # Prints true
print("Word!".is_subsequence_of(text))    # Prints true
print("Window".is_subsequence_of(text))   # Prints false
print("".is_subsequence_of(text))         # Prints true

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

Returns true if all characters of this string can be found in text in their original order, ignoring case. This is not the same as [method containsn].

pub fn bigrams(&self) -> PackedArray<GString>

Returns an array containing the bigrams (pairs of consecutive characters) of this string.

print("Get up!".bigrams()) # Prints ["Ge", "et", "t ", " u", "up", "p!"]

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

Returns the similarity index (Sørensen-Dice coefficient) of this string compared to another. A result of 1.0 means totally similar, while 0.0 means totally dissimilar.

print("ABC123".similarity("ABC123")) # Prints 1.0
print("ABC123".similarity("XYZ456")) # Prints 0.0
print("ABC123".similarity("123ABC")) # Prints 0.8
print("ABC123".similarity("abc123")) # Prints 0.4

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

Replaces all occurrences of what inside the string with the given forwhat.

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

Replaces all case-insensitive occurrences of what inside the string with the given forwhat.

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

Repeats this string a number of times. count needs to be greater than 0. Otherwise, returns an empty string.

pub fn reverse(&self) -> GString

Returns the copy of this string in reverse order. This operation works on unicode codepoints, rather than sequences of codepoints, and may break things like compound letters or emojis.

pub fn capitalize(&self) -> GString

Changes the appearance of the string: replaces underscores (_) with spaces, adds spaces before uppercase letters in the middle of a word, converts all letters to lowercase, then converts the first one and each one following a space to uppercase.

"move_local_x".capitalize()   # Returns "Move Local X"
"sceneFile_path".capitalize() # Returns "Scene File Path"
"2D, FPS, PNG".capitalize()   # Returns "2d, Fps, Png"

pub fn to_camel_case(&self) -> GString

Returns the string converted to camelCase.

pub fn to_pascal_case(&self) -> GString

Returns the string converted to PascalCase.

pub fn to_snake_case(&self) -> GString

Returns the string converted to snake_case.

Note: Numbers followed by a single letter are not separated in the conversion to keep some words (such as “2D”) together.

"Node2D".to_snake_case()               # Returns "node_2d"
"2nd place".to_snake_case()            # Returns "2_nd_place"
"Texture3DAssetFolder".to_snake_case() # Returns "texture_3d_asset_folder"

pub fn split_floats(&self, delimiter: impl AsArg<GString>) -> PackedArray<f64>

To set the default parameters, use split_floats_ex and its builder methods. See the book for detailed usage instructions. Splits the string into floats by using a delimiter and returns a PackedFloat64Array.

If allow_empty is false, empty or invalid float conversions between adjacent delimiters are excluded.

var a = "1,2,4.5".split_floats(",")         # a is [1.0, 2.0, 4.5]
var c = "1| ||4.5".split_floats("|")        # c is [1.0, 0.0, 0.0, 4.5]
var b = "1| ||4.5".split_floats("|", false) # b is [1.0, 4.5]

pub fn split_floats_ex<'ex>( &'ex self, delimiter: impl AsArg<GString> + 'ex, ) -> ExSplitFloats<'ex>

Splits the string into floats by using a delimiter and returns a PackedFloat64Array.

If allow_empty is false, empty or invalid float conversions between adjacent delimiters are excluded.

var a = "1,2,4.5".split_floats(",")         # a is [1.0, 2.0, 4.5]
var c = "1| ||4.5".split_floats("|")        # c is [1.0, 0.0, 0.0, 4.5]
var b = "1| ||4.5".split_floats("|", false) # b is [1.0, 4.5]

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

Returns the concatenation of parts’ elements, with each element separated by the string calling this method. This method is the opposite of [method split].

var fruits = ["Apple", "Orange", "Pear", "Kiwi"]

print(", ".join(fruits))  # Prints "Apple, Orange, Pear, Kiwi"
print("---".join(fruits)) # Prints "Apple---Orange---Pear---Kiwi"

pub fn to_upper(&self) -> GString

Returns the string converted to UPPERCASE.

pub fn to_lower(&self) -> GString

Returns the string converted to lowercase.

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

Returns the first length characters from the beginning of the string. If length is negative, strips the last length characters from the string’s end.

print("Hello World!".left(3))  # Prints "Hel"
print("Hello World!".left(-4)) # Prints "Hello Wo"

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

Returns the last length characters from the end of the string. If length is negative, strips the first length characters from the string’s beginning.

print("Hello World!".right(3))  # Prints "ld!"
print("Hello World!".right(-4)) # Prints "o World!"

pub fn strip_edges(&self) -> GString

To set the default parameters, use strip_edges_ex and its builder methods. See the book for detailed usage instructions. Strips all non-printable characters from the beginning and the end of the string. These include spaces, tabulations (\t), and newlines (\n \r).

If left is false, ignores the string’s beginning. Likewise, if right is false, ignores the string’s end.

pub fn strip_edges_ex<'ex>(&'ex self) -> ExStripEdges<'ex>

Strips all non-printable characters from the beginning and the end of the string. These include spaces, tabulations (\t), and newlines (\n \r).

If left is false, ignores the string’s beginning. Likewise, if right is false, ignores the string’s end.

pub fn strip_escapes(&self) -> GString

Strips all escape characters from the string. These include all non-printable control characters of the first page of the ASCII table (values from 0 to 31), such as tabulation (\t) and newline (\n, \r) characters, but not spaces.

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

Removes a set of characters defined in chars from the string’s beginning. See also [method rstrip].

Note: chars is not a prefix. Use [method trim_prefix] to remove a single prefix, rather than a set of characters.

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

Removes a set of characters defined in chars from the string’s end. See also [method lstrip].

Note: chars is not a suffix. Use [method trim_suffix] to remove a single suffix, rather than a set of characters.

pub fn get_extension(&self) -> GString

If the string is a valid file name or path, returns the file extension without the leading period (.). Otherwise, returns an empty string.

var a = "/path/to/file.txt".get_extension() # a is "txt"
var b = "cool.txt".get_extension()          # b is "txt"
var c = "cool.font.tres".get_extension()    # c is "tres"
var d = ".pack1".get_extension()            # d is "pack1"

var e = "file.txt.".get_extension()  # e is ""
var f = "file.txt..".get_extension() # f is ""
var g = "txt".get_extension()        # g is ""
var h = "".get_extension()           # h is ""

pub fn get_basename(&self) -> GString

If the string is a valid file path, returns the full file path, without the extension.

var base = "/path/to/file.txt".get_basename() # base is "/path/to/file"

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

Concatenates path at the end of the string as a subpath, adding / if necessary.

Example: "this/is".path_join("path") == "this/is/path".

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

Indents every line of the string with the given prefix. Empty lines are not indented. See also [method dedent] to remove indentation.

For example, the string can be indented with two tabulations using "\t\t", or four spaces using " ".

pub fn dedent(&self) -> GString

Returns a copy of the string with indentation (leading tabs and spaces) removed. See also [method indent] to add indentation.

pub fn md5_text(&self) -> GString

Returns the MD5 hash of the string as another String.

pub fn sha1_text(&self) -> GString

Returns the SHA-1 hash of the string as another String.

pub fn sha256_text(&self) -> GString

Returns the SHA-256 hash of the string as another String.

pub fn md5_buffer(&self) -> PackedArray<u8>

Returns the MD5 hash of the string as a PackedByteArray.

pub fn sha1_buffer(&self) -> PackedArray<u8>

Returns the SHA-1 hash of the string as a PackedByteArray.

pub fn sha256_buffer(&self) -> PackedArray<u8>

Returns the SHA-256 hash of the string as a PackedByteArray.

pub fn is_empty(&self) -> bool

Returns true if the string’s length is 0 (""). See also [method length].

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

Returns true if the string contains what. In GDScript, this corresponds to the in operator.

print("Node".contains("de")) # Prints true
print("team".contains("I"))  # Prints false
print("I" in "team")         # Prints false

If you need to know where what is within the string, use [method find]. See also [method containsn].

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

Returns true if the string contains what, ignoring case.

If you need to know where what is within the string, use [method findn]. See also [method contains].

pub fn is_absolute_path(&self) -> bool

Returns true if the string is a path to a file or directory, and its starting point is explicitly defined. This method is the opposite of [method is_relative_path].

This includes all paths starting with "res://", "user://", "C:\", "/", etc.

pub fn is_relative_path(&self) -> bool

Returns true if the string is a path, and its starting point is dependent on context. The path could begin from the current directory, or the current Node (if the string is derived from a NodePath), and may sometimes be prefixed with "./". This method is the opposite of [method is_absolute_path].

pub fn simplify_path(&self) -> GString

If the string is a valid file path, converts the string into a canonical path. This is the shortest possible path, without "./", and all the unnecessary ".." and "/".

var simple_path = "./path/to///../file".simplify_path()
print(simple_path) # Prints "path/file"

pub fn get_base_dir(&self) -> GString

If the string is a valid file path, returns the base directory name.

var dir_path = "/path/to/file.txt".get_base_dir() # dir_path is "/path/to"

pub fn get_file(&self) -> GString

If the string is a valid file path, returns the file name, including the extension.

var file = "/path/to/icon.png".get_file() # file is "icon.png"

pub fn xml_escape(&self) -> GString

To set the default parameters, use xml_escape_ex and its builder methods. See the book for detailed usage instructions. Returns a copy of the string with special characters escaped using the XML standard. If escape_quotes is true, the single quote (') and double quote (") characters are also escaped.

pub fn xml_escape_ex<'ex>(&'ex self) -> ExXmlEscape<'ex>

Returns a copy of the string with special characters escaped using the XML standard. If escape_quotes is true, the single quote (') and double quote (") characters are also escaped.

pub fn xml_unescape(&self) -> GString

Returns a copy of the string with escaped characters replaced by their meanings according to the XML standard.

pub fn uri_encode(&self) -> GString

Encodes the string to URL-friendly format. This method is meant to properly encode the parameters in a URL when sending an HTTP request. See also [method uri_decode].

var prefix = "$DOCS_URL/?highlight="
var url = prefix + "Godot Engine:docs".uri_encode()

print(url) # Prints "$DOCS_URL/?highlight=Godot%20Engine%3%docs"

pub fn uri_decode(&self) -> GString

Decodes the string from its URL-encoded format. This method is meant to properly decode the parameters in a URL when receiving an HTTP request. See also [method uri_encode].

var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs"
print(url.uri_decode()) # Prints "$DOCS_URL/?highlight=Godot Engine:docs"

Note: This method decodes + as space.

pub fn c_escape(&self) -> GString

Returns a copy of the string with special characters escaped using the C language standard.

pub fn c_unescape(&self) -> GString

Returns a copy of the string with escaped characters replaced by their meanings. Supported escape sequences are \', \", \\, \a, \b, \f, \n, \r, \t, \v.

Note: Unlike the GDScript parser, this method doesn’t support the \uXXXX escape sequence.

pub fn json_escape(&self) -> GString

Returns a copy of the string with special characters escaped using the JSON standard. Because it closely matches the C standard, it is possible to use [method c_unescape] to unescape the string, if necessary.

pub fn validate_node_name(&self) -> GString

Returns a copy of the string with all characters that are not allowed in [member Node.name] (. : @ / " %) replaced with underscores.

pub fn validate_filename(&self) -> GString

Returns a copy of the string with all characters that are not allowed in [method is_valid_filename] replaced with underscores.

pub fn is_valid_identifier(&self) -> bool

Returns true if this string is a valid identifier. A valid identifier may contain only letters, digits and underscores (_), and the first character may not be a digit.

print("node_2d".is_valid_identifier())    # Prints true
print("TYPE_FLOAT".is_valid_identifier()) # Prints true
print("1st_method".is_valid_identifier()) # Prints false
print("MyMethod#2".is_valid_identifier()) # Prints false

pub fn is_valid_int(&self) -> bool

Returns true if this string represents a valid integer. A valid integer only contains digits, and may be prefixed with a positive (+) or negative (-) sign. See also [method to_int].

print("7".is_valid_int())    # Prints true
print("1.65".is_valid_int()) # Prints false
print("Hi".is_valid_int())   # Prints false
print("+3".is_valid_int())   # Prints true
print("-12".is_valid_int())  # Prints true

pub fn is_valid_float(&self) -> bool

Returns true if this string represents a valid floating-point number. A valid float may contain only digits, one decimal point (.), and the exponent letter (e). It may also be prefixed with a positive (+) or negative (-) sign. Any valid integer is also a valid float (see [method is_valid_int]). See also [method to_float].

print("1.7".is_valid_float())   # Prints true
print("24".is_valid_float())    # Prints true
print("7e3".is_valid_float())   # Prints true
print("Hello".is_valid_float()) # Prints false

pub fn is_valid_hex_number(&self) -> bool

To set the default parameters, use is_valid_hex_number_ex and its builder methods. See the book for detailed usage instructions. Returns true if this string is a valid hexadecimal number. A valid hexadecimal number only contains digits or letters A to F (either uppercase or lowercase), and may be prefixed with a positive (+) or negative (-) sign.

If with_prefix is true, the hexadecimal number needs to prefixed by "0x" to be considered valid.

print("A08E".is_valid_hex_number())    # Prints true
print("-AbCdEf".is_valid_hex_number()) # Prints true
print("2.5".is_valid_hex_number())     # Prints false

print("0xDEADC0DE".is_valid_hex_number(true)) # Prints true

pub fn is_valid_hex_number_ex<'ex>(&'ex self) -> ExIsValidHexNumber<'ex>

Returns true if this string is a valid hexadecimal number. A valid hexadecimal number only contains digits or letters A to F (either uppercase or lowercase), and may be prefixed with a positive (+) or negative (-) sign.

If with_prefix is true, the hexadecimal number needs to prefixed by "0x" to be considered valid.

print("A08E".is_valid_hex_number())    # Prints true
print("-AbCdEf".is_valid_hex_number()) # Prints true
print("2.5".is_valid_hex_number())     # Prints false

print("0xDEADC0DE".is_valid_hex_number(true)) # Prints true

pub fn is_valid_html_color(&self) -> bool

Returns true if this string is a valid color in hexadecimal HTML notation. The string must be a hexadecimal value (see [method is_valid_hex_number]) of either 3, 4, 6 or 8 digits, and may be prefixed by a hash sign (#). Other HTML notations for colors, such as names or hsl(), are not considered valid. See also [html][crate::builtin::Color::html].

pub fn is_valid_ip_address(&self) -> bool

Returns true if this string represents a well-formatted IPv4 or IPv6 address. This method considers reserved IP addresses such as "0.0.0.0" and "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" as valid.

pub fn is_valid_filename(&self) -> bool

Returns true if this string is a valid file name. A valid file name cannot be empty, begin or end with space characters, or contain characters that are not allowed (: / \ ? * " | % < >).

pub fn to_int(&self) -> i64

Converts the string representing an integer number into an int. This method removes any non-number character and stops at the first decimal point (.). See also [method is_valid_int].

var a = "123".to_int()    # a is 123
var b = "x1y2z3".to_int() # b is 123
var c = "-1.2.3".to_int() # c is -1
var d = "Hello!".to_int() # d is 0

pub fn to_float(&self) -> f64

Converts the string representing a decimal number into a float. This method stops on the first non-number character, except the first decimal point (.) and the exponent letter (e). See also [method is_valid_float].

var a = "12.35".to_float()  # a is 12.35
var b = "1.2.3".to_float()  # b is 1.2
var c = "12xy3".to_float()  # c is 12.0
var d = "1e3".to_float()    # d is 1000.0
var e = "Hello!".to_float() # e is 0.0

pub fn hex_to_int(&self) -> i64

Converts the string representing a hexadecimal number into an int. The string may be optionally prefixed with "0x", and an additional - prefix for negative numbers.

print("0xff".hex_to_int()) # Prints 255
print("ab".hex_to_int())   # Prints 171

pub fn bin_to_int(&self) -> i64

Converts the string representing a binary number into an int. The string may optionally be prefixed with "0b", and an additional - prefix for negative numbers.

print("101".bin_to_int())   # Prints 5
print("0b101".bin_to_int()) # Prints 5
print("-0b10".bin_to_int()) # Prints -2

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

Removes the given prefix from the start of the string, or returns the string unchanged.

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

Removes the given suffix from the end of the string, or returns the string unchanged.

pub fn to_ascii_buffer(&self) -> PackedArray<u8>

Converts the string to an ASCII/Latin-1 encoded PackedByteArray. This method is slightly faster than [method to_utf8_buffer], but replaces all unsupported characters with spaces. This is the inverse of get_string_from_ascii.

pub fn to_utf8_buffer(&self) -> PackedArray<u8>

Converts the string to a UTF-8 encoded PackedByteArray. This method is slightly slower than [method to_ascii_buffer], but supports all UTF-8 characters. For most cases, prefer using this method. This is the inverse of get_string_from_utf8.

pub fn to_utf16_buffer(&self) -> PackedArray<u8>

Converts the string to a UTF-16 encoded PackedByteArray. This is the inverse of get_string_from_utf16.

pub fn to_utf32_buffer(&self) -> PackedArray<u8>

Converts the string to a UTF-32 encoded PackedByteArray. This is the inverse of get_string_from_utf32.

pub fn to_wchar_buffer(&self) -> PackedArray<u8>

Converts the string to a wide character (wchar_t, UTF-16 on Windows, UTF-32 on other platforms) encoded PackedByteArray. This is the inverse of get_string_from_wchar.

pub fn hex_decode(&self) -> PackedArray<u8>

Decodes a hexadecimal string as a PackedByteArray.

var text = "hello world"
var encoded = text.to_utf8_buffer().hex_encode() # outputs "68656c6c6f20776f726c64"
print(encoded.hex_decode().get_string_from_utf8())