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" 等)。


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"