sort

Sorts the elements of an array.

Applies to

Array

Syntax

sort(compareFunction)

Parameters

compareFunction

Specifies a function that defines the sort order. If omitted, the array is sorted lexicographically (in dictionary order) according to the string conversion of each element.

Description

If compareFunction is not supplied, elements are sorted by converting them to strings and comparing strings in lexicographic ("dictionary" or "telephone book," not numerical) order. For example, "80" comes before "9" in lexicographic order, but in a numeric sort 9 comes before 80.

If compareFunction is supplied, the array elements are sorted according to the return value of the compare function. If a and b are two elements being compared, then:

If compareFunction(a, b) is less than 0, sort b to a lower index than a.
If compareFunction(a, b) returns 0, leave a and b unchanged with respect to each other, but sorted with respect to all different elements.
If compareFunction(a, b) is greater than 0, sort b to a higher index than a.

So, the compare function has the following form:

function compare(a, b) {
      if (a is less than b by some ordering criterion)
            return -1
      if (a is greater than b by the ordering criterion)
            return 1
      // a must be equal to b
      return 0
}

To compare numbers instead of strings, the compare function can simply subtract b from a:

function compareNumbers(a, b) {
      return a - b
}

JavaScript uses a stable sort: the index partial order of a and b does not change if a and b are equal. If a's index was less than b's before sorting, it will be after sorting, no matter how a and b move due to sorting.

a = new Array();
a[0] = "Ant";
a[5] = "Zebra";
function writeArray(x) {
      for (i = 0; i < x.length; i++) {
            Console.Write(x[i]);
            if (i < x.length-1) Console.Write(", ");
      }
}
writeArray(a);
a.sort();
Console.Write();
writeArray(a);
ant, undefined, undefined, undefined, undefined, zebra 
ant, zebra, undefined, undefined, undefined, undefined

Examples

The following example creates four arrays and displays the original array, then the sorted arrays. The numeric arrays are sorted without, then with, a compare function.

stringArray = new Array("Blue","Humpback","Beluga")
numericStringArray = new Array("80","9","700")
numberArray = new Array(40,1,5,200)
mixedNumericArray = new Array("80","9","700",40,1,5,200)
function compareNumbers(a, b) {
      return a - b
}
Console.Write("stringArray:" + stringArray.join())
Console.Write("Sorted:" + stringArray.sort())
Console.Write("numberArray:" + numberArray.join())
Console.Write("Sorted without a compare function:" + numberArray.sort())
Console.Write("Sorted with compareNumbers:" + numberArray.sort(compareNumbers))
Console.Write("numericStringArray:" + numericStringArray.join())
Console.Write("Sorted without a compare function:" + numericStringArray.sort())
Console.Write("Sorted with compareNumbers:" + numericStringArray.sort(compareNumbers))
Console.Write("mixedNumericArray:" + mixedNumericArray.join())
Console.Write("Sorted without a compare function:" + mixedNumericArray.sort())
Console.Write("Sorted with compareNumbers: " + mixedNumericArray.sort(compareNumbers))

This example produces the following output. As the output shows, when a compare function is used, numbers sort correctly whether they are numbers or numeric strings.

stringArray: Blue,Humpback,Beluga
Sorted: Beluga,Blue,Humpback
numberArray: 40,1,5,200
Sorted without a compare function: 1,200,40,5
Sorted with compareNumbers: 1,5,40,200
numericStringArray: 80,9,700
Sorted without a compare function: 700,80,9
Sorted with compareNumbers: 9,80,700
mixedNumericArray: 80,9,700,40,1,5,200
Sorted without a compare function: 1,200,40,5,700,80,9
Sorted with compareNumbers: 1,5,9,40,80,200,700