Up to date

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

String

字符串内置类型。

描述

这是内置的字符串 Variant 类型(GDScript 使用的就是这个类型)。字符串中可以包含任意数量的 Unicode 字符,暴露的方法可用于字符串的操作和生成。字符串有引用计数,使用写时复制技术(每次对字符串的修改都会返回新的 String),所以传递字符串的资源损耗很小。

部分字符串方法有对应的变体。后缀 n 的变体(countnfindnreplacen 等)大小写不敏感(不区分大写字符和小写字符)。前缀 r 的方法变体(rfindrsplit 等)是逆序的,会从字符串末尾开始,而不是从开头开始。

注意:在布尔语境下,空字符串("")的求值结果为 false。否则字符串的求值结果始终为 true。无法使用 not 运算符。检查空字符串请使用 is_empty

备注

通过 C# 使用这个 API 时有显著的不同。详见 C# API 与 GDScript 的差异

教程

构造函数

String

String ( )

String

String ( String from )

String

String ( NodePath from )

String

String ( StringName 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

String

chr ( int char ) static

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

humanize_size ( int size ) static

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

num ( float number, int decimals=-1 ) static

String

num_int64 ( int number, int base=10, bool capitalize_hex=false ) static

String

num_scientific ( float number ) static

String

num_uint64 ( int number, int base=10, bool capitalize_hex=false ) static

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 < ( String right )

bool

operator <= ( String right )

bool

operator == ( String right )

bool

operator == ( StringName right )

bool

operator > ( String right )

bool

operator >= ( String right )

String

operator [] ( int index )


构造函数说明

String String ( )

构造空的 String"")。


String String ( String from )

构造给定 String 的副本。


String String ( NodePath from )

从给定的 NodePath 构造新的 String


String String ( StringName from )

从给定的 StringName 构造新 String


方法说明

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".capitalize()   # 返回 "2d, Fps, Png"

int casecmp_to ( String to ) const

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

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

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


String chr ( int char ) static

根据十进制数 char 返回单一 Unicode 字符。你可以用 unicodelookup.comunicode.org 作为参考。

print(String.chr(65))     # 输出 "A"
print(String.chr(129302)) # 输出 "🤖"(机器人脸 Emoji)

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 的子串。如果字符串中不存在 delimiter 则返回原字符串。如果 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

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

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

int hex_to_int ( ) const

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

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

String humanize_size ( int size ) static

将表示字节数的 size 转换为人类可读的形式。

结果使用 IEC 词头,结尾可能是 "B""KiB""MiB""GiB""TiB""PiB""EiB"


String indent ( String prefix ) const

使用前缀 prefix 将该字符串中的每一行进行缩进。空行不缩进。移除缩进请参阅 dedent

例如,该字符串可以用 "\t\t" 缩进两个制表位,用 "    " 缩进四个空格。


String insert ( int position, String what ) const

在该字符串中的 position 位置插入 what


bool is_absolute_path ( ) const

如果该字符串为文件或目录的路径,并且显式指定了起点,则返回 true。这个方法与 is_relative_path 相反。

包括以 "res://""user://""C:\""/" 等开头的路径。


bool is_empty ( ) const

如果该字符串的长度为 0""),则返回 true。另见 length


bool is_relative_path ( ) const

如果该字符串为文件或目录的路径,并且起点依赖于上下文,则返回 true。路径可以是从当前目录开始,也可以是从当前 Node 开始(如果该字符串是从 NodePath 得到的),有时候也可以是使用了 "./" 前缀。这个方法与 is_absolute_path 相反。


bool is_subsequence_of ( String text ) const

如果这个字符串中的所有字符都能在 text 中按照原始顺序找到,则返回 true

var text = "Wow, incredible!"

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

bool is_subsequence_ofn ( String text ) const

如果这个字符串中的所有字符都能在 text 中按照原始顺序找到,忽略大小写,则返回 true


bool is_valid_filename ( ) const

