MACROMEDIA FLASH MX 2004 - ACTIONSCRIPT, Reference Manual

Page: 284 / 816

284 Chapter 12: ActionScript Dictionary
Returns
The return value depends on whether you pass any parameters:
•
If you specify a value of 4 or Array.UNIQUE for
option
, and two or more elements being
sorted have identical sort fields, Flash returns a value of 0 and does not modify the array.
•
If you specify a value of 8 or Array.RETURNINDEXEDARRAY for
option
, Flash returns an
array that reflects the results of the sort and does not modify the array.
•
Otherwise, Flash returns nothing and modifies the array to reflect the sort order.
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:
•
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”.
•
Nothing is returned.
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” on page 63 ) 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});