String

String

内置字符串类。

描述

这是内置的字符串类（也是 GDScript 所使用的字符串类）。它支持 Unicode，提供了处理字符串的所有必要手段。字符串进行了引用计数，实现了写时复制，所以在资源中进行传递的成本很低。

教程

GDScript 格式字符串

方法

String	String ( bool from )
String	String ( int from )
String	String ( float from )
String	String ( Vector2 from )
String	String ( Rect2 from )
String	String ( Vector3 from )
String	String ( Transform2D from )
String	String ( Plane from )
String	String ( Quat from )
String	String ( AABB from )
String	String ( Basis from )
String	String ( Transform from )
String	String ( Color from )
String	String ( NodePath from )
String	String ( RID from )
String	String ( Dictionary from )
String	String ( Array from )
String	String ( PoolByteArray from )
String	String ( PoolIntArray from )
String	String ( PoolRealArray from )
String	String ( PoolStringArray from )
String	String ( PoolVector2Array from )
String	String ( PoolVector3Array from )
String	String ( PoolColorArray from )
bool	beginswith ( String text )
PoolStringArray	bigrams ( )
String	c_escape ( )
String	c_unescape ( )
String	capitalize ( )
int	casecmp_to ( String to )
int	count ( String what, int from=0, int to=0 )
int	countn ( String what, int from=0, int to=0 )
String	dedent ( )
bool	empty ( )
bool	ends_with ( String text )
void	erase ( int position, int chars )
int	find ( String what, int from=0 )
int	find_last ( String what )
int	findn ( String what, int from=0 )
String	format ( Variant values, String placeholder=”{}” )
String	get_base_dir ( )
String	get_basename ( )
String	get_extension ( )
String	get_file ( )
String	get_slice ( String delimiter, int slice )
int	hash ( )
int	hex_to_int ( )
String	http_escape ( )
String	http_unescape ( )
String	humanize_size ( int size )
String	indent ( String prefix )
String	insert ( int position, String what )
bool	is_abs_path ( )
bool	is_rel_path ( )
bool	is_subsequence_of ( String text )
bool	is_subsequence_ofi ( String text )
bool	is_valid_filename ( )
bool	is_valid_float ( )
bool	is_valid_hex_number ( bool with_prefix=false )
bool	is_valid_html_color ( )
bool	is_valid_identifier ( )
bool	is_valid_integer ( )
bool	is_valid_ip_address ( )
String	json_escape ( )
String	left ( int position )
int	length ( )
String	lstrip ( String chars )
bool	match ( String expr )
bool	matchn ( String expr )
PoolByteArray	md5_buffer ( )
String	md5_text ( )
int	naturalnocasecmp_to ( String to )
int	nocasecmp_to ( String to )
int	ord_at ( int at )
String	pad_decimals ( int digits )
String	pad_zeros ( int digits )
String	percent_decode ( )
String	percent_encode ( )
String	plus_file ( String file )
String	repeat ( int count )
String	replace ( String what, String forwhat )
String	replacen ( String what, String forwhat )
int	rfind ( String what, int from=-1 )
int	rfindn ( String what, int from=-1 )
String	right ( int position )
PoolStringArray	rsplit ( String delimiter, bool allow_empty=true, int maxsplit=0 )
String	rstrip ( String chars )
PoolByteArray	sha1_buffer ( )
String	sha1_text ( )
PoolByteArray	sha256_buffer ( )
String	sha256_text ( )
float	similarity ( String text )
String	simplify_path ( )
PoolStringArray	split ( String delimiter, bool allow_empty=true, int maxsplit=0 )
PoolRealArray	split_floats ( String delimiter, bool allow_empty=true )
String	strip_edges ( bool left=true, bool right=true )
String	strip_escapes ( )
String	substr ( int from, int len=-1 )
PoolByteArray	to_ascii ( )
float	to_float ( )
int	to_int ( )
String	to_lower ( )
String	to_upper ( )
PoolByteArray	to_utf8 ( )
PoolByteArray	to_wchar ( )
String	trim_prefix ( String prefix )
String	trim_suffix ( String suffix )
String	validate_node_name ( )
String	xml_escape ( )
String	xml_unescape ( )

