Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

StringName

唯一字符串内置类型。

描述

StringName 是不可变的字符串,用于唯一名称的通用表示(也叫“字符串内嵌”)。值相同的两个 StringName 是同一个对象。进行比较时比普通 String 要快很多。

对于需要 StringName 的方法,你通常可以只传 String,会自动进行转换,不过有时候你可能会想要提前使用 StringName 构造函数来构造 StringName,在 GDScript 中也可以用 &"example" 语法。

另见 NodePath,这是与此类似的概念,针对存储预解析的场景树路径设计。

String 的所有方法都在这个类中可用。它们会将 StringName 转换为字符串,返回的也是字符串。这样做效率非常低,应该只在需要字符串时使用。

注意:转换为布尔值时,空的 StringNameStringName(""))为 false,其他 StringName 均为 true。不能使用 not 运算符。请改用 is_empty 来检查空的 StringName

构造函数

StringName

StringName ( )

StringName

StringName ( StringName from )

StringName

StringName ( String from )

方法

bool

begins_with ( String text ) const

PackedStringArray

bigrams ( ) const

int

bin_to_int ( ) const

String

c_escape ( ) const

String

c_unescape ( ) const

String

capitalize ( ) const

int

casecmp_to ( String to ) const

bool

contains ( String what ) const

int

count ( String what, int from=0, int to=0 ) const

int

countn ( String what, int from=0, int to=0 ) const

String

dedent ( ) const

bool

ends_with ( String text ) const

String

erase ( int position, int chars=1 ) const

int

find ( String what, int from=0 ) const

int

findn ( String what, int from=0 ) const

String

format ( Variant values, String placeholder="{_}" ) const

String

get_base_dir ( ) const

String

get_basename ( ) const

String

get_extension ( ) const

String

get_file ( ) const

String

get_slice ( String delimiter, int slice ) const

int

get_slice_count ( String delimiter ) const

String

get_slicec ( int delimiter, int slice ) const

int

hash ( ) const

PackedByteArray

hex_decode ( ) const

int

hex_to_int ( ) const

String

indent ( String prefix ) const

String

insert ( int position, String what ) const

bool

is_absolute_path ( ) const

bool

is_empty ( ) const

bool

is_relative_path ( ) const

bool

is_subsequence_of ( String text ) const

bool

is_subsequence_ofn ( String text ) const

bool

is_valid_filename ( ) const

bool

is_valid_float ( ) const

bool

is_valid_hex_number ( bool with_prefix=false ) const

bool

is_valid_html_color ( ) const

bool

is_valid_identifier ( ) const

bool

is_valid_int ( ) const

bool

is_valid_ip_address ( ) const

String

join ( PackedStringArray parts ) const

String

json_escape ( ) const

String

left ( int length ) const

int

length ( ) const

String

lpad ( int min_length, String character=" " ) const

String

lstrip ( String chars ) const

bool

match ( String expr ) const

bool

matchn ( String expr ) const

PackedByteArray

md5_buffer ( ) const

String

md5_text ( ) const

int

naturalcasecmp_to ( String to ) const

int

naturalnocasecmp_to ( String to ) const

int

nocasecmp_to ( String to ) const

String

pad_decimals ( int digits ) const

String

pad_zeros ( int digits ) const

String

path_join ( String file ) const

String

repeat ( int count ) const

String

replace ( String what, String forwhat ) const

String

replacen ( String what, String forwhat ) const

String

reverse ( ) const

int

rfind ( String what, int from=-1 ) const

int

rfindn ( String what, int from=-1 ) const

String

right ( int length ) const

String

rpad ( int min_length, String character=" " ) const

PackedStringArray

rsplit ( String delimiter="", bool allow_empty=true, int maxsplit=0 ) const

String

rstrip ( String chars ) const

PackedByteArray

sha1_buffer ( ) const

String

sha1_text ( ) const

PackedByteArray

sha256_buffer ( ) const

String

sha256_text ( ) const

float

similarity ( String text ) const

String

simplify_path ( ) const

PackedStringArray

split ( String delimiter="", bool allow_empty=true, int maxsplit=0 ) const

