Description

Sorts list elements according to a sort type and sort order.

Returns

A copy of a list, sorted.

Category

List functions

Function syntax

ListSort(list,sortType,[sortOrder=asc, delimiters=',' ,includeEmptyFields=false, localeSensitive=false])

Syntax with callback

ListSort(list,callback)

See also

Lists in Using ColdFusion Variables in the Developing ColdFusion Applications

History

ColdFusion (2018 release): Introduced named parameters.

ColdFusion 10: Added support for all Java supported locale-specific characters (including support for umlaut characters). A flag for this support has been added for sorttype = "text" or sorttype = "textnocase".

ColdFusion MX: Changed the order in which sorted elements are returned: in a textnocase, descending sort, this function might return elements in a different sort order than in earlier releases. If sortTtype = "textnocase" and sortOrder = "desc", ColdFusion MX processes elements that differ only in case differently from earlier releases. ColdFusion MX outputs the elements in the reverse of the ascending order. Earlier releases do not change order of elements that differ only in case. Both operations are correct. The new operation ensures that an ascending and descending sort output elements in exactly reverse order.For example, in a textnocase, desc sort of d,a,a,b,A, the following occurs:

  • ColdFusion MX returns d,b,A,a,a
  • Earlier ColdFusion releases return d,b,a,a,A(In a textnocaseasc sort, all ColdFusion releases return a,a,A,b,d.)

Parameters

Parameter

Required/Optional Default

Description

list

Required  

A list or a variable that contains one.

includeEmptyFields

Optional no

Set to yes to include empty fields.

localeSensitive

Optional false

Specify if you wish to do a locale-sensitive sorting. The default value is false.

sortType

Optional  
  • numeric: sorts numbers
  • text: sorts text alphabetically, taking case into account (also known as case sensitive). All letters of one case precede the first letter of the other case:
  • aabzABZ, if sortOrder = "asc" (ascending sort)- ZBAzbaa, if sortOrder = "desc" (descending sort)
  • textnocase: sorts text alphabetically, without regard to case (also known as case-insensitive). A letter in varying cases precedes the next letter:
  • aAaBbBzzZ, in an ascending sort; preserves original intra-letter order - ZzzBbBaAa, in a descending sort; reverses original intra-letter order

sortOrder

Required asc
  • asc - ascending sort order. Default.
  • aabzABZ or aAaBbBzzZ, depending on value of sortType, for letters- from smaller to larger, for numbers
  • desc - descending sort order.
  • ZBAzbaa or ZzzBbBaAa, depending on value of sortType, for letters- from larger to smaller, for numbers

delimiters

Optional ,

A string or a variable that contains one. Characters that separate list elements. The default value is comma. If this parameter contains more than one character, ColdFusion uses the first character in the string as the delimiter, and ignores the rest.

callback Optional   A function that takes two elements of the list and returns 1, 0 or -1, if the first value is greater than, equal to, or less than the second value, respectively.

Usage

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

Example

<h3>ListSort Example</h3> 

<!--- Find a list of users who wrote messages ---> 
<cfquery name = "GetMessageUser" datasource = "cfdocexamples"> 
SELECT Username, Subject, Posted 
FROM Messages 
</cfquery> 

<cfset myList = ValueList(GetMessageUser.UserName)> 
<p>Here is the unsorted list. </p> 
<cfoutput>#myList# 
</cfoutput> 
<p>Here is the list sorted alphabetically:</p> 
<cfset sortedList = ListSort(myList, "Text")> 
<cfoutput>#sortedList# 
</cfoutput> 

<p>Here is a numeric list that is to be sorted in descending order.</p> 
<cfset sortedNums = ListSort("12,23,107,19,1,65","Numeric", "Desc")> 
<cfoutput>#sortedNums# </cfoutput> 

<p>Here is a list that must be sorted numerically, since it contains 
negative and positive numbers, and decimal numbers. </p> 
<cfset sortedNums2 = ListSort("23.75;-34,471:100,-9745","Numeric", "ASC", ";,:")> 
<cfoutput>#sortedNums2# </cfoutput> 

<p>Here is a list to be sorted alphabetically without consideration of case.</p> 
<cfset sortedMix = 
ListSort("hello;123,HELLO:jeans,-345,887;ColdFusion:coldfusion", 
"TextNoCase", "ASC", ";,:")> 
<cfoutput>#sortedMix# </cfoutput>

Example with callback

<cfscript>
       myList="ColdFusion,COLDFUSION,Cold Fusion,Coldfusion";
       // define callback function
       function callback(e1,e2){
             return compareNoCase(e1,e2);
       }
       mySortedList=ListSort(myList,callback);
       writeOutput(mySortedList);
</cfscript>

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy