User Guide

652 Chapter 3: ColdFusion Functions
Usage
This function finds the first occurrence of a regular expression in a string. To find the second and
subsequent instances of the expression or of subexpressions in it, you call this function more than
once, each time with a different start position. To determine the next start position, use the
returnsubexpressions parameter, and add the value returned in the first element of the length
array to the value in the first element of the position array.
Example
<h3>REFind Example</h3>
<p>This example shows the use of the REFind function with and without the
<i>returnsubexpressions</i> parameter set to True.
If you do not use the <i>returnsubexpressions</i> parameter,
REFind returns the position of the first occurrence of a regular
expression in a string starting from the specified position.
Returns 0 if no occurrences are found.</p>
<p>REFind("a+c+", "abcaaccdd"):
<cfoutput>#REFind("a+c+", "abcaaccdd")#</cfoutput></p>
<p>REFind("a+c*", "abcaaccdd"):
<cfoutput>#REFind("a+c*", "abcaaccdd")#</cfoutput></p>
<p>REFind("[[:upper:]]", "abcaacCDD"):
<cfoutput>#REFind("[[:upper:]]", "abcaacCDD")#</cfoutput></p>
<p>REFind("[\?&]rep = ", "report.cfm?rep = 1234&u = 5"):
<cfoutput>#REFind("[\?&]rep = ", "report.cfm?rep = 1234&u = 5")#
</cfoutput>
</p>
<!--- Set startPos to one; returnMatchedSubexpressions = TRUE --->
<hr size = "2" color = "#0000A0">
<p>If you use the <i>returnssubexpression</i> parameter, REFind returns the
position and length of the first occurrence of a regular expression
in a string starting from the specified position. The position and
length variables are stored in a structure. To access position and length
information, use the keys <i>pos</i> and <i>len</i>, respectively.</p>
<cfset teststring = "The cat in the hat hat came back!">
<p>The string in which the function is to search is:
<cfoutput><b>#teststring#</b></cfoutput>.</p>
<p>The first call to REFind to search this string is:
<b>REFind("[A-Za-z]+",testString,1,"TRUE")</b></p>
<p>This function returns a structure that contains two arrays: pos and len.</p>
<p>To create this structure you can use a CFSET statement, for example: </p>
&lt;CFSET st = REFind("[[:alpha:]]",testString,1,"TRUE")&gt;
<cfset st = REFind("[[:alpha:]]",testString,1,"TRUE")>
start Optional. A positive integer, or a variable that contains one. Position in the
string at which to start search. Default: 1.
returnsubexpressions Optional. Boolean. Whether to return substrings of reg_expression, in arrays
named
len and pos:
• True: if the regular expression is found, the first array element contains the
length and position, respectively, of the first match.
If the regular expression contains parentheses that group subexpressions,
each subsequent array element contains the length and position,
respectively, of the first occurrence of each group.
If the regular expression is not found, the arrays each contain one element
with the value 0.
• False: the function returns the position in the string where the match
begins. Default.
Parameter Description