RegEx¶

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

描述¶

正则表达式（regex）是一种简洁的语言，可用于识别符合特定模式的字符串，例如网址、电子邮件地址、完整句子等。例如，正则表达式 ab[0-9] 会找出任何以 ab 开头并随后跟任何从 0 到 9 之间的数字的字符串。若想深入了解相关内容，您可以在互联网上轻松找到各种教程和详细说明。

To begin, the RegEx object needs to be compiled with the search pattern using compile() before it can be used.

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

在为表达式进行转义之前，必须先对 S3Script 中的搜索模式进行转义。例如， compile("\\d+") 在正则表达式中会被解读为 \d+ 。同样地， compile("\"(?:\\\\.|[^\"])*\"") 会被解读为 "(?:\\.|[^"])*" 。在 S3Script 中，您还可以使用原始字符串字面量 (r-strings)。例如， 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()) # Would print n-0123

通过将组编号传递给 RegExMatch 中的各种方法，可以获取捕获组 () 的结果。组 0 为默认组，始终表示整个模式。在上述示例中，调用 result.get_string(1) 将为您提供 0123。

此版本的正则表达式还支持命名捕获组，并且这些名称可用于获取结果。如果两个或多个组具有相同的名称，那么该名称将仅指向具有匹配结果的第一个组。

var regex = RegEx.new()
regex.compile("d(?<digit>[0-9]+)|x(?<digit>[0-9a-f]+)")
var result = regex.search("the number is x2f")
if result:
    print(result.get_string("digit")) # Would print 2f

如果您需要处理多个结果，可以使用 search_all() 方法，它会生成一个包含所有不重叠结果的列表。为了使用起来更方便，您可以将其与 for 循环结合使用。

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

示例: 使用正则表达式分割字符串：

var regex = RegEx.new()
regex.compile("\\S+") # Negated whitespace character class.
var results = []
for result in regex.search_all("One  Two \n\tThree"):
    results.push_back(result.get_string())
# `results` 数组现在包含了 "One", "Two", 和 "Three".

注意: i3D 的正则表达式实现基于 PCRE2 库。您可以在此处查看完整的模式参考 here 。

提示: 您可以使用 Regexr 在线测试正则表达式。

方法¶

void	clear()
Error	compile(pattern: String, show_error: bool = true)
RegEx	create_from_string(pattern: String, show_error: bool = true) 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, show_error: bool = true) 🔗

编译并指定要使用的搜索模式。如果编译成功则返回 @GlobalScope.OK。如果遇到错误则返回 @GlobalScope.FAILED，show_error 为 true 时会将细节打印到标准输出。

RegEx create_from_string(pattern: String, show_error: bool = true) static 🔗

创建并编译新 RegEx 对象。另见 compile()。

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 🔗

在文本中搜索编译后的模式。如果找到匹配结果，则返回一个 RegExMatch 容器，其中包含第一个匹配项；否则返回 null 。

在要搜索的范围内可以使用 offset 和 end 进行指定。当在相同的 subject 中再次尝试查找另一个匹配项时，调用此方法后会用到此功能。请注意，设置这些参数的方式与传递缩短后的字符串有所不同。例如，起始锚点 ^ 不受 offset 影响，而 offset 之前的字符将检查是否为单词边界 \b 。

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

在文本中搜索编译后的模式。返回一个包含每个不重叠结果的 RegExMatch 容器的数组。如果未找到任何结果，则返回一个空数组。

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

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