Array.sortOn( ) Method

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock
	Chapter 18.  ActionScript Language Reference

Array.sortOn( ) Method

Flash 6

---

sort an array of objects by the specified property

array.sortOn(key)

Arguments

key

A mandatory string specifying which property should be used to sort the objects in array.

Description

The sortOn( ) method is used to sort an array of objects according to the value of a specified property. The elements of array are expected to be objects. Each object is expected to have a property, specified by the string key, that will be used to sort the object. If key is not provided, sortOn( ) silently fails and no sort is performed.

The following code populates a three-element array with object literals that define fruit and meat properties:

var shoppingList = new Array(); shoppingList[0] = {fruit:"mango", meat:"beef"}; shoppingList[1] = {fruit:"orange", meat:"pork"}; shoppingList[2] = {fruit:"apple", meat:"chicken"};

To sort the shoppingList array by the fruit property, we use:

shoppingList.sortOn("fruit"); // shoppingList now contains: // ELEMENT 0: {fruit:"apple", meat:"chicken"} // ELEMENT 1: {fruit:"mango", meat:"beef"} // ELEMENT 2: {fruit:"orange", meat:"pork"};

More typically, the objects in the array will be instances of some class. For example:

// Create a simple Contact class with firstName and lastName properties function Contact (firstName, lastName) {   this.firstName = firstName;   this.lastName = lastName; }     // Override toString( ) for our class so it returns a more legible value Contact.prototype.toString = function () {   return this.firstName + " " + this.lastName; }     // Populate a contacts array with Contact instances var contacts = new Array(); contacts[0] = new Contact("Colin", "Moock"); contacts[1] = new Contact("Bruce", "Epstein"); contacts[2] = new Contact("Derek", "Clayton");     // Sort by lastName... contacts.sortOn("lastName"); trace(contacts);  // Displays: Derek Clayton,Bruce Epstein,Colin Moock // Sort by firstName... contacts.sortOn("firstName"); trace(contacts);  // Displays: Bruce Epstein,Colin Moock,Derek Clayton

Note that sortOn( ) uses the standard compare function to sort values (as if sort( ) had been called with no arguments). The sortOn( ) method does not offer any custom compare function capabilities. For sorting routines that require a custom compare function, use the sort( ) method instead. To ensure case-insensitive alphabetic sorting for Latin 1 letters, use String.toUpperCase( ) to convert property values to uppercase before calling sortOn( ).

When an element does not contain an object with a key property, that element is converted to a string and then ordered according to the default sort rules.

Bugs

In Flash Player 6, using sortOn( ) on an array that contains both strings and objects can crash the Player and the browser in which it is running. For example, the following code crashes Flash Player 6:

var shoppingList = new Array(); shoppingList[0] = {fruit:"mango", meat:"beef"}; shoppingList[1] = "hi"; shoppingList[2] = {fruit:"apple", meat:"chicken"};     shoppingList.sortOn("fruit");

Therefore, it is advisable to user a wrapper function that first checks whether all elements are objects before calling sortOn( ), such as:

Array.prototype.safeSortOn = function (key) {   for (i=0; i < this.length; i++) {     if (typeof this[i] != "object") {       trace ("Element " + i + " is not an object.");       return;     }   }   // If it passes the test, then call sortOn()   this.sortOn(key); }     // Usage: // This won't crash Flash Player 6. shoppingList.safeSortOn("fruit");

The sort order is indeterminate when multiple elements have the identical value for the key property. In this case, sortOn( ) may produce inconsistent results between multiple calls. For example:

function Contact (firstName, lastName) {   this.firstName = firstName;   this.lastName = lastName; }     Contact.prototype.toString = function () {   return this.firstName + " " + this.lastName; }     // Populate a contacts array with Contact instances that // share identical lastName property values. var contacts = new Array(); contacts[0] = new Contact("Makiko", "Pitaru"); contacts[1] = new Contact("Amit",   "Pitaru"); contacts[2] = new Contact("Richard", "Clayton"); contacts[3] = new Contact("Derek",   "Clayton");     // Sort by lastName... contacts.sortOn("lastName"); trace(contacts);  // Displays:                   // Richard Clayton,Derek Clayton,Makiko Pitaru,Amit Pitaru     // Sort AGAIN by lastName... contacts.sortOn("lastName"); trace(contacts);  // Displays DIFFERENT RESULTS:                   // Richard Clayton,Derek Clayton,Amit Pitaru,Makiko Pitaru

See Also

Array.sort( )