Getting started with Lists in ColdFusion

Readability

Getting started with Lists in ColdFusion

The fol­low­ing exam­ples show how you can get started with using the var­i­ous List func­tions in ColdFusion.

Cre­at­ing a new List in ColdFusion

The fol­low­ing exam­ple shows how you can cre­ate a sim­ple list in Cold­Fu­sion using the <CFSET> tag:


List items: #names#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il

By default a list is comma (,) sep­a­rated. The fol­low­ing exam­ple shows how you can use a pipe char­ac­ter (|) as a list delim­iter (this can be use­ful if your list items con­tain a comma character):


List items: #namesDelim#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Deter­min­ing the num­ber of items in a List in ColdFusion

The fol­low­ing exam­ple shows how you can deter­mine the num­ber of items in a List using the listLen() function:


List has #listLen(names)# items: #names#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il

If you are using a cus­tom list delim­iter you can pass an optional sec­ond argu­ment, delimiters, to the listLen() func­tion, as seen in the fol­low­ing example:


List has #listLen(namesDelim, '|')# items: #namesDelim#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Get­ting a spe­cific item from a List in ColdFusion

The fol­low­ing exam­ple shows how you can get a spe­cific item from a list in Cold­Fu­sion using the listGetAt() function:


The third item in the list is: #listGetAt(names, 3)#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

The third item in the list is: Grace

If you are using a cus­tom list delim­iter you can pass an optional third argu­ment, delimiters, to the listGetAt() func­tion, as seen in the fol­low­ing example:


The third item in the list is: #listGetAt(namesDelim, 3, '|')#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

The third item in the list is: Ryan, Grace

If you only want the first item in a list, last item in a list, or all items in the list except the first item, you can use the listFirst(), listLast(), or listRest() func­tions, as seen in the fol­low­ing example:



List has #listLen(names)# items: #names#
First item in list: #listFirst(names)#
Last item in list: #listLast(names)#
Rest items in list: #listRest(names)#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
First item in list: Xan­der
Last item in list: Taqu’il
Rest items in list: Wendell,Grace,Arthur,Stan,Taqu’il

If you are using a cus­tom list delim­iter you can pass an optional sec­on­dar­gu­ment, delimiters, to the listFirst(), listLast(), or listRest() func­tions, as seen in the fol­low­ing example:



List has #listLen(namesDelim, "|")# items: #namesDelim#
First item in list: #listFirst(namesDelim, "|")#
Last item in list: #listLast(namesDelim, "|")#
Rest items in list: #listRest(namesDelim, "|")#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
First item in list: Crews, Xan­der
Last item in list: Taqu’il
Rest items in list: Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Append­ing and prepend­ing items to a List in ColdFusion

The fol­low­ing exam­ple shows how you can append an item to the end of a list in Cold­Fu­sion using the listAppend() function:


List has #listLen(names)# items: #names#
List has #listLen(names)# items: #names#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 7 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il,Simon

If you are using a cus­tom list delim­iter you can pass an optional third argu­ment, delimiters, to the listAppend() func­tion, as seen in the fol­low­ing example:


List has #listLen(namesDelim, "|")# items: #namesDelim#
List has #listLen(namesDelim, "|")# items: #namesDelim#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 7 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il|Simon

The fol­low­ing exam­ple shows how you can prepend an item to the start of a list in Cold­Fu­sion using the listPrepend() function:


List has #listLen(names)# items: #names#
List has #listLen(names)# items: #names#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 7 items: Kill­face,Xander,Wendell,Grace,Arthur,Stan,Taqu’il

If you are using a cus­tom list delim­iter you can pass an optional third argu­ment, delimiters, to the listPrepend() func­tion, as seen in the fol­low­ing example:


List has #listLen(namesDelim, "|")# items: #namesDelim#
List has #listLen(namesDelim, "|")# items: #namesDelim#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 7 items: Kill­face|Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Insert­ing items to a List in ColdFusion

The fol­low­ing exam­ple shows how you can insert an item into a spe­cific posi­tion within a list in Cold­Fu­sion using the listInsertAt() function:


List has #listLen(names)# items: #names#
List has #listLen(names)# items: #names#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 7 items: Xan­der,Simon,Wendell,Grace,Arthur,Stan,Taqu’il

If you are using a cus­tom list delim­iter you can pass an optional fourth argu­ment, delimiters, to the listInsertAt() func­tion, as seen in the fol­low­ing example:


