StructSort

Description

Returns an array of structures containing top-level key names (strings) sorted according to the value of the specified subelement. The value of the keys may be simple values or complex elements.

Syntax

StructSort( base, pathToSubElement, sortOrder, sortType )

Parameters

Parameter

Description

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

pathToSubElement
The path to apply to each of the top-level keys in order to reach the element whose value you wish to sort by. If unspecified, pathToSubElement, defaults to nothing: meaning that the top-level entries will be sorted based on their own values.

sortType
The sort type. Options are "NUMERIC", "TEXT", or "TEXTNOCASE". The default is "TEXT."

sortOrder
The sort order. Options are "ASC" (ascending) or "DESC" (descending). The default is "ASC."

Parameter	Description
base	A ColdFusion struct with one field (an associative array).
pathToSubElement	The path to apply to each of the top-level keys in order to reach the element whose value you wish to sort by. If unspecified, pathToSubElement, defaults to nothing: meaning that the top-level entries will be sorted based on their own values.
sortType	The sort type. Options are "NUMERIC", "TEXT", or "TEXTNOCASE". The default is "TEXT."
sortOrder	The sort order. Options are "ASC" (ascending) or "DESC" (descending). The default is "ASC."

Usage

The pathToSubElement string does not support array notation so 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 ) )#<br>
3) #ArrayToList( StructSort( salaries, "text", "ASC" ) )#<br>
4) #ArrayToList( StructSort( salaries, "textnocase", "ASC" ) )#<br>
5) #ArrayToList( StructSort( salaries, "text", "DESC" ) )#<br>
<p>
list of employees based on the salary (numeric search): <br>
6) #ArrayToList( StructSort( salaries, "numeric", "ASC" ) )#<br>
7) #ArrayToList( StructSort( salaries, "numeric", "DESC" ) )#<br>
<p>
list of employees based on the salary (subfield search): <br>
8) #ArrayToList( StructSort( employees, "numeric", "DESC", "salary" ) )#<br>
9) #ArrayToList( StructSort( employees, "text", "ASC",  "salary" ) )#<br>
<p>
list of departments based on the salary (sub-sub-field search): <br>
10) #ArrayToList( StructSort( departments, "text", "ASC", "boss.salary" ) )#<br>
</cfoutput>

<!--- add an invalid item 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>