Function Block PREG_FILTER

The Function Block PREG_FILTER searches and replaces using regular expressions.

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

Apart from the fact that the Function Block PREG_FILTER only returns the (possibly converted) strings in case of matches, it is identical to the Function Block PREG_REPLACE.

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 by 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., a number should come right after matching a pattern), 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 letter symbol.

If you use the deprecated modifier e, this function masks some characters (namely ', ", \ and NULL) in the strings with which backreferences will be 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 (possibly converted) 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.