ListQualify

Description

Inserts a string at the beginning and end of list elements.

Return value

A copy of the list, with qualifier before and after the specified element(s).

Syntax

ListQualify(list, qualifier [, delimiters ] [, elements ])

History

New in ColdFusion MX: As the elements parameter value, you must specify "all" or "char"; otherwise, ColdFusion throws an exception. (In earlier releases, the function ignored an invalid value, and used "all"; this was inconsistent with other functions.)

Parameters

Parameter Description

list
A list or a variable that contains one.

qualifier
A string or a variable that contains one. Character or string to insert before and after the list elements specified in the elements attribute.

delimiters
A string or a variable that contains one. Character(s) that separate list elements. Default: comma.
If this parameter contains more than one character, ColdFusion processes each occurrence of each character as a delimiter.

elements

all: all elements

char: elements that are composed of alphabetic characters

Parameter	Description
list	A list or a variable that contains one.
qualifier	A string or a variable that contains one. Character or string to insert before and after the list elements specified in the `elements` attribute.
delimiters	A string or a variable that contains one. Character(s) that separate list elements. Default: comma. If this parameter contains more than one character, ColdFusion processes each occurrence of each character as a delimiter.
elements	all: all elements char: elements that are composed of alphabetic characters

Usage

The new list might not preserve all of the delimiters in the list.

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

Example

<cfquery name = "GetEmployeeNames" datasource = "cfsnippets">
SELECT   FirstName, LastName
FROM   Employees
</cfquery>

<h3>ListQualify Example</h3>
<p>This example uses ListQualify to put the full names of the 
employees in the query within quotation marks.</p>
<cfset myArray = ArrayNew(1)>

<!--- loop through query; append these names successively to the last element --->
<cfloop query = "GetEmployeeNames">
  <cfset temp = ArrayAppend(myArray, "#FirstName# #LastName#")>
</cfloop>

<!--- sort that array descending alphabetically --->
<cfset myAlphaArray = ArraySort(myArray, "textnocase")>

<!--- show the resulting array as a list --->
<cfset myList = ArrayToList(myArray, ",")>

<cfoutput>
  <p>The contents of the unqualified list are as follows:  </p>
  #myList#
</cfoutput>

<!--- show the resulting alphabetized array as a qualified list with 
single quotes around each full name.    --->
<cfset qualifiedList1 = ListQualify(myList,"'",",","CHAR")>

<!--- output the array as a list --->
<cfoutput>
  <p>The contents of the qualified list are as follows:  </p>
  <p>#qualifiedList1#</p>
</cfoutput>

<!--- show the resulting alphabetized array as a qualified list with quotation
marks around each full name. We use &quot; to denote quotation marks
because the quotation mark character is a control character. --->
<cfset qualifiedList2 = ListQualify(myList,"&quot;",",","CHAR")>

<!--- output the array as a list --->
<cfoutput>
  <p>The contents of the second qualified list are:  </p>
  <p>#qualifiedList2#</p>
</cfoutput>