REFind

Description

Returns the position of the first occurrence of a regular expression in a string starting from a specified position. Returns 0 if no occurrences are found. The search is case sensitive.

Returns the position and length of the first occurrence of a regular expression in a string, if the returnsubexpressions parameter is set to True.

Syntax


REFind(reg_expression, string [, start ] 

  [, returnsubexpressions ] )

Parameters

Parameter

Description

reg_expression
Regular expression used for search. Can include POSIX-specified character classes (for example, [[:alpha:]], [[:digit:]], [[:upper:]], and [[:lower:]]).

string
String to search

start
Optional. Starting position for the search. Default is 1.

returnsubexpressions
Optional. Boolean value that indicates whether a substring is returned.
If TRUE, the function returns a CFML structure composed of two arrays that contain the position and length of the first substring that matches the search criteria. You can retrieve the position and length of the matching subexpression using the keys "pos" and "len." If there are no occurrences of the regular expression, the "pos" and the "len" arrays each contain one element that has a value of zero. If FALSE, a scalar value is returned that indicates the position of the first occurrence of a regular expression. The default is FALSE.

Parameter	Description
reg_expression	Regular expression used for search. Can include POSIX-specified character classes (for example, [[:alpha:]], [[:digit:]], [[:upper:]], and [[:lower:]]).
string	String to search
start	Optional. Starting position for the search. Default is 1.
returnsubexpressions	Optional. Boolean value that indicates whether a substring is returned. If TRUE, the function returns a CFML structure composed of two arrays that contain the position and length of the first substring that matches the search criteria. You can retrieve the position and length of the matching subexpression using the keys "pos" and "len." If there are no occurrences of the regular expression, the "pos" and the "len" arrays each contain one element that has a value of zero. If FALSE, a scalar value is returned that indicates the position of the first occurrence of a regular expression. The default is FALSE.

Usage

To find multiple instances of a substring, you must call REFind more than once, each time with a different starting position. To determine the next starting position for the function, use the returnsubexpressions parameter and add the value returned in the position key to the value in the length key.

If you do not use parentheses in the regular expression, returnsubexpressions returns one-element arrays that denote the position and length of the first match found.

If you use parentheses in the regular expression, returnsubexpressions returns the position and length of the first match of the regular expression in the first element of the respective arrays. The position and length of the first instance of each subexpression in the regular expression are returned in subsequent array elements.

Example

<!--- This example shows the use of REFind --->

<html>

<head>

<title>

REFind Example

</title>

</head>

<body>



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



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 aregular

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, you must 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")>

<P>

  <cfoutput>

  The number of elements in each array: #ArrayLen(st.pos)#.

  </cfoutput>

</P>

<P><b>The number of elements in the pos and len arrays is always one

if you do not use parentheses in the regular expression.</b></P>

<P>The value of st.pos[1] is: <cfoutput>#st.pos[1]#.</cfoutput></P>

<P>The value of st.len[1] is: <cfoutput>#st.len[1]#.</cfoutput></P>

<P>

  <cfoutput>

  Substring is <b>[#Mid(testString,st.pos[1],st.len[1])#]</B>

  </cfoutput>

</P>



<hr size = "2" color = "#0000A0">



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



<P>For example: 

&lt;CFSET st1 = REFind("([[:alpha:]])[ ]+(\1)",testString,1,"TRUE")&gt;</P>



<cfset st1 = REFind("([[:alpha:]]+)[ ]+(\1)",testString,1,"TRUE")>



<P>The number of elements in each array is <cfoutput>#ArrayLen(st1.pos)#</cfoutput>.</P>



<P>First whole expression match; position is <cfoutput>#st1.pos[1]#;

  length is #st1.len[1]#; whole expression match is

  <B>[#Mid(testString,st1.pos[1],st1.len[1])#]</B></cfoutput></P>

<P>Subsequent elements of the arrays provide the position and 

length of the first instance of each parenthesized subexpression 

therein.</P>

 <CFLOOP index = "i" from = "2" to = "#ArrayLen(st1.pos)#">

  <P><cfoutput>Position is #st1.pos[i]#; Length is #st1.len[i]#;

Substring is <B>[#Mid(testString,st1.pos[i],st1.len[i])#]</B></cfoutput></P>

</CFLOOP><BR>  

</body>

</html>