# RegExMatch() [v1.0.45+]

确定一个字符串中所包含的匹配模式 (即：正则表达式)。

FoundPos := RegExMatch(Haystack, NeedleRegEx [, UnquotedOutputVar = "", StartingPosition = 1])

#### 参数

FoundPos | RegExMatch() 返回从源字符串 Haystack 最左边开始找到的第一个匹配 NeedleRegEx 模式的位置。首字符的位置是 1 。要是在字符串中没有找到匹配模式的时候就会返回 0。如果出现了错误 (比如：正则表达式 NeedleRegEx 的语法错误)，它将会返回一个空的字符串和 ErrorLevel 。ErrorLevel 将是 下面 值中的一个，包括 0。
Haystack | 源字符串。
NeedleRegEx | 这种匹配模式是和 Perl 兼容的正则表达式 (PCRE) 。如果有必要的话，可以在正则表达式前加上 选项 ，并以 ")" 结束。例如：这个匹配模式 "i)abc.*123" 将匹配不区分大小写的 "abc" ，中间可以是任何字符，并以 123 结尾的模式进行搜索。要是没有 选项 ，这个 ")" 是可选的，例如： ")abc" 就等同于 "abc" 。
UnquotedOutputVar | 形式1 (默认)：OutputVar 是 unquoted 的一个变量名，它将存储 Haystack 中符合匹配模式的那一部分字符串。如果没有找到符合这个模式的子串 (那么，RegExMatch() 将返回 0 )，而输出变量和所有的数组元素将被置为空。 如果在 NeedleRegEx 中包含 捕捉子模式 ，那么它们将存储在以 OutputVar 为基变量的 数组 里。例如：输出的变量名是 Match ，那它第一个能匹配子模式的子串将存储在 Match1 ，第二个存储在 Macth2 ，等等。有一个例外是 命名子模式 ：它用名字代替了数字的形式来存储。例如：这种模式 (?P<Year>\d{4}) ，会把输出的子串存储在 MatchYear 里面。如果没有任何字符串 (或者此函数返回的值是 0 )，那么这一输出变量置为空。 在 函数 中创建一个全局变量的数组来替代局部变量，就要在使用前 声明 数组名 (比如刚才的 Match ) 为全局变量。 形式2 (位置 – 长度)：若以 P 开头的正则表达式，比如，"P)abc.*123"，则完全匹配正则表达式的字符串的 长度 将存储在 OutputVar 里 (没有匹配到，长度就是 0 )。如果现在使用了 捕捉子模式 ，就会有两个数组 OutputOvarPos 和 OutputVarLen 分别存储匹配到的字符串的位置和长度。例如：若基变量名为 Match ，则符合模式的第一个子串的位置存储在 MatchPos1 ，长度存储在 MatchLen1 (没到匹配到任何子串则全部返回 0 ，函数值也会为 0 )。仍有一个例外，就是 命名子模式：它将存储名用名字替代了数字 (比如，MatchPosYear 和 MatchLenYear )。
StartingPosition | 如果省略 StartingPostion 的值，它会默认为 1 (从源字符串 Haystack 的第一个字符开始)。另外，设置为 2 则以第二个字符开始，值为 3 就从第三个开始，依次类推。如果 StartingPostion 的值超出了 Haystack 的长度范围，则函数返回为 0 ，变量值为空。 如果 StartingPostion 的值小于1，函数会认为是从 Haystack 的末尾处开始。例如：0 就是倒数一个字符的位置，-1 就是倒数第二个字符，依次类推。如果 StartingPostion 超过了 Haystack 最左边的位置，它就会搜索整个 Haystack 。 无论 StartinPostion 的值是什么，函数返回的值都是根据 Haystack 的第一个字符所确定的。例如："123abc789” 中 "abc” 的位置总是 4 。

#### ErrorLevel

ErrorLevel 的值是下面中的一个:

