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
的变体(countn、findn、replacen 等)大小写不敏感(不区分大写字符和小写字符)。前缀 r
的方法变体(rfind、rsplit 等)是逆序的,会从字符串末尾开始,而不是从开头开始。
注意:在布尔语境下,空字符串(""
)的求值结果为 false
。否则字符串的求值结果始终为 true
。无法使用 not
运算符。检查空字符串请使用 is_empty。
备注
通过 C# 使用这个 API 时有显著的不同。详见 C# API 与 GDScript 的差异。
教程¶
构造函数¶
String ( ) |
|
String ( StringName from ) |
方法¶
begins_with ( String text ) const |
|
bigrams ( ) const |
|
bin_to_int ( ) const |
|
c_escape ( ) const |
|
c_unescape ( ) const |
|
capitalize ( ) const |
|
casecmp_to ( String to ) const |
|
dedent ( ) const |
|
get_base_dir ( ) const |
|
get_basename ( ) const |
|
get_extension ( ) const |
|
get_file ( ) const |
|
get_slice_count ( String delimiter ) const |
|
get_slicec ( int delimiter, int slice ) const |
|
hash ( ) const |
|
hex_decode ( ) const |
|
hex_to_int ( ) const |
|
humanize_size ( int size ) static |
|
is_absolute_path ( ) const |
|
is_empty ( ) const |
|
is_relative_path ( ) const |
|
is_subsequence_of ( String text ) const |
|
is_subsequence_ofn ( String text ) const |
|
is_valid_filename ( ) const |
|
is_valid_float ( ) const |
|
is_valid_hex_number ( bool with_prefix=false ) const |
|
is_valid_html_color ( ) const |
|
is_valid_identifier ( ) const |
|
is_valid_int ( ) const |
|
is_valid_ip_address ( ) const |
|
join ( PackedStringArray parts ) const |
|
json_escape ( ) const |
|
length ( ) const |
|
md5_buffer ( ) const |
|
md5_text ( ) const |
|
naturalcasecmp_to ( String to ) const |
|
naturalnocasecmp_to ( String to ) const |
|
nocasecmp_to ( String to ) const |
|
num_int64 ( int number, int base=10, bool capitalize_hex=false ) static |
|
num_scientific ( float number ) static |
|
num_uint64 ( int number, int base=10, bool capitalize_hex=false ) static |
|
pad_decimals ( int digits ) const |
|
reverse ( ) const |
|
rsplit ( String delimiter="", bool allow_empty=true, int maxsplit=0 ) const |
|
sha1_buffer ( ) const |
|
sha1_text ( ) const |
|
sha256_buffer ( ) const |
|
sha256_text ( ) const |
|
similarity ( String text ) const |
|
simplify_path ( ) const |
|
split ( String delimiter="", bool allow_empty=true, int maxsplit=0 ) const |
|
split_floats ( String delimiter, bool allow_empty=true ) const |
|
strip_edges ( bool left=true, bool right=true ) const |
|
strip_escapes ( ) const |
|
to_ascii_buffer ( ) const |
|
to_camel_case ( ) const |
|
to_float ( ) const |
|
to_int ( ) const |
|
to_lower ( ) const |
|
to_pascal_case ( ) const |
|
to_snake_case ( ) const |
|
to_upper ( ) const |
|
to_utf8_buffer ( ) const |
|
to_utf16_buffer ( ) const |
|
to_utf32_buffer ( ) const |
|
to_wchar_buffer ( ) const |
|
trim_prefix ( String prefix ) const |
|
trim_suffix ( String suffix ) const |
|
unicode_at ( int at ) const |
|
uri_decode ( ) const |
|
uri_encode ( ) const |
|
validate_filename ( ) const |
|
validate_node_name ( ) const |
|
xml_escape ( bool escape_quotes=false ) const |
|
xml_unescape ( ) const |
操作符¶
operator != ( String right ) |
|
operator != ( StringName right ) |
|
operator % ( Variant right ) |
|
operator + ( String right ) |
|
operator + ( StringName right ) |
|
operator < ( String right ) |
|
operator <= ( String right ) |
|
operator == ( String right ) |
|
operator == ( StringName right ) |
|
operator > ( String right ) |
|
operator >= ( String right ) |
|
operator [] ( int index ) |
构造函数说明¶
String String ( )
构造空的 String(""
)。
构造给定 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
GD.Print("101".BinToInt()); // 输出 5
GD.Print("0b101".BinToInt()); // 输出 5
GD.Print("-0b10".BinToInt()); // 输出 -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"
"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_to、naturalcasecmp_to 和 naturalnocasecmp_to。
String chr ( int char ) static
根据十进制数 char
返回单一 Unicode 字符。你可以用 unicodelookup.com 和 unicode.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
GD.Print("Node".Contains("de")); // 输出 true
GD.Print("team".Contains("I")); // 输出 false
如果想要知道 what
在该字符串中的位置,请使用 find。
int count ( String what, int from=0, int to=0 ) const
返回子串 what
在 from
和 to
位置之间出现的次数。如果 to
为 0,会在剩余字符串中继续搜索。
int countn ( String what, int from=0, int to=0 ) const
返回子串 what
在 from
和 to
位置之间出现的次数,忽略大小写。如果 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
超过字符串的长度,返回的字符串中擦除的字符数会少于请求的数量。如果 position
或 chars
为负数,则返回空字符串。如果 chars
为 0
则返回原字符串,不进行修改。
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
GD.Print("Team".Find("I")); // 输出 -1
GD.Print("Potato".Find("t")); // 输出 2
GD.Print("Potato".Find("t", 3)); // 输出 4
GD.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
可以是 Dictionary 或 Array。placeholder
中的任何下划线将被预先被替换为对应的键。数组元素使用它们的索引作为键。
# 输出: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"}))
当 values
是 Array 时还会执行一些额外的处理。 如果 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"