Replace

The replace action replaces occurances of the matched regex in the input text with the specified replacement. Like other cfRegex actions you can specify a starting position, and can apply any limit to how many times replacement is made (not just "one" or "all", as rereplace has).

The value to replace each match with can be specified in one of three ways: as a replacement string, a replacement array, or a callback function that returns a string.

Replacement Types

string

If you specify a simple string variable the match found in the input text will be replaced with the contents of this variable. If you include $0 in the replacement string, this refers to the entire matched text, and use $1..$n to refer to numbered groups. (Where n indicates is the number of captured groups, not the literal letter n.)

If you have ten (or more) groups, you can use $10, however if you have less than ten groups this will be interpreted as $1 (i.e group 1), then a literal 0 character, similarly with $11, $12, $20, etc.

If you need a $ in your replacement string, you need to use \$, and if you need \$ you need to use \\$, and so on.

function

If you provide a function for the replacement variable, that function is called each time a match is made, and the result of the function is used as the text to replace the match with.

The function must be a UDF or an object method (i.e. built-in functions cannot be used directly).

These callback functions receive a selection of arguments containing information relating to the match - the text matched, the groups found, and so on. Full details of what arguments a function should receive are detailed on the page dedicated to callbacks.

The string result of the callback is subject to the same processing rules as a replacement string, so $0..$n are replaced by group text and \$ is needed to represent a literal $ character.

array

By specifying an array of replacements, you can use a different value for each match found. If the number of matches found is greater than the length of the array supplied, the replacements start again from the beginning of the array.

Each element in the array can be either a replacement string or a callback function - you can use a combination of both in the same array.

String replacement values use the same rules as the replacement string (i.e. use $0..$n), and callback functions work in the same way as they would when passed singularly.

NOTE: Due to a bug in Adobe ColdFusion, only string replacements can be used in arrays with ACF9. You can still use callbacks outside of arrays for ACF9. Neither Railo not OpenBD are affected by this bug, so this feature works fine for them.

Object

Arguments

Name	Type	Required	Default	Notes
Text	String	yes	n/a	The text in which the regex is to be replaced
Replacement	String OR Callback OR Array	yes	n/a	See section "Replacement Types" above.
Start	Char Position	no	1	Position at which to start replacing (1 is first character.)
Limit	Integer	no	0	Number of times to replace before stopping. (0 is unlimited.)
CallbackData	Struct	no	none	A structure which is passed into the callback function.

Usage Examples

<cfset Input = "The quick fox jumps over the lazy brown dog." />
<cfset OneWordRx = new Regex( '\w+' ) />


<cfdump var=#OneWordRx.replace( Input , "[word]" )# />


<cfdump var=#OneWordRx.replace( Input , "[word]" , 5 )# />


<cfdump var=#OneWordRx.replace( Input , "[word]" , 5 , 2 )# />


<cfdump var=#OneWordRx.replace( Input , "[$0]" )# />


<cfdump var=#OneWordRx.replace( Input , ["[word]","$0"] )# />


<cfdump var=#OneWordRx.replace( text=Input , replacement=["[word]","[$0]"] , limit = 4 )# />


<cfdump var=#OneWordRx.replace( Input , UcaseFunc , 1 , 3 )# />

<cffunction name="UcaseFunc" returntype="String" output="false">
    <cfargument name="Match" type="String" required />
    <cfreturn UCase(Argments.Match) />
</cffunction>



<cfdump var=#OneWordRx.replace( Input , [ UcaseFunc , "[word]" ] , 1 , 3 )# />

<cffunction name="UcaseFunc" returntype="String" output="false">
    <cfargument name="Match" type="String" required />
    <cfreturn UCase(Argments.Match) />
</cffunction>

Tag

Attributes

Name	Type	Required	Default	Notes
Variable	VarName	no	"cfregex"	The variable which the result is assigned to.
Text	String	yes	n/a	The text in which the regex is to be replaced
Replacement	String OR Callback OR Array	yes	n/a	See section "Replacement Types" above.
Start	Char Position	no	1	Position at which to start replacing (1 is first character.)
Limit	Integer	no	0	Number of times to replace before stopping. (0 is unlimited.)
CallbackData	Struct	no	none	A structure which is passed into the callback function.
Modes	StringList	no	none	List of regex modes to apply to the pattern.

Usage Examples

<cfset Input = "The quick fox jumps over the lazy brown dog." />
<cfset OneWordRx = new Regex( '\w+' ) />



<cfregex replace variable="Output" text=#Input# replacement="[word]" >
    \w+
</cfregex>
<dump var=#Output#/>


<cfregex replace variable="Output" text=#Input# replacement="[word]" , 5 >
    \w+
</cfregex>
<dump var=#Output#/>


<cfregex replace variable="Output" text=#Input# replacement="[word]" start=5 limit=2 >
    \w+
</cfregex>
<dump var=#Output#/>


<cfregex replace variable="Output" text=#Input# replacement="[$0]" >
    \w+
</cfregex>
<dump var=#Output#/>


<cfregex replace variable="Output" text=#Input# replacement=#["[word]","$0"]# >
    \w+
</cfregex>
<dump var=#Output#/>


