REFindNoCase

Description

Returns the position of the first occurrence of a regular expression in a string starting from a specified position, if the returnsubexpressions parameter is not set to True. Returns 0 if no occurrences are found. The search is case-insensitive.

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


REFindNoCase(reg_expression, string [, start ] 

  [, returnsubexpressions ] )

Parameters

Parameter

Description

reg_expression
Regular expression used for search. The regular expression 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. A Boolean value that indicates whether a substring is returned. If you set this parameter to TRUE, the function returns a CFML structure composed of two single-element arrays that contain the position and length of the first substring that matches the criteria of the search. You can retrieve the position and length of the matching subexpression with 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 you set this parameter to FALSE, a scalar value is returned that indicates the position of the first occurrence of a regular expression. The default value of this parameter is FALSE.

Parameter	Description
reg_expression	Regular expression used for search. The regular expression 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. A Boolean value that indicates whether a substring is returned. If you set this parameter to TRUE, the function returns a CFML structure composed of two single-element arrays that contain the position and length of the first substring that matches the criteria of the search. You can retrieve the position and length of the matching subexpression with 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 you set this parameter to FALSE, a scalar value is returned that indicates the position of the first occurrence of a regular expression. The default value of this parameter 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, the returnsubexpressions parameter returns single-element arrays that denote the position and length of the first match found in the string.

If you use parentheses to denote subexpressions within the regular expression, the returnsubexpressions parameter 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 within the regular expression are returned in subsequent array elements.

Example

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

<html>



<head>

<title>

REFindNoCase Example

</title>

</head>



<body>



<H3>REFindNoCase Example</H3>



<P>This example demonstrates the use of the REFindNoCase function with

and without the <i>returnsubexpressions</i> parameter set to True.</P> 



<P>If you do not use the <i>returnsubexpressions</i> parameter, 

REFindNoCase 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>REFindNoCase("a+c+", "abcaaccdd"):  

<cfoutput>#REFindNoCase("a+c+", "abcaaccdd")#</cfoutput></P>

<P>REFindNoCase("a+c*", "abcaaccdd"):  

<cfoutput>#REFindNoCase("a+c*", "abcaaccdd")#</cfoutput></P>

<P>REFindNoCase("[[:alpha:]]+", "abcaacCDD"):  

<cfoutput>#REFindNoCase("[[:alpha:]]+", "abcaacCDD")#</cfoutput></P>

<P>REFindNoCase("[\?&]rep = ", "report.cfm?rep = 1234&u = 5"):

<cfoutput>#REFindNoCase("[\?&]rep = ", "report.cfm?rep = 1234&u = 5")#</cfoutput>

</P>

<!--- Set startPos to one; returnMatchedSubexpressions = TRUE --->

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



<P>If you do use the <i>returnssubexpression</i> parameter,

REFindNoCase 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 the 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 REFindNoCase to search this string is: 

<b>REFindNoCase("[[:alpha:]]+",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 = REFindNoCase("[[:alpha:]]+",testString,1,"TRUE")&gt;

<cfset st = REFindNoCase("[[: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 will always be 

one if you do not use parentheses to denote subexpressions 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 to denote subexpressions in the 

regular expression, you will find that 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 subexpression within will be included in additional 

array elements.</P>



<P>For example:

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



<cfset st1 = REFindNoCase("([[: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>