- 0, 表示没发现错误。
- 一个有如下格式的字符串：Complie error N at offset M: description. 在这个字符串里，N 是 PCRE ( Perl 兼容正则表达式 ) 的错误值，M 是正则表达式中出现错误的位置，description 是描述这个错误的文本信息。
- 一个负数，是指在 执行 正则表达式过程中出现的错误。尽管这种错误非常罕见，如这些情况就容易出现这种错误：”太多的空匹配“ (-22)，”递归太深“ (-21)，”太到匹配极限“ (-8)。如果出现了这些错误，就试着重新写更严格的正则表达式，如用 ? , + 或者用有限制的方式，如 {0,3} 来取代 * 。

#### 选项 ( 区分大小写 )

在正则表达式之前加上 0 个或者多个选项并以右括号结束。例如：模式 "im)abc” 将搜索多行中不区分大小写的 abc ，若没有选项可以省略圆括号。尽管这将原来的语法打断，但是它不需要新的前分割符 (比如右斜杠)，因此没有必要转换模式内的分割符。另外，由于使用了选项，函数性能有所提升。

i | 不区分大小写。
m | 多行是指由多个单行 (有换行符) 所组成的一个集合 (它包括换行符) 。但在下列情况会有所改变： 1) 弯折符号 (^) 在所有行内匹配 -- 总是从源字符串开头的地方开始匹配 (但不是匹配源字符串 Haystack 中换行 靠后 的地方)。 2) 美元符号 ($) 在源字符串中任意换行符之前匹配 (也就是说，它总是匹配每行靠近结尾的地方)。 例如：源字符串是 "xyz`r`nabc" 中的 abc 要用模式 "m)^abc$" 来精确匹配。 如果选项是 "D"，它就将会忽略当前的 "m"。
s | 该选项会使点 (.) 能匹配一行内所有的字符 (通常不会换行符后的) 。如果换行符是默认的 CRLF (`r`n) ，就要用两个点去匹配它 (而不是一个点)。无论这个选项如何，[^a] 总是匹配换行符。
x | 忽略模式中空白字符类。如字符 `n 和 `t 这类的字符将被在正则表达式中的忽略，这些字符都是出现在正则表达式中 (与此相反，使用 \n 和 \t 之类的字符就不会被正则表达式忽略)。x 选项也是一个复杂的模式。然而，这种模式必须遵循这个条件： 只能 应用在数据字符中；空白字符也许不会出现特殊的序列，如 (?(。
A | 强制将匹配模式固定；也就是说，它只能从源字符串的第一个字符开始匹配。大数情况下，和 "^" 的功能一样。
D | 强制用 ($) 的方式来从靠近源字符串末尾的地方开始匹配，即使源字符串以的换行符结尾的。没有这个选项时，$ 就只能匹配换行符 (如果有的话) 前的字符了。注意：这个选项会让 "m" 选项不起作用。
J | 允许重复 命名子模式 。这是一个很有用的模式，它在一组相同命名子模式下也能够匹配。注意：如果有多个实例命名去匹配字符串的话，就只有最左边的那个命名才会被存储 (变量名不区分大小写)。
U | 非贪婪的。只有在绝对必要的情况下才会使用量词 *+?{} ，并将剩下的部分提供给下一个模式。当 "U" 选项无效时，可以通过一个问号作为量词进行非贪婪匹配。相反地，当 "U" 选项有效，问号就会进行贪婪搜索。
X | PCRE 扩展。它使 PCRE 不完全符合 Perl 的正则表达式。目前，仅仅只有一个这样的特点，那就是在模式中的任何的反斜杠后加一个字符就没有特殊的意义并导致匹配失败和设置 ErrorLevel 相应的值。这个选项帮助保留未使用的反斜杠序列供以后使用。没有这个选项，反斜杠后的字符就会看成一般的字符而没有特殊的意义 (例如：\g 和 g 都被认为是字母 g )。不论此选项怎样，非字母反斜杠序列都没有特别的意义，它将总是认为是普通的字符 (例如：\/ 和 / 都被认为是 / )。
P | 位置模式。它会使函数 RegExMatch() 产生匹配到的子串的位置和长度。更详细的了解，请看上面的 输出变量。
S | 研究模式可以提高函数的性能。当匹配模式比较复杂或者被重复执行很多次的情况下，这个选项很有用。它会让匹配模式存储在高速缓存中，以便下次使用，通过这种方法来提高了正则表达式的性能。
`n | 替换默认的换行符 (`r`n) 为符合 UNIX 系统的标准的 (`n)。所选择的换行符会影响到 anchors (^ and $) 和 dot/period pattern 。
`r | 替换默认的换行符 (`r`n) 为符合 Windwos 标准的 (`r)。
`a | 在 1.0.46.06+ 的版本中，`a 看作是换行符，也就是指这些符号，`r，`n，`r`n，`v/VT/vertical tab/chr(0xB)，`f/FF/formfeed/chr(0xC)，and NEL/next-line/chr(0x85)。在 1.0.47.05+ 的版本中，换行符被限制为 CR，LF 和 CRLF 为 (*ANYCRLF) ，在选项后的正则表达式之前大写；例如： im)(*ANYCRLF)^abc$