List has #listLen(namesDelim, "|")# items: #namesDelim#
List has #listLen(namesDelim, "|")# items: #namesDelim#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 7 items: Crews, Xan­der|Simon|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Delet­ing items from a List in ColdFusion

The fol­low­ing exam­ple shows how you can delete an item from a spe­cific posi­tion within a list in Cold­Fu­sion using the listDeleteAt() function:


List has #listLen(names)# items: #names#
List has #listLen(names)# items: #names#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 5 items: Xander,Grace,Arthur,Stan,Taqu’il

If you are using a cus­tom list delim­iter you can pass an optional third argu­ment, delimiters, to the listDeleteAt() func­tion, as seen in the fol­low­ing example:


List has #listLen(namesDelim, "|")# items: #namesDelim#
List has #listLen(namesDelim, "|")# items: #namesDelim#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 5 items: Crews, Xander|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Replac­ing items in a List in ColdFusion

The fol­low­ing exam­ple shows how you can replace an item at a spe­cific posi­tion within a list in Cold­Fu­sion using the listSetAt() function:


List has #listLen(names)# items: #names#
List has #listLen(names)# items: #names#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 6 items: Xan­der,Dar­celle,Grace,Arthur,Stan,Taqu’il

If you are using a cus­tom list delim­iter you can pass an optional fourth argu­ment, delimiters, to the listSetAt() func­tion, as seen in the fol­low­ing example:


List has #listLen(namesDelim, "|")# items: #namesDelim#
List has #listLen(namesDelim, "|")# items: #namesDelim#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 6 items: Crews, Xan­der|Jones, Dar­celle|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Loop­ing over items in a List in ColdFusion

The fol­low­ing exam­ple shows how you can loop over items in a list using the <CFLOOP> tag and spec­i­fy­ing the list and index attributes:


  • #currName#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

  • Xan­der
  • Wen­dell
  • Grace
  • Arthur
  • Stan
  • Taqu’il

If you are using a cus­tom list delim­iter you can spec­ify the delimiters argu­ment in the <CFLOOP> tag, as seen in the fol­low­ing example:


  • #currName#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

  • Crews, Xan­der
  • Stamps, Wen­dell
  • Ryan, Grace
  • Wat­ley, Arthur
  • Stan
  • Taqu’il

Chang­ing the delim­iter in a List in ColdFusion

The fol­low­ing exam­ple shows how you can change the delim­iter in a list in Cold­Fu­sion using the listChangeDelims() function:


List has #listLen(names)# items: #names#
List has #listLen(names, ";")# items: #names#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 6 items: Xan­der;Wen­dell;Grace;Arthur;Stan;Taqu’il

If you are using a cus­tom list delim­iter you can pass an optional third argu­ment, delimiters, to the listChangeDelims() func­tion, as seen in the fol­low­ing example:


List has #listLen(namesDelim, "|")# items: #namesDelim#
List has #listLen(namesDelim, ";")# items: #namesDelim#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 6 items: Crews, Xan­der;Stamps, Wen­dell;Ryan, Grace;Wat­ley, Arthur;Stan;Taqu’il

Sort­ing a List in ColdFusion

The fol­low­ing exam­ple shows how you can sort a list in Cold­Fu­sion using the listSort() function:


List has #listLen(names)# items: #names#
List has #listLen(names)# items: #names#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 6 items: Arthur,Grace,Stan,Taqu’il,Wendell,Xander

If you want to sort the list in descend­ing order you can pass an optional third argu­ment, sortOrder, to the listSort() func­tion, as seen in the fol­low­ing example:


List has #listLen(names)# items: #names#
List has #listLen(names)# items: #names#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 6 items: Xander,Wendell,Taqu’il,Stan,Grace,Arthur

If you are using a cus­tom list delim­iter you can pass an optional fourth argu­ment, delimiters, to the listSort() func­tion, as seen in the fol­low­ing example:


List has #listLen(namesDelim, "|")# items: #namesDelim#
List has #listLen(namesDelim, "|")# items: #namesDelim#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 6 items: Crews, Xander|Ryan, Grace|Stamps, Wendell|Stan|Taqu’il|Watley, Arthur

Deter­min­ing if an item or sub­string is in a List in ColdFusion

The fol­low­ing exam­ple shows how you can deter­mine if an item or sub­string exists in a list using Cold­Fu­sion and the listContains(), listContainsNoCase(), listFind(), and listFindNoCase() functions:



