View comments | RSS feed
CFML Reference Previous Up One Level Next


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.

Category

Structure functions

Syntax 

StructSort(base, sortType, sortOrder, pathToSubElement)

See also

Structure functions

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).

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>
Previous Up Next

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | Bug Reporting

Version 6

Comments are no longer accepted for ColdFusion MX. ColdFusion 8 is the current version.

Comments


hotwater said on Jan 9, 2003 at 1:48 PM :
It doesn't return an array of structures, it returns an array of strings.
tedmasterweb said on Apr 22, 2003 at 9:56 AM :
There is no way to "permanently" sort a structure, not even with a recursive cfscript function. As soon as you call the structure, it reverts to whatever internal sort state the cf engine decides the structure should have. I've read somewhere that this is a desired behavior, but I find it to be counter productive as I rarely output the contents of a structure in an unsorted list.

The work-around is to include something along the lines of the following in your code:

// get an array of the structure keys, sorted by whatever subkey you need. In this case the subkey is "name"
sorted = structsort ( structs, "textnocase", "ASC", "name" );

// walk through each element of sorted, calling the corresponding structure and doing something with its content
for ( x = 1; x lte ArrayLen ( sorted ); x = x + 1 )
{
result = result & structs[sorted[x]].name & "<br />";
}

// return the sorted list of names...
return result;
tedmasterweb said on Apr 22, 2003 at 11:18 AM :
This function is actually just misnamed. It should be StructKeyArraySorted(). This is because this function functions exactly the same as StructKeyArray() with the exception that the array elements can be sorted according to one of the members of the structure parameter.
m c d said on Jan 6, 2004 at 7:26 AM :
Please note that non-English characters are not sorted correctly. For example, "Ö" comes after "Z".

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6/CFML_Reference/functions-pt2102.htm