方法说明

String String ( bool from )

从给定的 bool 构造新 String。

String String ( int from )

从给定的 int 构造新 String。

String String ( float from )

从给定的 float 构造新 String。

String String ( Vector2 from )

从给定的 Vector2 构造新 String。

String String ( Rect2 from )

从给定的 Rect2 构造新 String。

String String ( Vector3 from )

从给定的 Vector3 构造新 String。

String String ( Transform2D from )

从给定的 Transform2D 构造新 String。

String String ( Plane from )

从给定的 Plane 构造新 String。

String String ( Quat from )

从给定的 Quat 构造新 String。

String String ( AABB from )

从给定的 AABB 构造新 String。

String String ( Basis from )

从给定的 Basis 构造新 String。

String String ( Transform from )

从给定的 Transform 构造新 String。

String String ( Color from )

从给定的 Color 构造新 String。

String String ( NodePath from )

从给定的 NodePath 构造新 String。

String String ( RID from )

从给定的 RID 构造新 String。

String String ( Dictionary from )

从给定的 Dictionary 构造新 String。

String String ( Array from )

从给定的 Array 构造新 String。

String String ( PoolByteArray from )

从给定的 PoolByteArray 构造新 String。

String String ( PoolIntArray from )

从给定的 PoolIntArray 构造新 String。

String String ( PoolRealArray from )

从给定的 PoolRealArray 构造新 String。

String String ( PoolStringArray from )

从给定的 PoolStringArray 构造新 String。

String String ( PoolVector2Array from )

从给定的 PoolVector2Array 构造新 String。

String String ( PoolVector3Array from )

从给定的 PoolVector3Array 构造新 String。

String String ( PoolColorArray from )

从给定的 PoolColorArray 构造新 String。

bool begins_with ( String text )

该字符串以指定字符串开头时，返回 true。

PoolStringArray bigrams ( )

返回此字符串的二元组（连续字母对）。

String c_escape ( )

返回一个使用C语言标准转义的特殊字符的字符串的副本。

String c_unescape ( )

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.

String capitalize ( )

更改某些字母的大小写。用空格替换下划线，在词内大写字符之前添加空格，将所有字母转换为小写，然后将第一个字母和空格字符后面的每个字母大写。对于capitalize camelCase mixed_with_underscores，它将返回Capitalize Camel Case Mixed With Underscores。

int casecmp_to ( String to )

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

字符串长度不同时的行为： “基准”字符串比 to 字符串长时返回 -1，“基准”字符串比 to 字符串短时返回 -1。请注意此处的长度为 Unicode 码位的长度，不是实际的可见字符。

存在空字符串的行为： “基准”字符串为空时返回 -1，字符串 to 为空时返回 1，两者都为空时返回 0。

如果想在比较字符串时获得布尔型的返回值，请使用 == 运算符。参阅 nocasecmp_to。

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

返回子串 what 在 from 和 to 位置之间出现的次数。如果 from 和 to 等于 0，则将使用整个字符串。如果只有 to 等于 0，则将使用剩余的子串。

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

返回子串 what（忽略大小写）在 from 和 to 位置之间出现的次数。如果 from 和 to 等于 0，则将使用整个字符串。如果只有 to 等于 0，则将使用剩余的子串。

String dedent ( )

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

bool empty ( )

该字符串的长度为 0 时，返回 true。

bool ends_with ( String text )

该字符串以指定字符串结尾时，返回 true。

void erase ( int position, int chars )

从该字符串的 position 位置开始，擦除 chars 个字符。

int find ( String what, int from=0 )

查找首次出现的子字符串。返回该子字符串的起始位置，未找到时则返回 -1。还可以传入查找的起始位置。