如果该字符串不包含文件名中不允许的字符,则返回 true(不允许的字符有:: / \ ? * " | % < >)。


bool is_valid_float ( ) const

如果该字符串代表有效的浮点数,则返回 true。浮点数只能包含数字、一个小数点(.)以及指数字符(e)。还可以前缀正号(+)或负号(-)。有效的整数同时也是有效的浮点数(见 is_valid_int)。另见 to_float

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

bool is_valid_hex_number ( bool with_prefix=false ) const

如果该字符串代表有效的十六进制数,则返回 true。有效的十六进制数只能包含数字或字母 AF(大小写均可),还可以前缀正号(+)或负号(-)。

如果 with_prefixtrue,则十六进制数需要有 "0x" 前缀才算有效。

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

print("0xDEADC0DE".is_valid_hex_number(true)) # 输出 true

bool is_valid_html_color ( ) const

如果该字符串是有效的十六进制 HTML 颜色标记,则返回 true。该字符串必须为 3 位、4 位、6 位或 8 位字符的十六进制值(见 is_valid_hex_number),也可以带有井号前缀(#)。名称、hsl() 等其他 HTML 颜色标记法无效。另见 Color.html


bool is_valid_identifier ( ) const

如果该字符串为有效的标识符,则返回 true。有效的标识符仅可以包含字母、数字和下划线(_),第一个字符不能为数字。

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

bool is_valid_int ( ) const

如果该字符串代表有效的整数,则返回 true。有效的整数仅可以包含数字,还可以前缀正号(+)或负号(-)。另见 to_int

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

bool is_valid_ip_address ( ) const

如果该字符串表示格式正确的 IPv4 或 IPv6 地址,则返回 true。这个方法认为 0.0.0.0"ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"保留 IP 地址是有效的。


String join ( PackedStringArray parts ) const

返回将 parts 中的元素连接组成的字符串,元素间使用调用该方法的字符串进行分隔。该方法和 split 相反。

示例:

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

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

String json_escape ( ) const

返回该字符串的副本,使用 JSON 标准对特殊字符进行转义。因为与 C 标准非常类似,所以需要时可以用 c_unescape 取消转义。


String left ( int length ) const

返回该字符串开头的前 length 个字符。如果 length 为负,则会从该字符串的末尾剥离最后 length 个字符。

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

int length ( ) const

返回该字符串中的字符数。空字符串("")始终返回 0。另见 is_empty


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

必要时在该字符串的左侧添加若干 character 字符,使其长度至少为 min_length。另见 rpad


String lstrip ( String chars ) const

从该字符串的开头移除 chars 中定义的字符。另见 rstrip

注意:chars 不是前缀。如果要移除前缀而不是一组字符,请使用 trim_prefix


bool match ( String expr ) const

进行简单的表达式匹配(也叫“通配”),* 匹配零个或多个任意字符,? 匹配除英文句号外的任意字符(.)。使用空字符串或空表达式时始终为 false


bool matchn ( String expr ) const

进行简单的大小写不敏感表达式匹配(也叫“通配”),* 匹配零个或多个任意字符,? 匹配除英文句号外的任意字符(.)。使用空字符串或空表达式时始终为 false


PackedByteArray md5_buffer ( ) const

返回该字符串的 MD5 哈希,类型为 PackedByteArray


String md5_text ( ) const

返回该字符串的 MD5 哈希,类型 String


int naturalcasecmp_to ( String to ) const

与另一个字符串进行不区分大小写自然顺序比较。小于时返回 -1、大于时返回 1、等于时返回 0。“小于”和“大于”比较的是字符串中的 Unicode 码位,大致与字母表顺序一致。内部实现时,会将小写字符转换为大写后进行比较。

使用自然顺序进行排序时,会和常见预期一样将连续的数字进行组合,而不是一个个数字进行比较。排序后的数列为 ["1", "2", "3", ...] 而不是 ["1", "10", "2", "3", ...]

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

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


int naturalnocasecmp_to ( String to ) const

与另一个字符串进行不区分大小写自然顺序比较。小于时返回 -1、大于时返回 1、等于时返回 0。“小于”和“大于”比较的是字符串中的 Unicode 码位,大致与字母表顺序一致。内部实现时,会将小写字符转换为大写后进行比较。

使用自然顺序进行排序时,会和常见预期一样将连续的数字进行组合,而不是一个个数字进行比较。排序后的数列为 ["1", "2", "3", ...] 而不是 ["1", "10", "2", "3", ...]

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

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


int nocasecmp_to ( String to ) const

与另一个字符串进行不区分大小写的比较。小于时返回 -1、大于时返回 1、等于时返回 0。“小于”和“大于”比较的是字符串中的 Unicode 码位,大致与字母表顺序一致。内部实现时,会将小写字符转换为大写后进行比较。

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

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


String num ( float number, int decimals=-1 ) static

float 转换为十进制小数的字符串表示,小数点位数由 decimals 指定。

如果 decimals 为默认的 -1,该字符串表示可能最多只有 14 位有效数字,小数点前的数字优先于小数点后的数字。

该字符串中不包含后缀的零。最后一位数字会四舍五入,而不是截断。

示例:

String.num(3.141593)     # 返回 "3.141593"
String.num(3.141593, 3)  # 返回 "3.142"
String.num(3.14159300)   # 返回 "3.141593"

# 此处的最后一位数字会进位,
# 数字位数会减少,因为后缀的零会被移除:
String.num(42.129999, 5) # 返回 "42.13"

# 如果没有指定 `decimals`,最大有效位数为 14:
String.num(-0.0000012345432123454321)     # 返回 "-0.00000123454321"
String.num(-10000.0000012345432123454321) # 返回 "-10000.0000012345"

String num_int64 ( int number, int base=10, bool capitalize_hex=false ) static

将给定的数字 number 转换为字符串表示,进位制由 base 给定。

默认情况下 base 为十进制(10)。编程中常见的进位制还有二进制(2)、八进制8)、十六进制(16)。

如果 capitalize_hextrue,比 9 大的数位会大写。


String num_scientific ( float number ) static

将给定的数字 number 转换为字符串表示,使用科学记数法。

var n = -5.2e8
print(n)                       # 输出 -520000000
print(String.NumScientific(n)) # 输出 -5.2e+08

注意:这个方法没有在 C# 中实现。要实现类似的效果,见 C# 的标准数字格式字符串


String num_uint64 ( int number, int base=10, bool capitalize_hex=false ) static

将给定的无符号 int 转换为字符串表示,进位制由 base 给定。

默认情况下 base 为十进制(10)。编程中常见的进位制还有二进制(2)、八进制8)、十六进制(16)。