PackedFloat64Array

split_floats ( String delimiter, bool allow_empty=true ) const

String

strip_edges ( bool left=true, bool right=true ) const

String

strip_escapes ( ) const

String

substr ( int from, int len=-1 ) const

PackedByteArray

to_ascii_buffer ( ) const

String

to_camel_case ( ) const

float

to_float ( ) const

int

to_int ( ) const

String

to_lower ( ) const

String

to_pascal_case ( ) const

String

to_snake_case ( ) const

String

to_upper ( ) const

PackedByteArray

to_utf8_buffer ( ) const

PackedByteArray

to_utf16_buffer ( ) const

PackedByteArray

to_utf32_buffer ( ) const

PackedByteArray

to_wchar_buffer ( ) const

String

trim_prefix ( String prefix ) const

String

trim_suffix ( String suffix ) const

int

unicode_at ( int at ) const

String

uri_decode ( ) const

String

uri_encode ( ) const

String

validate_filename ( ) const

String

validate_node_name ( ) const

String

xml_escape ( bool escape_quotes=false ) const

String

xml_unescape ( ) const

操作符

bool

operator != ( String right )

bool

operator != ( StringName right )

String

operator % ( Variant right )

String

operator + ( String right )

String

operator + ( StringName right )

bool

operator < ( StringName right )

bool

operator <= ( StringName right )

bool

operator == ( String right )

bool

operator == ( StringName right )

bool

operator > ( StringName right )

bool

operator >= ( StringName right )


构造函数说明

StringName StringName ( )

构造空的 StringName


StringName StringName ( StringName from )

构造给定 StringName 的副本。


StringName StringName ( String from )

从给定的 String 创建 StringName。在 GDScript 中,StringName("example")&"example" 等价。


方法说明

bool begins_with ( String text ) const

如果该字符串以给定的 text 开始,则返回 true。另见 ends_with


PackedStringArray bigrams ( ) const

返回包含该字符串的双字母组(连续字母的组合)的数组。

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

int bin_to_int ( ) const

将表示二进制数的字符串转换为 int。该字符串可以前缀 "0b",负数可以前缀 -

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

String c_escape ( ) const

返回该字符串的副本,按照 C 语言标准对特殊字符进行转义。


String c_unescape ( ) const

返回该字符串的副本,转义字符均使用本义代替。支持的转义序列有 \'\"\\\a\b\f\n\r\t\v

注意:与 GDScript 解析器不同,这个方法不支持 \uXXXX 转义序列。


String capitalize ( ) const

改变字符串的外观:用空格代替下划线(_),在单词中间的大写字母前添加空格,将所有字母转换为小写,然后将第一个字母和空格后的每个字母转换为大写。

"move_local_x".capitalize()   # 返回 "Move Local X"
"sceneFile_path".capitalize() # 返回 "Scene File Path"

注意:这个方法与检查器面板中属性的默认外观不一样,不会像你期望的那样将首字母缩写大写("2D""FPS""PNG" 等)。


int casecmp_to ( String to ) const

与另一个字符串进行比较,区分大小写。小于时返回 -1、大于时返回 1、等于时返回 0。“小于”和“大于”比较的是字符串中的 Unicode 码位,大致与字母表顺序一致。

如果字符串长度不同,这个字符串比 to 字符串长时返回 1,短时返回 -1。请注意空字符串的长度始终0

如果想在比较字符串时获得 bool 返回值,请改用 == 运算符。另见 nocasecmp_tonaturalcasecmp_tonaturalnocasecmp_to


bool contains ( String what ) const

如果该字符串包含 what,则返回 true。在 GDScript 中对应 in 运算符。

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

如果想要知道 what 在该字符串中的位置,请使用 find


int count ( String what, int from=0, int to=0 ) const

返回子串 whatfromto 位置之间出现的次数。如果 to 为 0,会在剩余字符串中继续搜索。


int countn ( String what, int from=0, int to=0 ) const

返回子串 whatfromto 位置之间出现的次数,忽略大小写。如果 to 为 0,会在剩余字符串中继续搜索。