List has #listLen(names)# items: #names#
1) listFind('gra')? #listFind(names, "gra")#
2) listFindNoCase('gra')? #listFindNoCase(names, "gra")#
3) listFind('grace')? #listFind(names, "grace")#
4) listFindNoCase('grace')? #listFindNoCase(names, "grace")#
5) listContains('gra')? #listContains(names, "gra")#
6) listContainsNoCase('gra')? #listContainsNoCase(names, "gra")#
7) listContains('grace')? #listContains(names, "grace")#
8) listContainsNoCase('grace')? #listContainsNoCase(names, "grace")#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il

1) listFind(‘gra’)? 0
2) listFindNoCase(‘gra’)? 0
3) listFind(‘grace’)? 0
4) listFindNoCase(‘grace’)? 3

5) listContains(‘gra’)? 0
6) listContainsNoCase(‘gra’)? 3
7) listContains(‘grace’)? 0
8) listContainsNoCase(‘grace’)? 3

The dif­fer­ence between the listFind() and listContains() func­tions is that the listFind() func­tion deter­mines the index of the first list ele­ment in which a spec­i­fied value occurs, whereas the listContains() func­tion deter­mines the index of the first list ele­ment that con­tains a spec­i­fied sub­string. Or in other words, the listFind() func­tion only matches whole items, whereas the listContains() func­tion matches sub­strings within items. And the dif­fer­ence between the listFind() and listFindNoCase() func­tions is that listFind() is case sen­si­tive whereas listFindNoCase() is not.

If you are using a cus­tom list delim­iter you can pass an optional third argu­ment, delimiters, to the listFind(), listFindNoCase(), listContains(), or listContainsNoCase() func­tions, as seen in the fol­low­ing example:



List has #listLen(namesDelim, "|")# items: #namesDelim#
1) listFind('gra')? #listFind(namesDelim, "gra", "|")#
2) listFindNoCase('gra')? #listFindNoCase(namesDelim, "gra", "|")#
3) listFind('ryan, grace')? #listFind(namesDelim, "ryan, grace", "|")#
4) listFindNoCase('ryan, grace')? #listFindNoCase(namesDelim, "ryan, grace", "|")#
5) listContains('gra')? #listContains(namesDelim, "gra", "|")#
6) listContainsNoCase('gra')? #listContainsNoCase(namesDelim, "gra", "|")#
7) listContains('grace')? #listContains(namesDelim, "grace", "|")#
8) listContainsNoCase('grace')? #listContainsNoCase(namesDelim, "grace", "|")#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

1) listFind(‘gra’)? 0
2) listFindNoCase(‘gra’)? 0
3) listFind(‘ryan, grace’)? 0
4) listFindNoCase(‘ryan, grace’)? 3

5) listContains(‘gra’)? 0
6) listContainsNoCase(‘gra’)? 3
7) listContains(‘grace’)? 0
8) listContainsNoCase(‘grace’)? 3

Con­vert­ing a List to an array in ColdFusion

The fol­low­ing exam­ple shows how you can con­vert a list to an array in Cold­Fu­sion using the listToArray() function:


List has #listLen(names)# items: #names#

If you are using a cus­tom list delim­iter you can pass an optional sec­ond argu­ment, delimiters, to the listToArray() func­tion, as seen in the fol­low­ing example:


List has #listLen(namesDelim, "|")# items: #namesDelim#

Deter­min­ing the num­ber of instances of a spec­i­fied value in a List in ColdFusion

The fol­low­ing exam­ple shows how you can deter­mine the num­ber of instances of a spec­i­fied value in a list in Cold­Fu­sion using the listValueCount() and listValueCountNoCase() functions:



List has #listLen(names)# items: #names#
listValueCount('Wendell'): #listValueCount(names, "Wendell")#
listValueCountNoCase("wendell"): #listValueCountNoCase(names, "wendell")#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 7 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il,Wendell X

listValueCount(‘Wendell’): 1
listValueCountNoCase(“wendell”): 1

If you are using a cus­tom list delim­iter you can pass an optional third argu­ment, delimiters, to the listValueCount() and listValueCountNoCase() func­tions, as seen in the fol­low­ing example:



List has #listLen(namesDelim, "|")# items: #namesDelim#
listValueCount('Wendell'): #listValueCount(namesDelim, "Wendell", "|")#
listValueCountNoCase("wendell"): #listValueCountNoCase(namesDelim, "wendell", "|")#

The pre­vi­ous exam­ple out­puts the fol­low­ing text:

List has 7 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il|Wendell X

listValueCount(‘Wendell’): 0
listValueCountNoCase(“wendell”): 0

