Function Block PREG_REPLACE

The Function Block PREG_REPLACE searches and replaces using regular expressions.

Note: This function is Binary-Safe. This means that UTF8 characters cannot be processed directly.

Input PATTERN

The expression as a string to search for. Some PCRE modifiers are also available.

Input REPLACEMENT

The string to replace. This may contain references in the form \n or $n, with the latter being preferred. Each of these references is replaced with the text captured by the nth parenthesized subpattern. n can have a value from 0 to 99. \0 or $0 refer to the text that matches the entire pattern. To obtain the number of the capturing subpattern, opening parentheses are counted starting from left to right with 1. To use a backslash in the replacement, it must be doubled "\\".

If you want to work with a replacement where a number directly follows a backreference (i.e., right after matching a pattern a number should come), you cannot use the notation \1 for your backreference. For example, \11 would confuse the function because it does not know whether you want the backreference \1 followed by the number 1 or just the backreference \11. In this case, the solution is to use ${1}1. This creates an isolated backreference $1 and the 1 remains a character symbol.

If you use the deprecated modifier e, this function masks some characters (namely ', ", \ and NULL) in the strings with which backreferences are replaced. This is done to ensure that no syntax errors occur when using backreferences containing single or double quotes. Make sure you know the string syntax to exactly know how the evaluated string looks.

Input SUBJECT

The input defines the string to search through.

Input LIMIT

The maximum possible number of replacements for each pattern in every subject. Default value: -1 or NULL (no limit).

Output Q

If matches were found, the new string Q is returned; otherwise SUBJECT is returned unchanged or NULL, if an error occurred.

Output COUNT

The output returns the number of replacements made.