String dedent ( ) const

返回删除了缩进(前导制表符和空格)的字符串副本。添加缩进请参阅 indent


bool ends_with ( String text ) const

如果该字符串以给定的 text 结束,则返回 true。另见 begins_with


String erase ( int position, int chars=1 ) const

返回从 position 开始擦除 chars 个字符后的字符串。如果在指定 position 的基础上 chars 超过字符串的长度,返回的字符串中擦除的字符数会少于请求的数量。如果 positionchars 为负数,则返回空字符串。如果 chars0 则返回原字符串,不进行修改。


int find ( String what, int from=0 ) const

返回 what 在该字符串中第一次出现的索引,如果不存在则返回 -1。搜索的起点可以用 from 指定,持续到字符串结尾。

print("Team".find("I")) # 输出 -1

print("Potato".find("t"))    # 输出 2
print("Potato".find("t", 3)) # 输出 4
print("Potato".find("t", 5)) # 输出 -1

注意:如果你只是想要知道该字符串中是否包含 what,请使用 contains。在 GDScript 中,你还可以使用 in 运算符。


int findn ( String what, int from=0 ) const

返回这个字符串中 what 首次出现的索引,不区分大小写,不存在时则为 -1。搜索的起点可以用 from 指定,终点为该字符串的末尾。


String format ( Variant values, String placeholder="{_}" ) const

通过将所有出现的 placeholder 替换为 values 的元素来格式化字符串。

values 可以是 DictionaryArrayplaceholder 中的任何下划线将被预先被替换为对应的键。数组元素使用它们的索引作为键。

# 输出:Waiting for Godot 是 Samuel Beckett 的戏剧,Godot 引擎由此得名。
var use_array_values = "Waiting for {0} 是 {1} 的戏剧,{0} 引擎由此得名。"
print(use_array_values.format(["Godot", "Samuel Beckett"]))

# 输出:第 42 号用户是 Godot。
print("第 {id} 号用户是 {name}。".format({"id": 42, "name": "Godot"}))

valuesArray 时还会执行一些额外的处理。 如果 placeholder 不包含下划线,则 values 数组的元素将用于按顺序替换出现的占位符;如果 values 的元素是另一个 2 元素数组,则它将被解释为键值对。

# 输出:第 42 号用户是 Godot。
print("第 {} 号用户是 {}。".format([42, "Godot"], "{}"))
print("第 {id} 号用户是 {name}。".format([["id", 42], ["name", "Godot"]]))

另请参阅 GDScript 格式化字符串教程。

注意:在 C# 中推荐改为使用“$”插入字符串


String get_base_dir ( ) const

如果该字符串是有效的文件路径,则返回基础目录名称。

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

String get_basename ( ) const

如果该字符串是有效的文件路径,则返回完整文件路径,不包括扩展名。

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

String get_extension ( ) const

如果该字符串是有效的文件名或路径,则返回该文件的扩展名,不含开头的点号(.)。否则返回空字符串。

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

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

String get_file ( ) const

如果该字符串是有效的文件路径,则返回文件名,包括扩展名。

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

String get_slice ( String delimiter, int slice ) const

使用分隔符 delimiter 拆分该字符串,返回索引为 slice 的子串。如果 slice 不存在则返回空字符串。

只需要一个子串时这个方法比 split 快。

示例:

print("i/am/example/hi".get_slice("/", 2)) # 输出 "example"

int get_slice_count ( String delimiter ) const

返回使用给定的分隔符 delimiter 拆分该字符串后切片的总数(见 split)。


String get_slicec ( int delimiter, int slice ) const

使用 Unicode 字符码分隔符 delimiter 拆分该字符串,返回索引为 slice 的子串。如果 slice 不存在则返回空字符串。

只需要一个子串时这个方法比 split 快。


int hash ( ) const

返回代表该字符串内容的 32 位哈希值。

注意:由于哈希碰撞的缘故,内容相同的字符串不一定会得到相同的哈希值。而相对的是,哈希不同的字符串一定不同。


PackedByteArray hex_decode ( ) const

将十六进制字符串解码为 PackedByteArra