Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

RegEx

继承： RefCounted < Object

使用正则表达式搜索文本的类。

描述

正则表达式（或称 regex）是一种紧凑的语言，可用于识别遵循特定模式的字符串，如 URL、电子邮件地址、完整句子等。例如正则表达式 ab[0-9] 可以找到 ab 后面跟着 0 到 9 的任何数字的字符串。要想更深入地了解，你可以很容易地在互联网上找到各种教程和详细解释。

首先，在使用 RegEx 对象之前，需要用 compile 对其进行搜索模式的编译。

var regex = RegEx.new()
regex.compile("\\w-(\\d+)")

在为表达式转义之前，必须先为 GDScript 转义搜索模式。例如，compile("\\d+") 会被 RegEx 读成 \d+。同样，compile("\"(?:\\\\.|[^\"])*\") 会被读作 "(?:\.|[^"])*"。在 GDScript 中，你还可以使用原始字符串文字（r-字符串）。例如，compile(r'"(?:\\.|[^"])*"') 将被读取为相同的。

使用 search，你可以在给定的文本中匹配模式。如果匹配到一个模式，将返回 RegExMatch，你可以使用 RegExMatch.get_string 和 RegExMatch.get_start 等方法检索结果的细节。

var regex = RegEx.new()
regex.compile("\\w-(\\d+)")
var result = regex.search("abc n-0123")
if result:
    print(result.get_string()) # 会输出 n-0123

捕获组的结果 () 可以通过向 RegExMatch 中的各种方法传递组号来检索。默认是组 0，并且将总是指整个模式。在上面的例子中，调用 result.get_string(1) 会得到 0123。

这个版本的 RegEx 也支持命名的捕获组，名称可以用来检索结果。如果两个或更多的组有相同的名称，那么这个名称将只指第一个有匹配的组。

var regex = RegEx.new()
regex.compile("d(?<digit>[0-9]+)|x(?<digit>[0-9a-f]+)")
var result = regex.search("数字是 x2f")
if result:
    print(result.get_string("digit")) # 会输出 2f

如果你需要处理多个结果，search_all 会生成一个所有不重叠的结果列表。为了方便起见，这可以和一个 for 循环结合起来。

for result in regex.search_all("d01, d03, d0c, x3f and x42"):
    print(result.get_string("digit"))
# 会输出 01 03 0 3f 42

使用 RegEx 分割字符串的例子：

var regex = RegEx.new()
regex.compile("\\S+") # 非空白字符类。
var results = []
for result in regex.search_all("One  Two \n\tThree"):
    results.push_back(result.get_string())
# `results` 数组包含 "One"、"Two"、"Three"。

注意：Godot 的 regex 实现基于的是 PCRE2。你可以查看完整的模式参考这里。

提示：你可以使用 Regexr 来在线测试正则表达式。

方法

void

clear()

Error

compile(pattern: String)

RegEx

create_from_string(pattern: String) static

int

get_group_count() const

PackedStringArray

get_names() const

String

get_pattern() const

bool

is_valid() const

RegExMatch

search(subject: String, offset: int = 0, end: int = -1) const

Array[RegExMatch]

search_all(subject: String, offset: int = 0, end: int = -1) const

String

sub(subject: String, replacement: String, all: bool = false, offset: int = 0, end: int = -1) const

方法说明

void clear() 🔗

这个方法重置了对象的状态，就像它是新创建的一样。也就是说，它取消了这个对象的正则表达式的赋值。

Error compile(pattern: String) 🔗

编译并指定要使用的搜索模式。如果编译成功，返回 @GlobalScope.OK。如果遇到错误，细节将被打印到标准输出，并返回一个错误。

RegEx create_from_string(pattern: String) static 🔗

创建并编译新 RegEx 对象。

int get_group_count() const 🔗

返回编译模式中捕获组的数量。

PackedStringArray get_names() const 🔗

返回一个数组，该数组是编译模式中命名的捕获组的名称。它们是按外观排序的。

String get_pattern() const 🔗

返回被编译的原始搜索模式。

bool is_valid() const 🔗

返回此对象是否分配了有效的搜索模式。

在文本中搜索编译后的模式。如果找到，则将首个匹配结果放在 RegExMatch 容器中返回，否则返回 null。

可以使用 offset 和 end 指定要搜索的区域。这对在上一次成功后再次调用该方法，以相同的 subject 搜索另一个匹配项时很有用。请注意，设置这些参数不同于传递缩短后的字符串。例如，起始锚点 ^ 不受 offset 的影响，会为单词边界 \b 检查 offset 之前的字符。

Array[RegExMatch] search_all(subject: String, offset: int = 0, end: int = -1) const 🔗

在文本中搜索编译后的模式。返回 RegExMatch 容器的数组，其中每个容器包含的是互不重叠的匹配结果。如果没有找到结果，则返回一个空数组。

可以使用 offset 和 end 指定要搜索的区域。这对在上一次成功后再次调用该方法，以相同的 subject 搜索另一个匹配项时很有用。请注意，设置这些参数不同于传递缩短后的字符串。例如，起始锚点 ^ 不受 offset 的影响，会为单词边界 \b 检查 offset 之前的字符。

String sub(subject: String, replacement: String, all: bool = false, offset: int = 0, end: int = -1) const 🔗

在文本中搜索编译后的模式，并将其替换为指定的字符串。诸如 $1 和 $name 等转义和反向引用会被扩展和解析。默认情况下，只有第一个实例被替换，但可以修改为针对所有实例（全局替换）。

可以使用 offset 和 end 指定要搜索的区域。这对在上一次成功后再次调用该方法，以相同的 subject 搜索另一个匹配项时很有用。请注意，设置这些参数不同于传递缩短后的字符串。例如，起始锚点 ^ 不受 offset 的影响，会为单词边界 \b 检查 offset 之前的字符。