注意： 如果只想知道字符串是否包含子字符串，请使用 in 运算符，如下所示：

# 判断结果将为 `false`。
if "i" in "team":
    pass

int find_last ( String what )

查找最后一次出现的子字符串。如果未找到，则返回子字符串的起始位置或 -1。

int findn ( String what, int from=0 )

查找子字符串的第一次出现，忽略大小写。如果未找到，则返回子字符串的起始位置或 -1。或者，可以传递初始搜索索引。

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

格式化字符串，将所有的 placeholder 替换为 values。

String get_base_dir ( )

字符串为有效文件路径时，返回基础目录名。

String get_basename ( )

字符串为有效文件路径时，返回完整的文件路径，不带扩展名。

String get_extension ( )

如果字符串是一个有效的文件名或路径，返回不带句点的扩展名（.）。如果字符串不包含扩展名，则返回一个空字符串。

print("/path/to/file.txt".get_extension())  # "txt"
print("file.txt".get_extension())  # "txt"
print("file.sample.txt".get_extension())  # "txt"
print(".txt".get_extension())  # "txt"
print("file.txt.".get_extension())  # "" (空字符串)
print("file.txt..".get_extension())  # "" (空字符串)
print("txt".get_extension())  # "" (空字符串)
print("".get_extension())  # "" (空字符串)

String get_file ( )

字符串为有效文件路径时，返回文件名。

String get_slice ( String delimiter, int slice )

Splits a string using a delimiter and returns a substring at index slice. Returns an empty string if the index doesn’t exist.

This is a more performant alternative to split for cases when you need only one element from the array at a fixed index.

Example:

print("i/am/example/string".get_slice("/", 2)) # Prints 'example'.

int hash ( )

以32位整数形式返回字符串的哈希值。

int hex_to_int ( )

将包含十六进制数的字符串转换为整数。十六进制字符串应以“0x”为前缀，否则返回 0。

print("0xff".hex_to_int()) # 打印 "255"

String http_escape ( )

对字符串进行转义（编码），使之成为适合URL的格式。也被称为 “URL编码”。

print("https://example.org/?escaped=" + "Godot Engine:'docs'".http_escape())

String http_unescape ( )

解除（解码）一个URL编码格式的字符串。也被称为 “URL解码”。

print("https://example.org/?escaped=" + "Godot%20Engine%3A%27docs%27".http_unescape())

String humanize_size ( int size )

将以字节数表示的大小转换为人类可读的格式，使用国际化的数据大小单位集，即。B, KiB, MiB, GiB, TiB, PiB, EiB。请注意，下一个最小的单位是自动挑选的，最多可容纳1024个单位。

var bytes = 133790307
var size = String.humanize_size(bytes)
print(size) # 打印 "127.5 MiB"

String indent ( String prefix )

Returns a copy of the string with lines indented with prefix.

For example, the string can be indented with two tabs using "\t\t", or four spaces using " ". The prefix can be any string so it can also be used to comment out strings with e.g. "# ". See also dedent to remove indentation.

Note: Empty lines are kept empty.

String insert ( int position, String what )

返回在给定位置插入子字符串 what 后的字符串副本。

bool is_abs_path ( )

如果字符串是文件或目录的路径，且路径是绝对路径，则返回 true。

bool is_rel_path ( )

如果字符串是文件或目录的路径，且路径是相对的，则返回 true。

bool is_subsequence_of ( String text )

该字符串为指定字符串的子串时，返回 true。

bool is_subsequence_ofi ( String text )

不考虑大小写的前提下，该字符串为指定字符串的子串时，返回 true。

bool is_valid_filename ( )

该字符串不包含文件名中所禁止的字符时，返回 true。禁止的字符有：

: / \ ? * " | % < >

bool is_valid_float ( )

该字符串包含有效浮点数时，返回 true。

bool is_valid_hex_number ( bool with_prefix=false )

