# string.regex 库模块帮助文档
正则表达式语法请参考：[preg 扩展库使用指南](https://www.aardio.com/zh-cn/docs/library-guide/ext/preg/_.html)
## string 成员列表 #
### string.regex() #
[返回对象:stringRegexObject](#stringRegexObject)
### string.regex(pattern,flags) #
创建正则表达式。
- 参数 @pattern 使用字符串指定正则表达式。
- 可选用字符串参数 @flags 指定一个或多个修饰符:
* "i" 表示忽略大小写
* "m" 表示启用多行模式（使 `^` 和 `$` 匹配每一行开头结尾）。
* "s" 将参数 @pattern 中的 `.` 自动替换为 `[\s\S]`（模仿 DotAll 单行模式 ）
未指定参数 @flags 时 @pattern 可用内联修饰符或斜杠修饰符格式指定全局修饰符，
例如 `(?s).+` 或 `/.+/s`（不要在一个正则表达式内使用两种不同的格式）。
## string.regex 成员列表 #
正则表达式组件。
string.regex 基于系统自带 VBScript.RegExp，不支持原子分组、命名捕获组等语法。
改用 preg 扩展库可提供更快更强大的正则表达式功能。
aardio 中更建议使用内置的模式匹配（更小更快效率更高，基本语法类似正则表达式）。
### string.regex.find(str,pattern,flags) #
从字符串参数 @str 开头查找参数 @pattern 参数指定的正则表达式。
可选用字符串参数 @flags 指定一个或多个修饰符（"i","m"等）。
匹配失败返回 null，匹配成功返回字符串开始位置与结束位置，按字符个数计数（不是按字节计数）。
正则表达式语法错误会抛出异常。
### string.regex.gmatch(str,pattern,flags) #
从字符串参数 @str 开头尝试全局匹配参数 @pattern 参数指定的正则表达式。
可选用字符串参数 @flags 指定一个或多个修饰符（"i","m"等）。
返回适用于 for in 语句的迭代器。
如果指定了捕获组，每次迭代遍历时都返回一个或多个迭代变量（对应捕获组匹配的字符串）。
如果未指定捕获组，每次迭代遍历时都返回包含完整匹配结果的单个字符串。
正则表达式语法错误会抛出异常。
### string.regex.match(str,pattern,flags) #
从字符串 str 开头尝试匹配 pattern 参数指定的正则表达式。
可选用字符串参数 @flags 指定一个或多个修饰符（"i","m"等）。
匹配失败返回 null，匹配成功返回字符串数组。
如果正则表达式包含捕获组，则返回的数组包含所有捕获组匹配的字符串。
如果未指定捕获组，则返回包含单个字符串的（匹配结果）数组。
返回数组可用 tostring 函数或者连接操作符转换为字符串。
正则表达式语法错误会抛出异常。
示例：
var result = string.regex.match("ABC 123","([a-z]+)\s+(\d+)","i");
print( result[1],result[2])
### string.regex.replace(str,pattern,repl,flags) #
从字符串参数 @str 开头全局替换 @pattern 参数指定正则表达式匹配的字符串。
@repl 参数指定替换字符串，替换参数不能是函数。
可选用字符串参数 @flags 指定一个或多个修饰符（"i","m"等）。
返回替换后的新字符串。
正则表达式语法错误会抛出异常。
### string.regex.test(str,pattern,flags) #
从字符串参数 @str 开头查找参数 @pattern 参数指定的正则表达式。
可选用字符串参数 @flags 指定一个或多个修饰符（"i","m"等）。
匹配失败返回 false，匹配成功返回 true。
正则表达式语法错误会抛出异常。
## stringRegexObject 成员列表 #
### stringRegexObject.find(目标字符串) #
使用正则表达式在字符串参数 @1 内查找字符串。
匹配成功返回字符串开始位置与结束位置，按字符个数计数（不是按字节计数）。
匹配失败返回 null，正则表达式语法错误会抛出异常。
### stringRegexObject.free() #
释放正则表达式对象。
此对象会自动回收，也可以显式调用 free 函数释放。
### stringRegexObject.gmatch(str) #
```aardio
for i,matchObject in regex.gmatch(/*要匹配的字符串*/,".+"){
/*从字符串参数 @1 开头全局匹配 @2 参数指定的正则表达式。
如果不指定参数 @2 则使用创建 string.regex 时指定的默认正则表达式。
迭代变量 i 为索引，迭代变量 matchObject 为 COM 对象 VBScript RegExp Object。
正则表达式语法错误会抛出异常。*/
}
```
使用正则表达式全局匹配字符串 @str 。
返回适用于 for in 语句的迭代器。
如果指定了捕获组，每次迭代遍历时都返回一个或多个迭代变量（对应捕获组匹配的字符串）。
如果未指定捕获组，每次迭代遍历时都返回包含完整匹配结果的单个字符串。
正则表达式语法错误会抛出异常。
### stringRegexObject.ignoreCase #
是否忽略大小写
### stringRegexObject.match(str) #
使用正则表达式在字符串参数 @str 内查找字符串。
匹配失败返回 null，匹配成功返回字符串数组。
如果正则表达式包含捕获组，则返回的数组包含所有捕获组匹配的字符串。
如果未指定捕获组，则返回包含单个字符串的（匹配结果）数组。
返回数组可用 tostring 函数或者连接操作符转换为字符串。
正则表达式语法错误会抛出异常。
### stringRegexObject.multiline #
设为 true，则 `^` 和 `$` 匹配每一行开头结尾，
否则匹配整个字符串的开头和结尾（默认值）
### stringRegexObject.pattern #
设置或返回用于匹配的正则表达式。
注意直接修改此属性时不能在正则表达式中包含修饰符。
### stringRegexObject.replace(str,repl) #
使用正则表达式全局搜索并替换字符串。
@repl 参数指定替换字符串（不能指定为函数对象）。
返回替换后的新字符串。
正则表达式语法错误会抛出异常。
### stringRegexObject.test(目标字符串) #
使用正则表达式在字符串参数 @1 内查找字符串。
匹配失败返回 false，匹配成功返回 true。
正则表达式语法错误会抛出异常。