<cfregex replace variable="Output" text=#Input# replacement=#["[word]","[$0]"]# limit=4 >
    \w+
</cfregex>
<dump var=#Output#/>


<cfregex replace variable="Output" text=#Input# replacement=#UcaseFunc# limit=3 >
    \w+
</cfregex>
<dump var=#Output#/>

<cffunction name="UcaseFunc" returntype="String" output="false">
    <cfargument name="Match" type="String" required />
    <cfreturn UCase(Argments.Match) />
</cffunction>



<cfregex replace variable="Output" text=#Input# replacement=#[ UcaseFunc , "[word]" ]# limit=3 >
    \w+
</cfregex>
<dump var=#Output#/>

<cffunction name="UcaseFunc" returntype="String" output="false">
    <cfargument name="Match" type="String" required />
    <cfreturn UCase(Argments.Match) />
</cffunction>

Function

Arguments

Name	Type	Required	Default	Notes
Pattern	RegexString	yes	n/a	The regex pattern to compile into a Regex Object.
Text	String	yes	n/a	The text in which the regex is to be replaced
Replacement	String OR Callback OR Array	yes	n/a	See section "Replacement Types" above.
Start	Char Position	no	1	Position at which to start replacing (1 is first character.)
Limit	Integer	no	0	Number of times to replace before stopping. (0 is unlimited.)
CallbackData	Struct	no	none	A structure which is passed into the callback function.
Modes	StringList	no	none	List of regex modes to apply to the pattern.

Usage Examples

<cfset Input = "The quick fox jumps over the lazy brown dog." />

<cfdump var=#RegexReplace( '\w+' , Input , "[word]" )# />


<cfdump var=#RegexReplace( '\w+' , Input , "[word]" , 5 )# />


<cfdump var=#RegexReplace( '\w+' , Input , "[word]" , 5 , 2 )# />


<cfdump var=#RegexReplace( '\w+' , Input , "[$0]" )# />


<cfdump var=#RegexReplace( '\w+' , Input , ["[word]","$0"] )# />


<cfdump var=#RegexReplace( pattern='\w+' , text=Input , replacement=["[word]","[$0]"] , limit = 4 )# />


<cfdump var=#RegexReplace( '\w+' , Input , UcaseFunc , 1 , 3 )# />

<cffunction name="UcaseFunc" returntype="String" output="false">
    <cfargument name="Match" type="String" required />
    <cfreturn UCase(Arguments.Match) />
</cffunction>



<cfdump var=#RegexReplace( '\w+' , Input , [ UcaseFunc , "[word]" ] , 1 , 3 )# />

<cffunction name="UcaseFunc" returntype="String" output="false">
    <cfargument name="Match" type="String" required />
    <cfreturn UCase(Arguments.Match) />
</cffunction>

Practical Examples

Example 1

A function which appends cfthrow after all TODO tasks in some CFML code:

<cffunction name="convertTodoToThrow" returntype="String" output="false" access="public">
    <cfargument name="Content" type="String" required />
    <cfset var Result = Arguments.Content />

    <cfif NOT StructKeyExists(Variables,'TodoTaxRx')>
        <cfset Variables.TodoTagRx    = new Regex('<!---\s*TODO:\s*([^-]++(?s:(?!--->).)*)--->') />
        <cfset Variables.TodoScriptRx = new Regex('//\s*TODO:\s*([^\n]+)') />
    </cfif>

    <!--- $0 is the entire matched tech, $1 is the first captured group (i.e. text of the TODO) --->
    <cfset Result = Variables.TodoTagRx.replace( Result , '$0#chr(10)#<cfthrow type="TODO" message="$1" />' ) />
    <cfset Result = Variables.TodoScriptRx.replace( Result , '$0#chr(10)#throw( type="TODO" message="$1" );' )/>

    <cfreturn Result />
</cffunction>

Example 2

This example uses a replacement callback to converts all IPv4 addresses to IPv6 format, excluding those specified by the callbackdata.

<cfset DocumentText = RegexReplace
    ( Pattern      = '([12]\d\d)\.([12]?\d\d)\.([12]?\d\d)\.([12]?\d\d)'
    , Text         = DocumentText
    , Replacement  = convertIP4toIP6
    , CallbackData = {ExcludedIPs:['192.168.0.1','127.0.0.1']}
    ) />

<cffunction name="convertIP4toIP6" returntype="String" output="false">
    <cfargument name="Match"  required />
    <cfargument name="Groups" required />
    <cfargument name="Data"   required />

    <cfif StructKeyExists(Arguments.Data,'ExcludedIps')
        AND ArrayFind(Arguments.Data.ExcludedIps,Arguments.Match)
        >
        <cfreturn Arguments.Match />
    </cfif>

    <cfreturn "::ffff:"
        & toHex( Arguments.Groups[1].Match )
        & toHex( Arguments.Groups[2].Match )
        & ":"
        & toHex( Arguments.Groups[3].Match )
        & toHex( Arguments.Groups[4].Match )
        />
</cffunction>


<cffunction name="toHex" returntype="String" output="false">
    <cfreturn Right( '0' & FormatBaseN( Arguments[1] , 16 ) , 2) />
</cffunction>