REReplace

Description

Uses a regular expression (RE) to search a string for a string pattern and replace it with another. The search is case-sensitive.

Return value

If the scope attribute is set to one, returns a string with the first occurrence of the regular expression replaced by the value of substring.

If the scope attribute is set to all, returns a string with all occurrences of the regular expression replaced by the value of substring.

If the function finds no matches, it returns a copy of the string unchanged.

Syntax

REReplace(string, reg_expression, substring [, scope ])

History

New in ColdFusion MX: this function supports the following special codes in a substring, to control case conversion:

\u - uppercase the next character
\l - lowercase the next character
\U - uppercase until \E
\L - lowercase until \E
\E - end \U or \L

As in ColdFusion 5, the characters \1, \2, and so on, are backreference codes. To include these literal characters in a substring, you must escape them, by inserting a backslash before them (for example, change "\u" to "\\u").

To include a backslash followed by a backreference or case conversion code, you must escape the backslash, by prefixing another backslash (for example, "\\\1").

For more information on new features, see REFind.

Parameters

Parameter Description

string
A string or a variable that contains one. String within which to search.

reg_expression
Regular expression to replace. The search is case-sensitive.

substring
A string or a variable that contains one. Replaces reg_expression.

scope

one: replace the first occurrence (default)

all: replace all occurrences

Parameter	Description
string	A string or a variable that contains one. String within which to search.
reg_expression	Regular expression to replace. The search is case-sensitive.
substring	A string or a variable that contains one. Replaces `reg_expression`.
scope	one: replace the first occurrence (default) all: replace all occurrences

Usage

For more information, see Developing ColdFusion MX Applications with CFML.

Example

<p>The REReplace function returns <i>string</i> with a regular expression replaced
with <i>substring</i> in the specified scope. Case-sensitive search.
<p>REReplace("CABARET","C|B","G","ALL"):  
<cfoutput>#REReplace("CABARET","C|B","G","ALL")#</cfoutput>
<p>REReplace("CABARET","[A-Z]","G","ALL"):  
<cfoutput>#REReplace("CABARET","[A-Z]","G","ALL")#</cfoutput>
<p>REReplace("I love jellies","jell(y|ies)","cookies"):
<cfoutput>#REReplace("I love jellies","jell(y|ies)","cookies")#
 </cfoutput>
<p>REReplace("I love jelly","jell(y|ies)","cookies"):
<cfoutput>#REReplace("I love jelly","jell(y|ies)","cookies")#</cfoutput>

Version 6

Comments are no longer accepted for ColdFusion MX. ColdFusion 8 is the current version.

Comments

No screen name said on Apr 26, 2004 at 12:12 PM :

Macromedia needs some real examples for their tags. Examples that state a problem, and also show results. The example on the page is of little use.

narsavagep said on Aug 4, 2004 at 8:57 AM :

You need a link to the definition of a "regular expression" -- how to use it and the special characters to use.
FYI: The link is http://livedocs.macromedia.com/coldfusion/6/Developing_ColdFusion_MX_Applications_with_CFML/regexp3.htm#1117230

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6/CFML_Reference/functions-pt269.htm