xf:replace

Substitutes all occurrences of the regular expression specified by $string-var2 in $string-var1 with $string-var3.

If any character besides m or i is specified in $string-var4 (the flags string), the TransformException exception is raised with the RT_REGEXP_FLAGS fault code. In the mapper the following error message is displayed:

Error occurred while executing XQuery: Invalid regular expression syntax (flags: "a") 

To learn more about using fault codes, see Getting the TransformException Fault Code Programmatically.

If the value of $string-var1, $string-var2, $string-var3, or $string-var4 is the empty sequence, the empty sequence is returned. The empty sequence is a sequence containing zero items (), which is similar to null in SQL.

Signatures

xf:replace(xs:string? $string-var1, xs:string? $string-var2 xs:string? $string-var3) —> xs:string?

xf:replace(xs:string? $string-var1, xs:string? $string-var2, xs:string? $string-var3, xs:string? $string-var4) —> xs:string?

Arguments

Data Type
Argument
Description

xs:string?

$string-var1

Represents the source string.

xs:string?

$string-var2

Represents the regular expression string. To learn more, see W3C Regular Expresssions.

xs:string?

$string-var3

Represents the replacement string.

xs:string?

$string-var4

Specifies flags that affect the comparison to the regular expression. (Optional)



m

If specified the match operates in multiline mode. By default, the match operates in string mode.

i

If specified the match operates in case-insensitive mode. By default, the match operates in case-sensitive mode.

Returns

Returns the string after substitution has occurred. (All occurrences of the regular expression specified by $string-var2 in $string-var1 are replaced with $string-var3.)

Examples

Simple

Invoking replace("xyzaxyz", "yz", "o") returns the string xoaxo, as shown in the following example query:

<result>{xf:replace("xyzaxyz", "yz", "o")}</result> 

The preceding query generates the following result:

<result>xoaxo</result> 

Greedy Qualifiers

Invoking replace("xyzaxyz", "x.*z", "o") returns the string o because the regular expression x.*z behaves as a greedy qualifier—the entire source string is read in before the first match is attempted and only if the first match attempt (with the entire source string) fails, does the matcher reduce the size of the source string by one character and attempts to match again. This process is repeated until there are no more characters in the source string. In this case, the regular expression x.*z matches the entire source string xyzaxyz, so the entire source string is replaced by the string o, shown in the following example query:

<result>{xf:replace("xyzaxyz", "x.*z", "o")}</result> 

The preceding query generates the following result:

<result>o</result> 

Reluctant Qualifiers

Invoking replace("xyzaxyz", "x.*?z", "o") returns the string oao because the regular expression x.*?z behaves as a reluctant qualifier—matching starts at the beginning of the input string, reluctantly reading in characters one at a time, until a match is found. Once a match is found, replacement occurs and the rest of the input string is searched for more matches. In this case, the regular expression x.?z finds two matches in the source string xyzaxyz, so the two xyz strings in the source string are replaced with the string o, shown in the following example query:

<result>{xf:replace("xyzaxyz", "x.*?z", "o")}</result> 

The preceding query generates the following result:

<result>oao</result> 

Replacement String Is Empty

Invoking replace("xyzaxyz", "x", "") returns the string yzayz because the replacement string is a zero-length string, as shown in the following example query:

<result>{xf:replace("xyzaxyz", "x", "")}</result> 

The preceding query generates the following result:

<result>yzayz</result> 

Case-Insensitive Mode

Invoking replace("Xax", "x", "o", "i") returns the string oao. The i flag in $string-var4 specifies to ignore the case during matching, so in this case two replacements occur (X and x), as shown in the following example query:

<result>{xf:replace("Xax", "x", "o", "i")}</result> 

The preceding query generates the following result:

<result>oao</result> 

Pass in Null

Invoking replace("xyz", "xyz",()) returns the null string as shown in the following example query:

<result>{xf:replace("xyz", "xyz",())}</result> 

Note: The string: () is the empty sequence (similar to a SQL null) which is a sequence containing zero items.

The preceding query generates the following result:

<result/> 

Related Topics

W3C replace function description.

W3C Regular Expressions description.