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", 接着零个或多个任意字符, 并以 "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
[v1.1.04+] 此函数失败时会抛出异常 (这个不会和 "没有找到匹配" 冲突, 失败表示匹配过程中遇到问题, 而 "没有找到匹配" 表示匹配过程成功完成只是没有发现匹配). 想了解更多信息, 请参阅 运行时错误.
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) 可以直接使用在正则表达式中. 然而, \.*?+[{|()^$ 这些字符则必须在其前面加上反斜线来进行匹配. 例如, \. 表示一个原义的句点而 \\ 表示一个原义的反斜线. 使用 \Q...\E 能避免转义. 例如：\QLiteral Text\E。
在正则表达式中, 特殊字符 (如制表符和新行符) 可以使用一个重音符 (`) 或反斜线 (\) 进行转义. 例如, `t 等同于 \t.
要了解正则表达式的基础 (或复习正则表达式的语法), 请参阅 正则表达式快速参考.
相关
RegExMatch(), 正则表达式快速参考, 正则表达式调出, StringReplace, InStr()
文本数据的常见来源: FileRead, UrlDownloadToFile, Clipboard, GUI Edit 控件
示例
NewStr := RegExReplace("abc123123", "123$", "xyz") ; 返回 "abc123xyz", 因为 $ 使得只能在末尾形成匹配.
NewStr := RegExReplace("abc123", "i)^ABC") ; 返回 "123", 因为通过不区分大小写选项实现了匹配.
NewStr := RegExReplace("abcXYZ123", "abc(.*)123", "aaa$1zzz") ; 返回 "aaaXYZzzz", 其中使用了 $1 后向引用.
NewStr := RegExReplace("abc123abc456", "abc\d+", "", ReplacementCount) ; 返回 "" 并保存 2 到 ReplacementCount.
; 关于普通正则表达式的例子, 请参阅 正则表达式快速参考.