该字符串包含有效十六进制数时，返回 true。如果 with_prefix 为 true，则有效的十六进制数还需要包含 0x 前缀，例如：0xDEADC0DE。

bool is_valid_html_color ( )

该字符串包含有效 HTML 十六进制颜色记号时，返回 true。本方法认为具名颜色以及 hsl() 颜色等其他 HTML 记号无效，会返回 false。

bool is_valid_identifier ( )

该字符串为有效标识符时，返回 true。有效标识符仅能够包含字母、数字、下划线（_），并且不能以数字开头。

bool is_valid_integer ( )

该字符串包含有效整数时，返回 true。

bool is_valid_ip_address ( )

如果此字符串仅包含格式正确的 IPv4 或 IPv6 地址，则返回 true。该方法认为保留IP地址如0.0.0.0是有效的。

String json_escape ( )

返回一个使用JSON标准转义的特殊字符的字符串的副本。

String left ( int position )

返回该字符串自左侧起的若干个字符。

int length ( )

返回字符串的字符数。

String lstrip ( String chars )

返回该字符串从左侧删除若干字符后的副本。参数 chars 为包含所需删除字符的字符串。

注意： chars 不是前缀。如果不想删除一组字符，而是想删除单一的前缀字符串，请参阅 trim_prefix。

bool match ( String expr )

判断表达式是否匹配(区分大小写)，其中 "*" 匹配零个或多个任意字符并且 "?" 匹配除句点( "." ）外的任意字符。

bool matchn ( String expr )

判断表达式是否匹配(不区分大小写)，其中 "*" 匹配零个或多个任意字符并且 "?" 匹配除句点( "." ）外的任意字符。

PoolByteArray md5_buffer ( )

以一个字节数组的形式返回字符串的MD5哈希值。

String md5_text ( )

以一个字符串的形式返回字符串的MD5哈希值。

int naturalnocasecmp_to ( String to )

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

使用自然顺序进行排序时，对连续数字的排序符合大多数人的预期。使用自然顺序对 1 到 10 进行排序后，会得到 [1, 2, 3, ...] 而不是 [1, 10, 2, 3, ...]。

存在空字符串的行为： “基准”字符串为空时返回 -1，字符串 to 为空时返回 1，两者都为空时返回 0。

如果想在比较字符串时获得布尔型的返回值，请使用 == 运算符。参阅 casecmp_to。

int nocasecmp_to ( String to )

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

存在空字符串的行为： “基准”字符串为空时返回 -1，字符串 to 为空时返回 1，两者都为空时返回 0。

如果想在比较字符串时获得布尔型的返回值，请使用 == 运算符。参阅 casecmp_to。

int ord_at ( int at )

返回 at 处的字符代码。

String pad_decimals ( int digits )

格式化数字，在小数点后具有 digits 的确切数字。

String pad_zeros ( int digits )

格式化数字，在小数点前具有 digits 的确切数字。

String percent_decode ( )

解码一个百分比编码的字符串。参阅percent_encode。

String percent_encode ( )

对字符串进行百分比编码。发送 HTTP GET 请求（以及表单 urlencoded POST 请求的主体）时在 URL 中编码参数。

String plus_file ( String file )

如果字符串是路径，则在字符串末尾连接 file 作为子路径。例如。 "this/is".plus_file("path") == "this/is/path"。

String repeat ( int count )

返回重复多次的原始字符串。重复次数由参数给出。

String replace ( String what, String forwhat )

将出现的子字符串替换为字符串中给定的子字符串，区分大小写。

String replacen ( String what, String forwhat )

将出现的子字符串替换为字符串中给定的子字符串，不区分大小写。

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

执行子字符串搜索，区分大小写。不过是从字符串末尾开始搜索，而不是开头。

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

执行子字符串搜索，不区分大小写。不过是从字符串末尾开始搜索，而不是开头。

String right ( int position )

返回该字符串指定位置右侧的内容。

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

从右侧开始，通过 delimiter 字符串拆分字符串并返回子字符串数组。

返回数组中的拆分按与原始字符串相同的顺序从左到右排序。

如果指定了 maxsplit，它定义了从右边到 maxsplit 的分割数。默认值 0 表示所有项目都被拆分，因此给出与 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]) # 打印 "Four"
print(some_array[1]) # 打印 "Three,Two,One"

