Vector.sort() documentation update

A community member  pointed out recently that the ActionScript Language Reference description for Vector.sort() is incomplete. The reference will be updated soon. In the meantime, here’s the corrected description, which now includes sorting according to a “sort option” as well as sorting by using a compare function.

Vector sort() method:

Sorts the elements in the Vector object, and also returns a sorted Vector object. This method sorts according to the parameter sortBehavior, which is either a function that compares two values, or a set of sorting options.

The method takes one parameter. The parameter is one of the following:

  • a function that takes two arguments of the base type (T) of the Vector and returns a Number:

function compare(x:T, y:T):Number {}

The logic of the function is that, given two elements x and y, the function returns one of the following three values:

  • a negative number, if x should appear before y in the sorted sequence
  • 0, if x equals y
  • a positive number, if x should appear after y in the sorted sequence
  • a number which is a bitwise OR of the following values:
  • 2 or Array.DESCENDING
  • 4 or Array.UNIQUESORT
  • 16 or Array.NUMERIC

If the value is 0, the sort 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.
  • All elements, regardless of data type, are sorted as if they were strings, so 100 precedes 99, because “1″ is a lower string value than “9″.

sortBehavior:* — A Function or a Number value that determines the behavior of the sort. A Function parameter specifies a comparison method. A Number value specifies the sorting options.

Vector  — A Vector object, with elements in the new order.