PreviousNext

Array.sortOn()

Availability

Flash Player 6; additional capabilities added in Flash Player 7.

Usage

my_array.sortOn("fieldName" )
my_array.sortOn("fieldName", option | option |... )
my_array.sortOn( [ "fieldName" , "fieldName" , ... ] )
my_array.sortOn( [ "fieldName" , "fieldName" , ... ] , option | option |... )

Note: Where brackets ([]) are shown, you must include them in the code; that is, the brackets don't represent optional parameters.

Parameters

fieldName A string that identifies a field (in an element of the Array) to be used as the sort value.

option One or more numbers or strings, separated by the | (bitwise OR) operator, that change the behavior of the sort from the default. The following values are acceptable for option:

Each of these options in discussed in more detail in "Description," below.

Returns

The return value depends on whether you pass any parameters:

Description

Method; sorts the elements in an array according to one or more fields in the array. 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 ASCII (Unicode) values. If either of the elements being compared does not contain the field 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 as follows:

You can use the option flags to override these defaults. The following examples use different forms of the option flag for illustration purposes. If you want to sort a simple array (for example, an array with only one field), or if you want to specify a sort order that the options parameter doesn't support, use Array.sort().

To pass multiple flags in numeric format, separate them with the | (bitwise OR) operator or add the values of the flags together. The following code shows three different ways to specify a numeric descending sort:

my_Array.sortOn(someFieldName, 2 | 16);
my_Array.sortOn(someFieldName, 18);
my_Array.sortOn(someFieldName, Array.DESCENDING | Array.NUMERIC);

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

Consider the following array:

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", 1|2)
// 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", 16)
// 3
// 4
// 29
// 35

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

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

Performing a sort changes the elements in the array as follows:

// Before sorting
// my_array[0].age = 29;
// my_array[1].age = 3;
// my_array[2].age = 35;
// my_array[3].age = 4;

// After any sort that doesn't pass a value of 8 for option
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 sort that returns an index array doesn't change the elements in the array:

// Before sorting
// my_array[0].age = 29;
// my_array[1].age = 3;
// my_array[2].age = 35;
// my_array[3].age = 4;

// After a sort that returns an array containing index values
// Note that the original array is unchanged.
// You can then use the returned array to display sorted information
// without modifying the original array.
var indexArray:Array = my_array.sortOn("age", Array.RETURNINDEXEDARRAY);
// my_array[0].age = 29;
// my_array[1].age = 3;
// my_array[2].age = 35;
// my_array[3].age = 4;

Example

This example creates a new array and sorts it according to the fields name and city: 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 = 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 in 
// 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 in 
// 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 in 
// john, kansas city
// bob, omaha
// john, omaha

See also

| (bitwise OR), Array.sort()

PreviousNext