如果 capitalize_hextrue,比 9 大的数位会大写。


String pad_decimals ( int digits ) const

格式化表示数字的字符串,使其小数点的位数为 digits


String pad_zeros ( int digits ) const

格式化表示数字的字符串,使其小数点的位数为 digits


String path_join ( String file ) const

file 作为子路径连接到该字符串的末尾,必要时会添加 /

示例:"this/is".path_join("path") == "this/is/path"


String repeat ( int count ) const

将该字符串重复若干次。次数 count 需要大于0 。否则返回空字符串。


String replace ( String what, String forwhat ) const

将该字符串中出现的所有 what 都替换为给定的 forwhat


String replacen ( String what, String forwhat ) const

将该字符串中出现的所有 what 都替换为给定的 forwhat大小写不敏感


String reverse ( ) const

返回将这个字符串逆序后的副本。


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

返回这个字符串中 what 最后一次出现时的索引,不存在时则为 -1。搜索的起点可以用 from 指定,终点为该字符串的末尾。这个方法与 find 相对。


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

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


String right ( int length ) const

返回该字符串末尾的最后 length 个字符。如果 length 为负,则会从该字符串的开头剥离前 length 个字符。

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

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

必要时在该字符串的右侧添加若干 character 字符,使其长度至少为 min_length。另见 lpad


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

使用分隔符 delimiter 将该字符串从末尾开始进行拆分,返回子字符串数组。返回的数组中,每部分的出现顺序与它们在原字符串中的出现顺序一致。如果 delimiter 为空,则子串为单个字符。

如果 allow_emptyfalse,数组中会排除相邻分隔符之间的空字符串。

如果 maxsplit 大于 0,则拆分次数不能超过 maxsplit。默认拆分整个字符串,基本与 split 一致。

示例:

var some_string = "One,Two,Three,Four"
var some_array = some_string.rsplit(",", true, 1)

print(some_array.size()) # 输出 2
print(some_array[0])     # 输出 "One,Two,Three"
print(some_array[1])     # 输出 "Four"