In the pre­vi­ous exam­ple, nei­ther the listValueCount() or listValueCountNoCase() func­tions matched any items. This is because the listValueCount() method matches whole items, not sub­strings within items.

The following examples show how you can get started with using the various List functions in ColdFusion.

Creating a new List in ColdFusion

The following example shows how you can create a simple list in ColdFusion using the <CFSET> tag:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>List items: <em>#names#</em></cfoutput>

The previous example outputs the following text:

List items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il

By default a list is comma (,) separated. The following example shows how you can use a pipe character (|) as a list delimiter (this can be useful if your list items contain a comma character):

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>List items: <em>#namesDelim#</em></cfoutput>

The previous example outputs the following text:

List items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Determining the number of items in a List in ColdFusion

The following example shows how you can determine the number of items in a List using the listLen() function:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>List has #listLen(names)# items: <em>#names#</em></cfoutput>

The previous example outputs the following text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il

If you are using a custom list delimiter you can pass an optional second argument, delimiters, to the listLen() function, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>List has #listLen(namesDelim, '|')# items: <em>#namesDelim#</em></cfoutput>

The previous example outputs the following text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Getting a specific item from a List in ColdFusion

The following example shows how you can get a specific item from a list in ColdFusion using the listGetAt() function:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>The third item in the list is: <em>#listGetAt(names, 3)#</em></cfoutput>

The previous example outputs the following text:

The third item in the list is: Grace

If you are using a custom list delimiter you can pass an optional third argument, delimiters, to the listGetAt() function, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>The third item in the list is: <em>#listGetAt(namesDelim, 3, '|')#</em></cfoutput>

The previous example outputs the following text:

The third item in the list is: Ryan, Grace

If you only want the first item in a list, last item in a list, or all items in the list except the first item, you can use the listFirst(), listLast(), or listRest() functions, as seen in the following example:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>
List has #listLen(names)# items: <em>#names#</em><br/>
First item in list: <em>#listFirst(names)#</em><br/>
Last item in list: <em>#listLast(names)#</em><br/>
Rest items in list: <em>#listRest(names)#</em><br/>
</cfoutput>

The previous example outputs the following text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
First item in list: Xander
Last item in list: Taqu’il
Rest items in list: Wendell,Grace,Arthur,Stan,Taqu’il

If you are using a custom list delimiter you can pass an optional secondargument, delimiters, to the listFirst(), listLast(), or listRest() functions, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>
List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/>
First item in list: <em>#listFirst(namesDelim, "|")#</em><br/>
Last item in list: <em>#listLast(namesDelim, "|")#</em><br/>
Rest items in list: <em>#listRest(namesDelim, "|")#</em><br/>
</cfoutput>

The previous example outputs the following text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
First item in list: Crews, Xander
Last item in list: Taqu’il
Rest items in list: Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Appending and prepending items to a List in ColdFusion

The following example shows how you can append an item to the end of a list in ColdFusion using the listAppend() function:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>
 
<cfset names = listAppend(names, "Simon") />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 7 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il,Simon

If you are using a custom list delimiter you can pass an optional third argument, delimiters, to the listAppend() function, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>
 
<cfset namesDelim = listAppend(namesDelim, "Simon", "|") />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 7 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il|Simon

The following example shows how you can prepend an item to the start of a list in ColdFusion using the listPrepend() function:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>
 
<cfset names = listPrepend(names, "Killface") />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 7 items: Killface,Xander,Wendell,Grace,Arthur,Stan,Taqu’il

If you are using a custom list delimiter you can pass an optional third argument, delimiters, to the listPrepend() function, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>
 
<cfset namesDelim = listPrepend(namesDelim, "Killface", "|") />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 7 items: Killface|Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Inserting items to a List in ColdFusion

The following example shows how you can insert an item into a specific position within a list in ColdFusion using the listInsertAt() function:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>
 
<cfset names = listInsertAt(names, 2, "Simon") />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 7 items: Xander,Simon,Wendell,Grace,Arthur,Stan,Taqu’il

If you are using a custom list delimiter you can pass an optional fourth argument, delimiters, to the listInsertAt() function, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>
 
<cfset namesDelim = listInsertAt(namesDelim, 2, "Simon", "|") />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 7 items: Crews, Xander|Simon|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Deleting items from a List in ColdFusion

The following example shows how you can delete an item from a specific position within a list in ColdFusion using the listDeleteAt() function:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>
 
