StructSort

Description

Returns a sorted array of the top level keys in a structure. Sorts using alphabetic or numeric sorting, and can sort based on the values of any structure element.

Returns

An array of top-level key names (strings), sorted by the value of the specified subelement.

Category

Structure functions

Function syntax

StructSort(base, sortType, sortOrder, pathToSubElement)

See also

Structure functions; Structure functions in the Developing ColdFusion Applications

Parameters

Parameter

Description

base

A ColdFusion structure with one field (an associative array).

sortType

  • numeric

  • text: case sensitive (all lowercase letters precede the first uppercase letter). Default.

  • textnocase

sortOrder

  • asc: ascending (a to z) sort order. Default.

  • desc: descending (z to a) sort order

pathToSubElement

String or a variable that contains one.

Path to apply to each top-level key, to reach element value by which to sort. The default value is nothing (top-level entries sorted by their own values).

Usage

The pathToSubElement string does not support array notation, and only supports substructures of structures.

This function does not sort or change the structure.

Example

<cfscript> 
    salaries = StructNew() ; 
    employees = StructNew() ; 
    departments = StructNew() ; 
    for ( i=1; i lt 6; i=i+1 ) 
    { 
        salary = 120000 - i*10000 ; 
        salaries["employee#i#"] = salary ; 
         
        employee = StructNew() ; 
        employee["salary"] = salary ;  
        // employee.salary = salary ; 
        employees["employee#i#"] = employee ; 
         
        departments["department#i#"] = StructNew() ; 
        departments["department#i#"].boss = employee ;         
    } 
</cfscript> 
 
<cfoutput> 
<p>list of employees based on the salary (text search): <br> 
1) #ArrayToList( StructSort( salaries ) )#<br> 
2) #ArrayToList( StructSort( salaries, "text", "ASC" ) )#<br> 
3) #ArrayToList( StructSort( salaries, "textnocase", "ASC" ) )#<br> 
4) #ArrayToList( StructSort( salaries, "text", "DESC" ) )#<br> 
<p>list of employees based on the salary (numeric search): <br> 
5) #ArrayToList( StructSort( salaries, "numeric", "ASC" ) )#<br> 
6) #ArrayToList( StructSort( salaries, "numeric", "DESC" ) )#<br> 
<p>list of employees based on the salary (subfield search): <br> 
7) #ArrayToList( StructSort( employees, "numeric", "DESC", "salary" ) )#<br> 
8) #ArrayToList( StructSort( employees, "text", "ASC","salary" ) )#<br> 
<p>list of departments based on the salary (sub-sub-field search): <br> 
9) #ArrayToList( StructSort( departments, "text", "ASC", "boss.salary" ) )#<br> 
</cfoutput> 
 
<!--- add an invalid element and test that it throws an error ---> 
<p><p> 
<cfset employees[ "employee4" ] = StructNew()> 
<cftry> 
    <cfset temp = StructSort( employees, "text", "ASC", "salary" )> 
    <cfoutput>We have a problem - this was supposed to throw an exception!<br> 
    </cfoutput> 
<cfcatch type="any"> 
    <cfoutput> 
        ERROR: <b>This error was expected!</b><br> 
        #cfcatch.message# - #cfcatch.detail#<br> 
    </cfoutput> 
</cfcatch> 
</cftry>