Table of Contents

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

Table of Contents