<html>
<head>
<link href="mmres://user_interface_reference.css" rel="stylesheet" type="text/css">
<title>REFIND</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
   <div id="Description">
   <table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
      <tr> 
         <td valign="top" class="name">REFIND</td>
         <td valign="top" nowrap class="compatibility">&nbsp;</td>
      </tr>
      <tr>
         <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
      </tr>


    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Description</span>
<p>
Uses a regular expression (RE) to search a string for a pattern. The search is case sensitive. 
</p>

<p>
For more information on regular expressions, including escape sequences, anchors, and modifiers, see Chapter&#160;7, "Using Regular Expressions in Functions," in ColdFusion MX Developer's Guide. 
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Returns</span>
<p>
Depends on the value of the returnsubexpressions<i> </i>parameter:
</p>
<ul>

<li>If returnsubexpressions<i> </i>= &quot;False&quot;: </li>
<ul>

<li>The position in the string where the match begins</li>

<li>0, if the regular expression is not matched in the string</li>
</ul>

<li>If returnsubexpressions = &quot;True&quot;: a structure that contains two arrays, len and pos. The array elements are as follows:</li>
<ul>

<li>If the regular expression is found in the string, the first element of the len and pos arrays contains the length and position, respectively, of the first match of the entire regular expression.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.</li>

<li>If the regular expression is not found in the string, the first element of the len and pos arrays contains 0. </li>
</ul>
</ul>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Category</span>
<p>
String functions
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Function syntax</span><pre>REFind(reg_expression, string [, start ]    [, <i>returnsubexpressions</i> ] )
</pre>    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">See also</span>
<p>
Find, FindNoCase, REFindNoCase, REReplace, REReplaceNoCase
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Parameters</span>
<p>

</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Usage</span>
<p>
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<i> </i>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.
</p>
    </td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="CLEARSEPARATION">&nbsp;</td>
  </tr>
  <tr>
    <td valign="top" colspan="2" class="description"><span class="title">Example</span><pre>&lt;h3&gt;REFind Example&lt;/h3&gt;
&lt;p&gt;This example shows the use of the REFind function with and without the
&lt;i&gt;returnsubexpressions&lt;/i&gt; parameter set to True. 
If you do not use the &lt;i&gt;returnsubexpressions&lt;/i&gt; 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.&lt;/p&gt;

&lt;p&gt;REFind(&quot;a+c+&quot;, &quot;abcaaccdd&quot;):   
&lt;cfoutput&gt;#REFind(&quot;a+c+&quot;, &quot;abcaaccdd&quot;)#&lt;/cfoutput&gt;&lt;/p&gt;
&lt;p&gt;REFind(&quot;a+c*&quot;, &quot;abcaaccdd&quot;):   
&lt;cfoutput&gt;#REFind(&quot;a+c*&quot;, &quot;abcaaccdd&quot;)#&lt;/cfoutput&gt;&lt;/p&gt;
&lt;p&gt;REFind(&quot;[[:upper:]]&quot;, &quot;abcaacCDD&quot;):   
&lt;cfoutput&gt;#REFind(&quot;[[:upper:]]&quot;, &quot;abcaacCDD&quot;)#&lt;/cfoutput&gt;&lt;/p&gt;
&lt;p&gt;REFind(&quot;[\?&amp;]rep = &quot;, &quot;report.cfm?rep = 1234&amp;u = 5&quot;):
   &lt;cfoutput&gt;#REFind(&quot;[\?&amp;]rep = &quot;, &quot;report.cfm?rep = 1234&amp;u = 5&quot;)#
   &lt;/cfoutput&gt;
&lt;/p&gt;
&lt;!--- Set startPos to one; returnMatchedSubexpressions = TRUE ---&gt;
&lt;hr size = &quot;2&quot; color = &quot;#0000A0&quot;&gt;
&lt;p&gt;If you use the &lt;i&gt;returnssubexpression&lt;/i&gt; 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 &lt;i&gt;pos&lt;/i&gt; and &lt;i&gt;len&lt;/i&gt;, respectively.&lt;/p&gt;
&lt;cfset teststring = &quot;The cat in the hat hat came back!&quot;&gt;
&lt;p&gt;The string in which the function is to search is:
&lt;cfoutput&gt;&lt;b&gt;#teststring#&lt;/b&gt;&lt;/cfoutput&gt;.&lt;/p&gt;
&lt;p&gt;The first call to REFind to search this string is:
      &lt;b&gt;REFind(&quot;[A-Za-z]+&quot;,testString,1,&quot;TRUE&quot;)&lt;/b&gt;&lt;/p&gt;