String rstrip ( String chars ) const

从该字符串的结尾移除 chars 中定义的字符。另见 rstrip

注意:chars 不是后缀。如果要移除后缀而不是一组字符,请使用 trim_suffix


PackedByteArray sha1_buffer ( ) const

返回该字符串的 SHA-1 哈希,类型为 PackedByteArray


String sha1_text ( ) const

返回该字符串的 SHA-1 哈希,类型为 String


PackedByteArray sha256_buffer ( ) const

返回该字符串的 SHA-256 哈希,类型为 PackedByteArray


String sha256_text ( ) const

返回该字符串的 SHA-256 哈希,类型为 String


float similarity ( String text ) const

返回该字符串与另一个字符串的相似指数(索伦森-戴斯系数)。结果为 1.0 表示完全相似,0.0 表示完全不相似。

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

String simplify_path ( ) const

如果该字符串为有效的文件路径,则将其转换为规范路径。规范路径是最短路径,不带 "./" 和所有不必要的 "..""/"

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

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

使用分隔符 delimiter 将该字符串进行拆分,返回子字符串数组。如果 delimiter 为空,则子串为单个字符。这个方法与 join 相对。

如果 allow_emptyfalse,数组中会排除相邻分隔符之间的空字符串。

如果 maxsplit 大于 0,则拆分次数不能超过 maxsplit。默认拆分整个字符串。

示例:

var some_array = "One,Two,Three,Four".split(",", true, 2)

print(some_array.size()) # 输出 3
print(some_array[0])     # 输出 "One"
print(some_array[1])     # 输出 "Two"
print(some_array[2])     # 输出 "Three,Four"

注意:如果你只需要数组中的某一个子串,请考虑使用更快的 get_slice。如果你需要用更复杂的规则来拆分字符串,请改用 RegEx 类。


PackedFloat64Array split_floats ( String delimiter, bool allow_empty=true ) const

使用分隔符 delimiter 将该字符串拆分为浮点数,返回 PackedFloat64Array

如果 allow_emptyfalse,则会排除相邻分隔符之间为空或无法转换为 float 的内容。

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

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

从该字符串的开头和结尾剥离所有不可打印的字符。其中包括空格、制表符(\t)以及换行符(\n \r)。

如果 leftfalse,会忽略该字符串的开头。与此类似,如果 rightfalse,则会忽略该字符串的结尾。


String strip_escapes ( ) const

从该字符串中剥离所有转义字符。其中包括 ASCII 表第一页的所有不可打印控制字符(值为 0 到 32),例如制表符(C 中的 \t)和换行符(\n]\r) 字符,但不包括空格。


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

返回该字符串中的某一部分,位置从 from 开始,长度为 len。如果 len-1(默认值),将返回开给定位置开始的剩余字符。


PackedByteArray to_ascii_buffer ( ) const

将该字符串转换为 ASCII/Latin-1 编码的 PackedByteArray。这个方法比 to_utf8_buffer 稍快,但会把不支持的字符都替换为空格。这是 PackedByteArray.get_string_from_ascii 的逆运算。


String to_camel_case ( ) const

返回将该字符串转换为小驼峰命名 camelCase 的结果。


float to_float ( ) const

将代表十进制数的字符串转换为 float。该方法会在首个非数字字符处停止,除非是首次遇到 .(小数点)以及表示指数的 e。另见 is_valid_float

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

int to_int ( ) const

将代表整数的字符串转换为 int。该方法会删除所有非数字字符,并在遇到 . 后停止。另见 is_valid_int

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

String to_lower ( ) const

返回将该字符串转换为小写 lowercase 的结果。


String to_pascal_case ( ) const

返回将该字符串转换为大驼峰命名 PascalCase 的结果。


String to_snake_case ( ) const

返回将该字符串转换为蛇形命名 snake_case 的结果。

注意:如果数字之后存在的是单个字符,则不会进行拆分,这是为了保证某些单词的连贯(例如“2D”)。

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

String to_upper ( ) const

返回将该字符串转换为大写 UPPERCASE 的结果。


PackedByteArray to_utf8_buffer ( ) const

