# JavaScript: Array.prototype.sort

By Xah Lee. Date: . Last updated: .
`arrayX.sort()`
Sort arrayX. Return the new array. Elements are converted to string for comparison.
arrayX can be a Array-Like Object.
`arrayX.sort(f)`
f is a ordering function. The function should take 2 arguments x y, and return:
• negative number if x ≺ y
• 0 if x = y
• positive number if x ≻ y.

WARNING: by spec, sort is not necessarily stable. That is, elements that are considered equal in order may be moved from the order they were in the original array.

```// array sort example

const aa = ["a1", "a70", "a8", "A2"];

console.log(
// default sort. element compared as string
aa.sort()
);
// [ 'A2', 'a1', 'a70', 'a8' ]

// the array is modified
console.log(aa); // [ 'A2', 'a1', 'a70', 'a8' ]```

## Custom Order Function

Sorting array using custom order function:

```// array sort using custom function

// custom ordering function
const ff = ((x, y) => {
// x and y are strings. we remove first char. consider rest as number
const nx = parseInt(x.slice(1));
const ny = parseInt(y.slice(1));

if ( nx < ny ) { return -1; }
if ( nx > ny ) { return 1; }
if ( nx == ny ) { return 0; }
});

// sort by comparing as numbers after first char

console.log(
["a1", "a70", "a8", "A2"].sort(ff)
);
// [ 'a1', 'A2', 'a8', 'a70' ]```

## Default Order Function

If order function is not `undefined`, the default will convert each element to a string if necessary by calling toString() method, then compare by their codepoint units. (note: not characters unicode codepoint)

Here's example showing it sorts by code unit and not codepoint.

```// example showing default comparison function for string, sorts by code unit and not codepoint.

console.log( ['﷽','😆'].sort());
// prints
// [ '😆', '﷽' ]

// 😆 (codepoint 128518, U+1f606)
// utf-16 encoding: #xFE #xFF #xD8 #x3D #xDE #x06

// ﷽ (codepoint 65021, U+fdfd)
// utf-16 encoding: #xFE #xFF #xFD #xFD```

## Order Function Must be Consistent

Note: the custom order function must be consistent, else the result of sort is implementation dependent.

Consistent means, for any x y z in the array:

1. `f(x,x) === 0`
2. if `f(x,y) === 0` and `f(y,z) === 0` then `f(x,z) === 0`
3. if `f(x,y) === -1` and `f(y,z) === -1` then `f(x,z) === -1`
4. if `f(x,y) === 1` and `f(y,z) === 1` then `f(x,z) === 1`

The above guarantee that the set is partitioned into classes by a equivalence relation, and the equivalence classes are total ordered.

also, the following are required due to how JavaScript the language works:

• `typeof f(x,y) === "number"` and is not `NaN`
• `f(x,y)` always returns the same value.
• Calling `f(x,y)` does not modify the array or any object of array's prototype chain.