StructSort

Description

Finds and sorts structures that contain top-level key names (strings).

Return value

An array of structures of top-level key names (strings), sorted by the value of the specified subelement. The key values may be simple values or complex elements.

Syntax

StructSort(base, sortType, sortOrder, pathToSubElement)

Parameters

Parameter Description

base
A ColdFusion struct with one field (an associative array).

sorttype

numeric

text: case sensitive (all lower-case letters precede the first upper-case 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. Default: nothing (top-level entries sorted by their own values).

Parameter	Description
base	A ColdFusion struct with one field (an associative array).
sorttype	numeric text: case sensitive (all lower-case letters precede the first upper-case 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. Default: nothing (top-level entries sorted by their own values).

Usage

The pathToSubElement string does not support array notation; only substructures of structures are supported.

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>