# RegExReplace

替换字符串中匹配模式(正则表达式) 出现的地方.

    NewStr := RegExReplace(Haystack, NeedleRegEx , Replacement, &OutputVarCount, Limit, StartingPos)

## 参数

Haystack

  类型: 字符串

  要搜索和替换其内容的字符串. 可以包含二进制零.

NeedleRegEx

  类型: 字符串

  要搜索的模式, 它是兼容 Perl 的正则表达式(PCRE). 模式的选项(如果有) 必须放在模式字符串的开始且后面跟着闭括号. 例如, 模式 i)abc.*123 将打开不区分大小写的选项并搜索 "abc", 接着零个或多个任意字符, 然后是 "123". 如果没有选项, ")" 是可选的; 例如, )abc 等同于 abc.

  虽然 NeedleRegEx 不能包含二进制零, 但模式 `\x00` 可用来匹配 Haystack 中的二进制零.

Replacement

  类型: 字符串

  每个匹配项要替换的字符串, 它是纯文本(不是正则表达式). 它可能包括反向引用, 比如 $1, 它从 Haystack 中引入匹配第一个子模式的子串. 最简单的反向引用是 $0 到 $9, 其中 $0 是匹配整个模式的子串, $1 是匹配第一个子模式的子串, $2 是第二个, 以此类推. 对于高于 9 的反引用(也可以是低于 9 的反引用), 请将数字用大括号括起来; 例如 ${10}, ${11}, 以此类推. 对于命名的子模式, 请将其名称用大括号括起来; 例如 ${SubpatternName}. 要指定一个原义的 $, 请使用 $$(这是唯一一个需要特殊处理的字符; 反斜杠永远不需要用来转义任何东西).

  要转换子模式的大小写, 请在 $ 后面加上下列字符之一: U 或 u(大写), L 或 l(小写), T 或 t(标题大小写, 其中每个单词的第一个字母大写, 但所有其他字母小写). 例如, $U1 和 $U{1} 都转写了第一个子模式的大写版本.

  不存在的反向引用和与 Haystack 中任何内容都不匹配的反向引用 -- 例如 (abc)|(xyz) 中的一个子模式 -- 将被转录为空字符串.

&OutputVarCount

  类型: VarRef

  指定一个变量引用, 用于存储发生的替换次数(如果没有, 则为 0).

Limit

  类型: 整数

  如果省略 Limit, 则默认为 -1, 即替换 Haystack 中出现的 所有 模式. 否则, 指定允许的最大替换次数. Haystack 中最后一次替换右边的部分将保持不变.

StartingPos

  类型: 整数

  如果省略 StartingPos, 则它默认为 1(Haystack 的开始位置). 否则, 指定 2 从第二个字符开始, 3 从第三个字符开始, 以此类推. 如果 StartingPos 的长度超过 Haystack 的长度, 那么搜索将从 Haystack 末尾的空字符串开始(常结果是不替换).

  指定负值的 StartingPos 将从右边的位置开始. 例如, -1 从最后一个字符开始, -2 从倒数第二个字符开始. 如果 StartingPos 试图超出 Haystack 的左端, 则会搜索整个 Haystack.

  不论 StartingPos 的值是多少, 返回值始终是 Haystack 的完整副本 -- 唯一的区别是, 与 StartingPos 为 1 时相比, 它的左侧更多部分可能没有改变.

## 返回值

类型: 字符串

函数将返回 Haystack 的一个版本, 其内容已经被操作所替换. 如果没有发生替换, 将返回 Haystack 原始值.

## 错误

在以下情况下会抛出 Error:

- 该模式包含一个语法错误; 或
- 在 execution 正则表达式的过程中发生了错误.

有关详情, 请参阅 RegExMatch.

## 选项

请参阅选项了解修饰符, 例如 i)abc, 它关闭了模式 "abc" 的区分大小写.

## 性能

要进行简单的子字符串替换, 请使用 StrReplace, 因为它比 RegExReplace 执行地更快.

如果您知道替换的最大次数是多少, 请在 Limit 参数中指定来提高性能, 因为这样可以早一些停止搜索(这样也可能会降低在替换操作过程中占用的系统内存). 例如, 如果您知道在一个大字符串的开始处仅有一个匹配, 请指定最大次数为 1.

为了提升性能, 最近使用的 100 个正则表达式会被缓存在内存中(以已编译的形式).

多次使用一个正则表达式时(例如在循环中), 使用研究选项(S) 可以提高性能.

## 备注

大多数字符(例如 abc123) 可以原义使用在正则表达式中. 然而 \.*?+[{|()^$ 这些字符则必须在其前面加上反斜杠才能被视为原义. 例如, \. 表示一个原义的句点, 而 \\ 表示一个原义的反斜杠. 使用 \Q...\E 能避免转义. 例如: \QLiteral Text\E.

在正则表达式中, 特殊字符(如制表符和换行符) 可以使用一个重音符(`) 或反斜杠(\) 进行转义. 例如, `t 等同于 \t.

要了解正则表达式的基础(或复习正则表达式的语法), 请参阅正则表达式快速参考.

## 相关

RegExMatch, RegEx 快速参考, Regular Expression Callouts, StrReplace, InStr

文本数据的常见来源: FileRead, Download, A_Clipboard, GUI Edit 控件

## 示例

有关普通 RegEx 的示例, 请参阅 RegEx 快速参考.

报告 "abc123xyz", 因为 $ 只能在末尾形成匹配.

    MsgBox RegExReplace("abc123123", "123$", "xyz")

报告 "123", 因为通过不区分大小写选项实现了匹配.

    MsgBox RegExReplace("abc123", "i)^ABC")

报告 "aaaXYZzzz", 使用了 $1 后向引用.

    MsgBox RegExReplace("abcXYZ123", "abc(.*)123", "aaa$1zzz")

报告空字符串, 并保存 2 到 ReplacementCount.

    MsgBox RegExReplace("abc123abc456", "abc\d+", "", &ReplacementCount)

dftg