View comments | RSS feed

ListContains

Description

Determines the index of the first list element that contains a specified substring.

Returns

Index of the first list element that contains substring. If not found, returns zero.

Category

List functions

Function syntax

ListContains(list, substring [, delimiters ])

See also

ListContainsNoCase, ListFind; Lists in Using ColdFusion Variables in ColdFusion MX Developer's Guide

Parameters

Parameter Description

list

A list or a variable that contains one.

substring

A string or a variable that contains one. The search is case-sensitive.

delimiters

A string or a variable that contains one. Character(s) that separate list elements. The default value is comma.

If this parameter contains more than one character, ColdFusion processes each occurrence of each character as a delimiter.

Usage

ColdFusion ignores empty list elements; thus, the list "a,b,c,,,d" has four elements.

Example

<!--- This example shows differences between ListContains and ListFind --->
<!--- Create a list composed of the elements one, two, three. ---->
<cfset aList = "one">
<cfset aList = ListAppend(aList, "two")>
<cfset aList = ListAppend(aList, "three")>
<p>Here is a list: <cfoutput>#aList#</cfoutput>
<p><strong>ListContains</strong> checks for substring "wo" in the list elements:
<cfoutput>
   <p>&nbsp;&nbsp;&nbsp;Substring "wo" is in 
<B>element #ListContains(aList, "wo")#</B> of list.
</cfoutput>
<p>ListFind cannot check for a substring within an element; therefore, in the 
   code, it does not find substring "wo" (it returns 0):
<cfoutput>
   <p>&nbsp;&nbsp;&nbsp;Substring "wo" is in <b>element #ListFind(aList, "wo")#
   </b> of the list.</cfoutput>
<p><p>If you specify a string that exactly equals an entire list element, such
   as "two", both ListContains and ListFind find it, in the second element:
   <p>&nbsp;&nbsp;&nbsp;<strong>ListContains</strong>: 
<cfoutput>
The string "two" is in <b>element #ListContains(aList, "two")#</b> of the list.
</cfoutput>
&nbsp;&nbsp;&nbsp;<p><strong>ListFind</strong>: 
<cfoutput>
The string "two" is in <b>element #ListFind(aList, "two")#</b> of the list.
</cfoutput>

ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | KnowledgeBase | Bug Reporting

Version 7

Comments


skibama1 said on Mar 5, 2007 at 3:51 AM :
I think some clarification in what this function really does should be documented. It took me forever to figure out the difference in this tag and the ListFind function.

The ListContains function looks at each inidividual member of a list for a specific value. For example, ListContains("436,4,232,934", 4) would return the 1st, 2nd and 4th indexes - even though the value itself is not in the list.

The ListFind function looks at the value itself of each individual index. For example, ListFind("436,4,232,934", 4) would return only the 3rd index because it's equal to the value itself.
skibama1 said on Mar 5, 2007 at 11:18 AM :
Ooops, last sentence should say 2nd index.

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/7/htmldocs/00000549.htm