注意：可用空格和 Tab 随意的隔开每个选项。

#### 性能

如果从一个较长的字符串中搜索一个简单的子串，请使用 InStr() 函数，因为它比 RegExMatch() 更有效率。

为了提高性能，它将最近使用的 100 个正则表达式缓存在内存里 (在编译的时候)。

当一个正则表达式重复使用的情况下，使用 S 选项 来提高性能。(比如在 loop 循环中)

#### 注意

一个命名子模式都有一个名字，如上文模式 (?P<Year>\d{4}) 中的 Year 。这些名字可能包括多达 32 个字母、数字和下划线。虽然这些命名子模式都是通过数字在对正则表达式本身的操作 (如：向后引用)，结果是仅仅用名字存储 输出数组，而不是用数字。例如 "Year" 是第一个名字，把匹配到的子串存储在 OutputVarYear 里，但是 OutputVar1 的值是没有改变 (它将保留以前的值，如果有的话)。如果是 非命名子模式 的 "Year" ，它将匹配到的子串存储在 OutputVar2 里，而不是 OutputVar1 里。

大多数的字符串 ( 像 abc123 ) 就能用一般的字符来匹配。而匹配像 \.*?+[{|()^$ 这样被保护的字符就要在其前面加是一个反斜杠。比如：\. 代表一个点，\\ 代表一个反斜杠。转义符可避免使用 \Q…\E。比如 \QLiteral Text\E。

在正则表达式中，一些特殊的字符，如制表符和换行符就用重音符号 (`) 或反斜杠 (\) 来表示。例如：`t is the same as \t 。

如学习正则表达式的基础 (或者重新记忆一下正则表达式的语法) ，请看 RegEx Quick Reference。

AutoHotKey 所使用的正则表达式是来自于 www.pcre.org 的兼容 Perl 语言的正则表达式。

#### 相关命令

RegExReplace(), RegEx Quick Reference, InStr(), IfInString, StringGetPos, SubStr(), SetTitleMatchMode RegEx, Global matching and Grep (forum link)

Common sources of text data: FileRead, UrlDownloadToFile, Clipboard, GUI Edit controls

#### 示例

    FoundPos := RegExMatch("xxxabc123xyz", "abc.*xyz")  ; 返回值 4，它就是匹配到的位置。
    FoundPos := RegExMatch("abc123123", "123$")  ; 返回值 7，因为 $ 要求从靠近最后的字符处开始匹配。
    FoundPos := RegExMatch("abc123", "i)^ABC")  ; 返回值 1，因为是要求从第一个字符处开始匹配，而且不区分大小写。
    FoundPos := RegExMatch("abcXYZ123", "abc(.*)123", SubPat)  ;返回 1 并且 SubPat1 的值是 "XYZ"。
    FoundPos := RegExMatch("abc123abc456", "abc\d+", "", 2)  ; 返回值 7 ，由于它是从第二个字符开始匹配的。

    ; 更多正则表达式的例子，请看 RegEx Quick Reference.