# RegExReplace() [v1.0.45+]

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

NewStr := RegExReplace(Haystack, NeedleRegEx [, Replacement = "", OutputVarCount = "", Limit = -1, StartingPosition = 1])

#### 参数

NewStr | RegExReplace() 返回内容被替换过的 Haystack 的一个版本. 如果没有替换操作发生, Haystack 保持不变. 如果遇到错误 (例如 NeedleRegEx 出现语法错误 ), Haystack 保持不变 (此时早于 1.0.46.06 的版本会返回 "") 同时 ErrorLevel 被设置为 下列 值的其中一个而不是 0.
Haystack | 源字符串.
NeedleRegEx | 此匹配模式是和 Perl 兼容的正则表达式 (PCRE). 如果需要, 可以在正则表达式前加上 选项, 并以 ")" 结束. 例如, 匹配模式 "i)abc.*123" 将匹配不区分大小写的 "abc", 接着0个或多个任意字符, 并以 "123" 结尾的字符串. 如果不含选项, ")" 是可选的; 例如, ")abc" 相当于 "abc".
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 | 此参数是不引用的变量名(即不需要使用百分号包围), 它用于保存替换的次数(如果没有则为 0).
Limit | 如果 Limit 省略, 默认值为 -1, 此时会替换 Haystack 中 所有 发现匹配模式的地方. 否则, 请指定允许替换的最大次数. Haystack 最后一次替换右边的部分保持不变.
StartingPosition | 如果 StartingPosition 省略, 默认值为 1 (从 Haystack 的第一个字符开始). 否则, 从第二个字符开始请指定 2, 第三个字符指定 3, 依此类推. 如果 StartingPosition 超过了 Haystack 的长度, 搜索会从 Haystack 的结尾后的空字符串开始 (这是导致没有替换发生的常见情况). 如果 StartingPosition 小于 1, 函数会认为是从 Haystack 末尾处开始. 例如, 0 从最后一个字符开始, -1 则从倒数第二个字符开始. 如果 StartingPosition 超过了 Haystack 最左边的位置, 它会搜索整个 Haystack. 不论 StartingPosition 的值是什么, 返回值总是 Haystack 的完整副本 -- 唯一的区别是比起 StartingPosition 为 1 时发生的情况此时源字符串左边可能更多的部分保持不变.

#### ErrorLevel

ErrorLevel 被设置为下列值的其中一个:

- 0, 表示没发现错误.
- 一个如下格式的字符串: Compile error N at offset M: description. 在此字符串中, N 是 PCRE 错误值, M 正则表达式中出现错误的字符的位置, 而 description 是描述这个错误的文本信息.
- 一个负数, 表示在正则表达式 执行 时遇到的错误. 尽管这种错误非常罕见, 像这些情况就容易出现这种错误 "太多空字符串匹配" (-22), "递归太深" (-21), 和 "达到匹配限制" (-8). 如果出现上述情况, 请尝试重新设计更严格的匹配模式, 例如使用一个 ?, +, 或一个像 {0,3} 这样的限制代替每个 *, 不管是否可行.

#### 选项

关于修饰符请参见 选项, 例如 "i)abc", 此选项会使得模式 "abc" 进行不区分大小写的匹配.

#### 性能

简单的字符串替换, 请使用 StringReplace 命令因为它比 RegExReplace() 执行的更快.

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

为了提高性能, 它将最近使用的 100 个正则表达式缓存在内存里 (在已编译的形式中).

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

#### 备注

大多数字符例如 abc123 可以直接使用于正则表达式中. 而 \.*?+[{|()^${/2} 这些字符必须在其前面加上反斜杠来进行匹配. 例如, \. 匹配一个原义的句号, \\ 匹配一个原义的反斜杠. 使用 \Q...\E 可以避免转义. 例如: \QLiteral Text\E.

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

要了解正则表达式的基础 (或重新记忆正则表达式语法), 请参看 正则表达式快速参考.

#### 相关

RegExMatch(), RegEx Quick Reference, StringReplace, InStr()

文本数据的通常来源: FileRead, UrlDownloadToFile, Clipboard, GUI Edit controls

#### 示例

    NewStr := RegExReplace("abc123123", "123$", "xyz")  ; Returns "abc123xyz" because the $ allows a match only at the end.
    NewStr := RegExReplace("abc123", "i)^ABC")  ; Returns "123" because a match was achieved via the case-insensitive option.
    NewStr := RegExReplace("abcXYZ123", "abc(.*)123", "aaa$1zzz")  ; Returns "aaaXYZzzz" by means of the $1 backreference.
    NewStr := RegExReplace("abc123abc456", "abc\d+", "", ReplacementCount)  ; Returns "" and stores 2 in ReplacementCount.

    ; For general RegEx examples, see the RegEx Quick Reference.