&lt;p&gt;This function returns a structure that contains two arrays: pos and len.&lt;/p&gt;
&lt;p&gt;To create this structure you can use a CFSET statement, for example: &lt;/p&gt;
&amp;lt;CFSET st = REFind(&quot;[[:alpha:]]&quot;,testString,1,&quot;TRUE&quot;)&amp;gt;
&lt;cfset st = REFind(&quot;[[:alpha:]]&quot;,testString,1,&quot;TRUE&quot;)&gt;
&lt;p&gt;
   &lt;cfoutput&gt;
   The number of elements in each array: #ArrayLen(st.pos)#.
   &lt;/cfoutput&gt;&lt;/p&gt;
&lt;p&gt;&lt;b&gt;The number of elements in the pos and len arrays is always one 
if you do not use parentheses in the regular expression.&lt;/b&gt;&lt;/p&gt;
&lt;p&gt;The value of st.pos[1] is: &lt;cfoutput&gt;#st.pos[1]#.&lt;/cfoutput&gt;&lt;/p&gt;
&lt;p&gt;The value of st.len[1] is: &lt;cfoutput&gt;#st.len[1]#.&lt;/cfoutput&gt;&lt;/p&gt;
&lt;p&gt;   
&lt;cfoutput&gt;
   Substring is &lt;b&gt;[#Mid(testString,st.pos[1],st.len[1])#]&lt;/B&gt;
   &lt;/cfoutput&gt;&lt;/p&gt;
&lt;hr size = &quot;2&quot; color = &quot;#0000A0&quot;&gt;
&lt;p&gt;However, if you use parentheses in the regular expression, the first 
element contains the position and length of the first instance 
of the whole expression. The position and length of the first instance
of each parenthesized subexpression within is included in additional
array elements.&lt;/p&gt;
&lt;p&gt;For example: 
&amp;lt;CFSET st1 = REFind(&quot;([[:alpha:]])[ ]+(\1)&quot;,testString,1,&quot;TRUE&quot;)&amp;gt;&lt;/p&gt;
&lt;cfset st1 = REFind(&quot;([[:alpha:]]+)[ ]+(\1)&quot;,testString,1,&quot;TRUE&quot;)&gt;
&lt;p&gt;The number of elements in each array is &lt;cfoutput&gt;#ArrayLen(st1.pos)#
&lt;/cfoutput&gt;.&lt;/p&gt;
&lt;p&gt;First whole expression match; position is 
   &lt;cfoutput&gt;#st1.pos[1]#;
      length is #st1.len[1]#; whole expression match is
      &lt;B&gt;[#Mid(testString,st1.pos[1],st1.len[1])#]&lt;/B&gt;
   &lt;/cfoutput&gt;&lt;/p&gt;
&lt;p&gt;Subsequent elements of the arrays provide the position and length of 
the first instance of each parenthesized subexpression therein.&lt;/p&gt;
 &lt;cfloop index = &quot;i&quot; from = &quot;2&quot; to = &quot;#ArrayLen(st1.pos)#&quot;&gt;
   &lt;p&gt;&lt;cfoutput&gt;Position is #st1.pos[i]#; Length is #st1.len[i]#;
Substring is &lt;B&gt;[#Mid(testString,st1.pos[i],st1.len[i])#]
&lt;/B&gt;&lt;/cfoutput&gt;&lt;/p&gt;
&lt;/cfloop&gt;&lt;br&gt; 
</pre>
         </td>
      </tr>
   </table>
   </div>
<div id="REG_EXPRESSION">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">REG_EXPRESSION</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>


<p>Regular expression for which to search. Case-sensitive.</p>

  </td>
  </tr>
  </table>
</div>
<div id="STRING">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">STRING</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>


<p>A string, or a variable that contains one, in which to search.</p>

  </td>
  </tr>
  </table>
</div>
<div id="START">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">START</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>


<p>Optional. A positive integer, or a variable that contains one. Position in the string at which to start search. The default value is 1.</p>

  </td>
  </tr>
  </table>
</div>
<div id="RETURNSUBEXPRESSIONS">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr>  
<td valign="top" class="name">RETURNSUBEXPRESSIONS</td>
  <td valign="top" nowrap class="compatibility">&nbsp;</td>
  </tr>
  <tr>
  <td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
  </tr>


<p>Optional. Boolean. Whether to return substrings of reg_expression, in arrays named len and pos:</p><ul>

<li>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.</li>

<li>False: the function returns the position in the string where the match begins. Default.</li>
</ul>


  </td>
  </tr>
  </table>
</div>

  </body>
</html>