将该字符串转换为 UTF-8 编码的 PackedByteArray。这个方法比 to_ascii_buffer 稍慢,但支持所有 UTF-8 字符。大多数情况下请优先使用这个方法。这是 PackedByteArray.get_string_from_utf8 的逆运算。


PackedByteArray to_utf16_buffer ( ) const

将该字符串转换为 UTF-16 编码的 PackedByteArray。这是 PackedByteArray.get_string_from_utf16 的逆运算。


PackedByteArray to_utf32_buffer ( ) const

将该字符串转换为 UTF-32 编码的 PackedByteArray。这是 PackedByteArray.get_string_from_utf32 的逆运算。


PackedByteArray to_wchar_buffer ( ) const

将该字符串转换为 宽字符wchat_t,Windows 上为 UTF-16,其他平台上为 UTF-32)编码的 PackedByteArray。这是 PackedByteArray.get_string_from_wchar 的逆运算。


String trim_prefix ( String prefix ) const

移除该字符串开头的 prefix 前缀,否则原样返回该字符串。


String trim_suffix ( String suffix ) const

移除该字符串末尾的 suffix 后缀,否则原样返回该字符串。


int unicode_at ( int at ) const

返回位于 at 处的字符的代码。


String uri_decode ( ) const

将该字符串从 URL 编码格式中解码。该方法的目的是在收到 HTTP 请求时正确解码 URL 中的参数。另见 uri_encode

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

String uri_encode ( ) const

将该字符串按照对 URL 友好的格式进行编码。该方法的目的是在发送 HTTP 请求时,正确编码 URL 中的参数。另见 uri_decode

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

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

String validate_filename ( ) const

返回该字符串的副本,所有 is_valid_filename 中不允许的字符都会被替换为下划线。


String validate_node_name ( ) const

返回该字符串的副本,所有 Node.name 中不允许的字符都会被替换为下划线(. : @ / " %))。


String xml_escape ( bool escape_quotes=false ) const

返回该字符串的副本,使用 XML 标准对特殊字符进行转义。如果 escape_quotestrue,则单引号(')和双引号(")字符也会被转义。


String xml_unescape ( ) const

返回该字符串的副本,转义字符均按照 XML 标准使用本义代替。


操作符说明

bool operator != ( String right )

如果两个字符串不以相同的字符序列开头,则返回 true


bool operator != ( StringName right )

如果该 String 与给定的 StringName 不等价,则返回 true


String operator % ( Variant right )

格式化该 String,使用若干参数替换占位符。要传递多个参数,right 需要为 Array

print("我捉到了 %d 条鱼!" % 2) # 输出 "我捉到了 2 条鱼!"

var my_message = "正在前往 %s,速度为 %2.2f km/h。"
var location = "深谷"
var speed = 40.3485
print(my_message % [location, speed]) # 输出 "正在前往深谷,速度为 40.35 km/h。"

更多信息见《GDScript 格式字符串》教程。

注意:C# 中没有等价的运算符。见如何使用“$”插入字符串


String operator + ( String right )

right 追加到该 String 的末尾,也称作字符串连接。


String operator + ( StringName right )

right 追加到该 String 的末尾,返回 String。也称作字符串连接。


bool operator < ( String right )

如果左侧的 Stringright 靠前,则返回 true。使用的是 Unicode 顺序,大致与字母表顺序一致。可用于排序。


bool operator <= ( String right )

如果左侧的 Stringright 靠前,或两者相等,则返回 true。使用的是 Unicode 顺序,大致与字母表顺序一致。


bool operator == ( String right )

如果两个字符串以相同的字符序列开头,则返回 true


bool operator == ( StringName right )

如果该 String 与给定的 StringName 等价,则返回 true


bool operator > ( String right )

如果左侧的 Stringright 靠后,则返回 true。使用的是 Unicode 顺序,大致与字母表顺序一致。可用于排序。


bool operator >= ( String right )

如果左侧的 Stringright 靠后,或两者相等,则返回 true。使用的是 Unicode 顺序,大致与字母表顺序一致。


String operator [] ( int index )

返回只包含索引为 index 的字符的新 String。索引从 0 开始。如果 index 大于等于 0,则字符是从该字符串的开头开始获取的。如果 index 为负,则从末尾开始获取。越界访问字符串会导致运行时错误,从编辑器中运行时会将项目暂停。