ListQualify

Description

Returns a list with a qualifying character around each item in the list, such as double or single quotes.

Syntax


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

Parameters

Parameter

Description

list
A list of items or a variable that names a list.

qualifier
The character to place at the beginning and end of each item in the list.

delimiters
Set of delimiters used in list.

elements
The keyword "ALL" or "CHAR." If you specify "ALL," the function qualifies all items in the list. If you specify "CHAR," the function qualifiers only items comprised of alphabetic characters.

Parameter	Description
list	A list of items or a variable that names a list.
qualifier	The character to place at the beginning and end of each item in the list.
delimiters	Set of delimiters used in list.
elements	The keyword "ALL" or "CHAR." If you specify "ALL," the function qualifies all items in the list. If you specify "CHAR," the function qualifiers only items comprised of alphabetic characters.

Usage

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

Note

ColdFusion ignores empty list elements; thus, a list that is defined as "a,b,c,,,d" is treated as a four element list.

Example

<!--- This example uses ListQualify to put quotes around each 

   employees full name --->

<html>

<head>

<title>ListQualify Example</title>

</head>



<body bgcolor = "#FFFFD5">



<cfquery name = "GetEmployeeNames" datasource = "cfsnippets">

SELECT   FirstName, LastName

FROM   Employees

</cfquery>



<H3>ListQualify Example</H3>

<P>This example uses ListQualify to place the full names of the employees found

in the query within quotation marks.</P>



<cfset myArray = ArrayNew(1)>



<!--- loop through the query and 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. Note that 

   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 as follows:  </P>

  <P>#qualifiedList2#</P>

</cfoutput>

</body>

</html>