Flash CS3 Documentation

ActionScript 2.0 Language Reference > ActionScript classes > Array > sortOn (Array.sortOn method)

sortOn (Array.sortOn method)

Sorts the elements in an array according to one or more fields in the array. The array should have the following characteristics:

• The array is an indexed array, not an associative array.
• Each element of the array holds an object with one or more properties.
• All of the objects have at least one property in common, the values of which can be used to sort the array. Such a property is called a field.

If you pass multiple fieldName parameters, the first field represents the primary sort field, the second represents the next sort field, and so on. Flash sorts according to Unicode values. (ASCII is a subset of Unicode.) If either of the elements being compared does not contain the field that is specified in the fieldName parameter, the field is assumed to be undefined, and the elements are placed consecutively in the sorted array in no particular order.

By default, Array.sortOn() works in the following way:

• Sorting is case-sensitive (Z precedes a).
• Sorting is ascending (a precedes b).
• The array is modified to reflect the sort order; multiple elements that have identical sort fields are placed consecutively in the sorted array in no particular order.
• Numeric fields are sorted as if they were strings, so 100 precedes 99, because "1" is a lower string value than "9".

Flash Player 7 added the options parameter, which you can use to override the default sort behavior. To sort a simple array (for example, an array with only one field), or to specify a sort order that the options parameter doesn't support, use Array.sort().

To pass multiple flags, separate them with the bitwise OR (|) operator:

my_array.sortOn(someFieldName, Array.DESCENDING | Array.NUMERIC);

Flash Player 8 added the ability to specify a different sorting option for each field when you sort by more than one field. In Flash Player 8, the options parameter accepts an array of sort options such that each sort option corresponds to a sort field in the fieldName parameter. The following example sorts the primary sort field, a, using a descending sort; the secondary sort field, b, using a numeric sort; and the tertiary sort field, c, using a case-insensitive sort:

Array.sortOn (["a", "b", "c"], [Array.DESCENDING, Array.NUMERIC, Array.CASEINSENSITIVE]);

Note: The fieldName and options arrays must have the same number of elements; otherwise, the options array is ignored. Also, the Array.UNIQUESORT and Array.RETURNINDEXEDARRAY options can be used only as the first element in the array; otherwise, they are ignored.

Availability: ActionScript 1.0; Flash Player 6 - The options parameter was added in Flash Player 7. The ability to use different options parameters on multiple sort fields was added in Flash Player 8.

Parameters

fieldName:Object - A string that identifies a field to be used as the sort value, or an array in which the first element represents the primary sort field, the second represents the secondary sort field, and so on.

options:Object [optional] - One or more numbers or names of defined constants, separated by the bitwise OR (|) operator, that change the sorting behavior. The following values are acceptable for the options parameter:

• Array.CASEINSENSITIVE or 1
• Array.DESCENDING or 2
• Array.UNIQUESORT or 4
• Array.RETURNINDEXEDARRAY or 8
• Array.NUMERIC or 16

Code hinting is enabled if you use the string form of the flag (for example, DESCENDING) rather than the numeric form (2).

Returns

Array - The return value depends on whether you pass any parameters:

• If you specify a value of 4 or Array.UNIQUESORT for the options parameter, and two or more elements being sorted have identical sort fields, a value of 0 is returned and the array is not modified.
• If you specify a value of 8 or Array.RETURNINDEXEDARRAY for the options parameter, an array is returned that reflects the results of the sort and the array is not modified.
• Otherwise, nothing is returned and the array is modified to reflect the sort order.

Example

The following example creates a new array and sorts it according to the name and city fields. The first sort uses name as the first sort value and city as the second. The second sort uses city as the first sort value and name as the second.

var rec_array:Array = new Array();
rec_array.push({name: "john", city: "omaha", zip: 68144});
rec_array.push({name: "john", city: "kansas city", zip: 72345});
rec_array.push({name: "bob", city: "omaha", zip: 94010});
for(i=0; i<rec_array.length; i++){
    trace(rec_array[i].name + ", " + rec_array[i].city);
}
// Results:
// john, omaha
// john, kansas city
// bob, omaha

rec_array.sortOn(["name", "city"]);
for(i=0; i<rec_array.length; i++){
    trace(rec_array[i].name + ", " + rec_array[i].city);
}
// Results:
// bob, omaha
// john, kansas city
// john, omaha

rec_array.sortOn(["city", "name" ]);
for(i=0; i<rec_array.length; i++){
    trace(rec_array[i].name + ", " + rec_array[i].city);
}
// Results:
// john, kansas city
// bob, omaha
// john, omaha

The following array of objects is used by the remaining examples, which show how to use the options parameter:

var my_array:Array = new Array();
my_array.push({password: "Bob", age:29});
my_array.push({password: "abcd", age:3});
my_array.push({password: "barb", age:35});
my_array.push({password: "catchy", age:4});

Performing a default sort on the password field produces the following results:

my_array.sortOn("password");
// Bob
// abcd
// barb
// catchy

Performing a case-insensitive sort on the password field produces the following results:

my_array.sortOn("password", Array.CASEINSENSITIVE);
// abcd
// barb
// Bob
// catchy

Performing a case-insensitive, descending sort on the password field produces the following results:

my_array.sortOn("password", Array.CASEINSENSITIVE | Array.DESCENDING);
// catchy
// Bob
// barb
// abcd

Performing a default sort on the age field produces the following results:

my_array.sortOn("age");
// 29
// 3
// 35
// 4

Performing a numeric sort on the age field produces the following results:

my_array.sortOn("age", Array.NUMERIC);
// my_array[0].age = 3
// my_array[1].age = 4
// my_array[2].age = 29
// my_array[3].age = 35

Performing a descending numeric sort on the age field produces the following results:

my_array.sortOn("age", Array.DESCENDING | Array.NUMERIC);
// my_array[0].age = 35
// my_array[1].age = 29
// my_array[2].age = 4
// my_array[3].age = 3

When you use the Array.RETURNEDINDEXARRAY sorting option, you must assign the return value to a different array. The original array is not modified.

var indexArray:Array = my_array.sortOn("age", Array.RETURNINDEXEDARRAY);

See also

| bitwise OR operator, sort (Array.sort method)

Flash CS3