String rstrip ( String chars )

返回该字符串从右侧删除若干字符后的副本。参数 chars 为包含所需删除字符的字符串。

注意： chars 不是后缀。如果不想删除一组字符，而是想删除单一的前缀字符串，请参阅 trim_suffix。

PoolByteArray sha1_buffer ( )

以字节数组的形式返回字符串的 SHA-1 哈希值。

String sha1_text ( )

以字符串形式返回字符串的 SHA-1 哈希值。

PoolByteArray sha256_buffer ( )

以字节数组的形式返回字符串的 SHA-256 哈希值。

String sha256_text ( )

以字符串形式返回字符串的 SHA-256 哈希值。

float similarity ( String text )

返回与此字符串相比的文本的相似度指数。 1表示完全相似，0表示完全不同。

String simplify_path ( )

返回简化的规范路径。

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

Splits the string by a delimiter string and returns an array of the substrings. The delimiter can be of any length.

If maxsplit is specified, it defines the number of splits to do from the left up to maxsplit. The default value of 0 means that all items are split.

If you need only one element from the array at a specific index, get_slice is a more performant option.

Example:

var some_string = "One,Two,Three,Four"
var some_array = some_string.split(",", true, 1)
print(some_array.size()) # Prints 2
print(some_array[0]) # Prints "One"
print(some_array[1]) # Prints "Two,Three,Four"

If you need to split strings with more complex rules, use the RegEx class instead.

PoolRealArray split_floats ( String delimiter, bool allow_empty=true )

使用分隔符字符串将字符串拆分为浮点数，并返回子字符串数组。

例如，如果被 "," 分割，"1,2.5,3" 将返回 [1,2.5,3] 。

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

返回在开头和结尾去除了任何不可打印字符（包括制表符、空格和换行符）的字符串的副本。可选参数分别用于切换左右边缘的删除。

String strip_escapes ( )

Returns a copy of the string stripped of any escape character. These include all non-printable control characters of the first page of the ASCII table (< 32), such as tabulation (\t in C) and newline (\n and \r) characters, but not spaces.

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

从 from 返回字符串的一部分，长度为 len。参数 len 是可选的，使用 -1 将返回给定位置的剩余字符。

PoolByteArray to_ascii ( )

将 String（字符数组）转换为 PoolByteArray（字节数组）。与 to_utf8 相比，转换速度更快，因为此方法假定 String 中的所有字符都是 ASCII 字符。

float to_float ( )

将包含十进制数的字符串转换为 float。

int to_int ( )

将包含整数的字符串转换为 int。

String to_lower ( )

返回转换为小写的字符串。

String to_upper ( )

返回转换为大写的字符串。

PoolByteArray to_utf8 ( )

将字符串（字符数组）转换为 PoolByteArray（字节数组）。转换比 to_ascii 慢一点，但支持所有 UTF-8 字符。因此，您应该更喜欢这个函数而不是 to_ascii。

PoolByteArray to_wchar ( )

将字符串（字符的数组）转换为 PoolByteArray（字节的数组）。

String trim_prefix ( String prefix )

如果以一个给定的字符串为开头，则从该字符串中删除，或者不改变该字符串。

String trim_suffix ( String suffix )

如果以一个给定的字符串为结尾，则从该字符串中删除，或者不改变该字符串。

String validate_node_name ( )

从字符串中删除所有不允许在 Node 名称中出现的字符（. : @ / "）。

String xml_escape ( )

返回带有使用 XML 标准转义的特殊字符的字符串的副本。

String xml_unescape ( )

返回根据 XML 标准将转义字符替换为其含义的字符串副本。