| CFML Reference
|
|
ColdFusion Functions
|
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 )
See also
StructDelete, StructFind, StructGet, StructInsert, StructIsEmpty, StructKeyArray, StructKeyExists, StructKeyList, StructCount, StructNew, StructUpdate, StructAppend, StructFindKey, StructClear
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."
|
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>
|
Copyright © 2001, Macromedia Inc. All rights reserved. |
|
|