<cfset names = listDeleteAt(names, 2) />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 5 items: Xander,Grace,Arthur,Stan,Taqu’il

If you are using a custom list delimiter you can pass an optional third argument, delimiters, to the listDeleteAt() function, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>
 
<cfset namesDelim = listDeleteAt(namesDelim, 2, "|") />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 5 items: Crews, Xander|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Replacing items in a List in ColdFusion

The following example shows how you can replace an item at a specific position within a list in ColdFusion using the listSetAt() function:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>
 
<cfset names = listSetAt(names, 2, "Darcelle") />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 6 items: Xander,Darcelle,Grace,Arthur,Stan,Taqu’il

If you are using a custom list delimiter you can pass an optional fourth argument, delimiters, to the listSetAt() function, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>
 
<cfset namesDelim = listSetAt(namesDelim, 2, "Jones, Darcelle", "|") />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 6 items: Crews, Xander|Jones, Darcelle|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

Looping over items in a List in ColdFusion

The following example shows how you can loop over items in a list using the <CFLOOP> tag and specifying the list and index attributes:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<ul>
<cfoutput>
<cfloop list="#names#" index="currName">
    <li>#currName#</li>
</cfloop>
</cfoutput>
</ul>

The previous example outputs the following text:

  • Xander
  • Wendell
  • Grace
  • Arthur
  • Stan
  • Taqu’il

If you are using a custom list delimiter you can specify the delimiters argument in the <CFLOOP> tag, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<ul>
<cfoutput>
<cfloop list="#namesDelim#" index="currName" delimiters="|">
    <li>#currName#</li>
</cfloop>
</cfoutput>
</ul>

The previous example outputs the following text:

  • Crews, Xander
  • Stamps, Wendell
  • Ryan, Grace
  • Watley, Arthur
  • Stan
  • Taqu’il

Changing the delimiter in a List in ColdFusion

The following example shows how you can change the delimiter in a list in ColdFusion using the listChangeDelims() function:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>
 
<cfset names = listChangeDelims(names, ";") />
<cfoutput>List has #listLen(names, ";")# items: <em>#names#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 6 items: Xander;Wendell;Grace;Arthur;Stan;Taqu’il

If you are using a custom list delimiter you can pass an optional third argument, delimiters, to the listChangeDelims() function, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>
 
<cfset namesDelim = listChangeDelims(namesDelim, ";", "|") />
<cfoutput>List has #listLen(namesDelim, ";")# items: <em>#namesDelim#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 6 items: Crews, Xander;Stamps, Wendell;Ryan, Grace;Watley, Arthur;Stan;Taqu’il

Sorting a List in ColdFusion

The following example shows how you can sort a list in ColdFusion using the listSort() function:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>
 
<cfset names = listSort(names, "textNoCase") />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 6 items: Arthur,Grace,Stan,Taqu’il,Wendell,Xander

If you want to sort the list in descending order you can pass an optional third argument, sortOrder, to the listSort() function, as seen in the following example:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>
 
<cfset names = listSort(names, "textNoCase", "desc") />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il
List has 6 items: Xander,Wendell,Taqu’il,Stan,Grace,Arthur

If you are using a custom list delimiter you can pass an optional fourth argument, delimiters, to the listSort() function, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>
 
<cfset namesDelim = listSort(namesDelim, "textNoCase", "asc", "|") />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>

The previous example outputs the following text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il
List has 6 items: Crews, Xander|Ryan, Grace|Stamps, Wendell|Stan|Taqu’il|Watley, Arthur

Determining if an item or substring is in a List in ColdFusion

The following example shows how you can determine if an item or substring exists in a list using ColdFusion and the listContains(), listContainsNoCase(), listFind(), and listFindNoCase() functions:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>
List has #listLen(names)# items: <em>#names#</em><br/>
 
1) listFind('gra')? #listFind(names, "gra")#<br/>
2) listFindNoCase('gra')? #listFindNoCase(names, "gra")#<br/>
3) listFind('grace')? #listFind(names, "grace")#<br/>
4) listFindNoCase('grace')? #listFindNoCase(names, "grace")#<br/>
 
5) listContains('gra')? #listContains(names, "gra")#<br/>
6) listContainsNoCase('gra')? #listContainsNoCase(names, "gra")#<br/>
7) listContains('grace')? #listContains(names, "grace")#<br/>
8) listContainsNoCase('grace')? #listContainsNoCase(names, "grace")#<br/>
</cfoutput>

The previous example outputs the following text:

List has 6 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il

