ListQualify

Description

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

Returns

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

Function syntax

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

History

ColdFusion MX: Changed behavior: 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` parameter.
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 uses the first character as the delimiter and ignores the remaining characters.
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 = "cfdocexamples">
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 quotation marks 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>

Version 7

Comments

williambq said on Jun 25, 2007 at 3:00 PM :

When using this listQualifier function, it states the "all|char" parameter is *not* optional, which I have not tested, just am using 'all'. However, by using this *optional* property, you are also forced to provide the delimeters *optional* property as well. Thus LISTQUALIFY(ARGUMENTS.TYPE , '"' , , 'all' ) will *NOT* be the same as LISTQUALIFY(ARGUMENTS.TYPE , '"' , ',' , 'all' ) whereas the first case will give you a false negative all the time by trying find *all* in the provided list as a substring delimiter... but not throw, suggesting the last optional element which is listed as *must be provided* in fact, does not need to be provided...

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/00000560.htm