1) listFind(‘gra’)? 0
2) listFindNoCase(‘gra’)? 0
3) listFind(‘grace’)? 0
4) listFindNoCase(‘grace’)? 3

5) listContains(‘gra’)? 0
6) listContainsNoCase(‘gra’)? 3
7) listContains(‘grace’)? 0
8) listContainsNoCase(‘grace’)? 3

The difference between the listFind() and listContains() functions is that the listFind() function determines the index of the first list element in which a specified value occurs, whereas the listContains() function determines the index of the first list element that contains a specified substring. Or in other words, the listFind() function only matches whole items, whereas the listContains() function matches substrings within items. And the difference between the listFind() and listFindNoCase() functions is that listFind() is case sensitive whereas listFindNoCase() is not.

If you are using a custom list delimiter you can pass an optional third argument, delimiters, to the listFind(), listFindNoCase(), listContains(), or listContainsNoCase() functions, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>
List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/>
 
1) listFind('gra')? #listFind(namesDelim, "gra", "|")#<br/>
2) listFindNoCase('gra')? #listFindNoCase(namesDelim, "gra", "|")#<br/>
3) listFind('ryan, grace')? #listFind(namesDelim, "ryan, grace", "|")#<br/>
4) listFindNoCase('ryan, grace')? #listFindNoCase(namesDelim, "ryan, grace", "|")#<br/>
 
5) listContains('gra')? #listContains(namesDelim, "gra", "|")#<br/>
6) listContainsNoCase('gra')? #listContainsNoCase(namesDelim, "gra", "|")#<br/>
7) listContains('grace')? #listContains(namesDelim, "grace", "|")#<br/>
8) listContainsNoCase('grace')? #listContainsNoCase(namesDelim, "grace", "|")#<br/>
</cfoutput>

The previous example outputs the following text:

List has 6 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il

1) listFind(‘gra’)? 0
2) listFindNoCase(‘gra’)? 0
3) listFind(‘ryan, grace’)? 0
4) listFindNoCase(‘ryan, grace’)? 3

5) listContains(‘gra’)? 0
6) listContainsNoCase(‘gra’)? 3
7) listContains(‘grace’)? 0
8) listContainsNoCase(‘grace’)? 3

Converting a List to an array in ColdFusion

The following example shows how you can convert a list to an array in ColdFusion using the listToArray() function:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il" />
<cfoutput>List has #listLen(names)# items: <em>#names#</em><br/></cfoutput>
<cfdump var="#listToArray(names)#" />

If you are using a custom list delimiter you can pass an optional second argument, delimiters, to the listToArray() function, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il" />
<cfoutput>List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/></cfoutput>
<cfdump var="#listToArray(namesDelim, '|')#" />

Determining the number of instances of a specified value in a List in ColdFusion

The following example shows how you can determine the number of instances of a specified value in a list in ColdFusion using the listValueCount() and listValueCountNoCase() functions:

<cfset names = "Xander,Wendell,Grace,Arthur,Stan,Taqu'il,Wendell X" />
<cfoutput>
List has #listLen(names)# items: <em>#names#</em><br/>
 
listValueCount('Wendell'): #listValueCount(names, "Wendell")#<br/>
listValueCountNoCase("wendell"): #listValueCountNoCase(names, "wendell")#<br/>
</cfoutput>

The previous example outputs the following text:

List has 7 items: Xander,Wendell,Grace,Arthur,Stan,Taqu’il,Wendell X

listValueCount(‘Wendell’): 1
listValueCountNoCase(“wendell”): 1

If you are using a custom list delimiter you can pass an optional third argument, delimiters, to the listValueCount() and listValueCountNoCase() functions, as seen in the following example:

<cfset namesDelim = "Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu'il|Wendell X" />
<cfoutput>
List has #listLen(namesDelim, "|")# items: <em>#namesDelim#</em><br/>
 
listValueCount('Wendell'): #listValueCount(namesDelim, "Wendell", "|")#<br/>
listValueCountNoCase("wendell"): #listValueCountNoCase(namesDelim, "wendell", "|")#<br/>
</cfoutput>

The previous example outputs the following text:

List has 7 items: Crews, Xander|Stamps, Wendell|Ryan, Grace|Watley, Arthur|Stan|Taqu’il|Wendell X

listValueCount(‘Wendell’): 0
listValueCountNoCase(“wendell”): 0

In the previous example, neither the listValueCount() or listValueCountNoCase() functions matched any items. This is because the listValueCount() method matches whole items, not substrings within items.

Leave a Reply