TypedArray.prototype.toSorted() — Methode · JavaScript-Referenz

Signatur

TypedArray.prototype.toSorted(compareFn)

Beschreibung

toSorted() ist die nicht verändernde Variante von TypedArray.prototype.sort(). Die Methode legt ein neues TypedArray desselben Typs an (z. B. Float64Array) und gibt es sortiert zurück. Das ursprüngliche Array bleibt dabei unverändert.

Ohne Vergleichsfunktion wird numerisch aufsteigend sortiert. Das ist ein wichtiger Unterschied zu Array.prototype.toSorted(), das Elemente standardmäßig als Zeichenketten vergleicht. -0 steht vor +0, und NaN-Werte kommen ans Ende.

Die Methode ist praktisch, wenn Rohdaten wie Messwerte, Audio-Samples oder Pixelwerte erhalten bleiben sollen, Sie aber zusätzlich eine sortierte Sicht brauchen, etwa für einen Median, Perzentile oder eine Rangliste. Nützlich ist sie auch in unveränderlichen Zustandsmodellen (z. B. React-State), in denen Daten nicht direkt verändert werden dürfen.

Parameter

Name	Typ	Default	Beschreibung
$compareFn	(a: number \| bigint, b: number \| bigint) => number	numerisch aufsteigend	Optionale Vergleichsfunktion. Ein negativer Rückgabewert stellt `a` vor `b`, ein positiver stellt `b` vor `a`, bei `0` bleibt die Reihenfolge erhalten. Bei `BigInt64Array` und `BigUint64Array` sind `a` und `b` BigInts.

Rückgabewert

Typ

TypedArray

Beschreibung

Ein neues TypedArray vom selben Typ wie das Original, mit den sortierten Elementen. Es hat einen eigenen, neuen ArrayBuffer.

Beispiele

Numerische Standardsortierung ohne Veränderung des Originals

const werte = new Int16Array([30, -5, 100, 2, 0]);
const sortiert = werte.toSorted();

console.log(sortiert);
console.log(werte); // Original bleibt unverändert

Int16Array(5) [-5, 0, 2, 30, 100] Int16Array(5) [30, -5, 100, 2, 0]

Absteigend sortieren mit Vergleichsfunktion

const punkte = new Float32Array([1.5, 9.25, 3, 7.75]);
const rangliste = punkte.toSorted((a, b) => b - a);

console.log(rangliste);

Float32Array(4) [9.25, 7.75, 3, 1.5]

Median von Messwerten berechnen

const messwerte = new Float64Array([21.4, 19.8, 23.1, 20.5, 22.0, 18.9]);

const median = (daten) => {
  const s = daten.toSorted();
  const mitte = Math.floor(s.length / 2);
  return s.length % 2 ? s[mitte] : (s[mitte - 1] + s[mitte]) / 2;
};

console.log(median(messwerte));
console.log(messwerte[0]); // Rohdaten unverändert

20.95 21.4

BigInt-Arrays und Vergleich mit Array.prototype.toSorted()

const ids = new BigUint64Array([300n, 12n, 4n]);
console.log(ids.toSorted());

// Normales Array sortiert standardmäßig als Zeichenkette:
console.log([300, 12, 4].toSorted());
console.log(new Uint16Array([300, 12, 4]).toSorted());

BigUint64Array(3) [4n, 12n, 300n] [12, 300, 4] Uint16Array(3) [4, 12, 300]

// Wichtig · Fallstricke

Kompatibilität: Teil von ES2023 („Change Array by Copy“). Verfügbar ab Chrome/Edge 110, Firefox 115, Safari 16 und Node.js 20. Für ältere Umgebungen gibt es einen Polyfill (z. B. core-js) oder den Ersatz ta.slice().sort().
Speicherbedarf: Es wird immer ein vollständiger neuer Puffer angelegt. Bei sehr großen Arrays (etwa Millionen Audio-Samples) verdoppelt sich damit kurzzeitig der Speicherverbrauch. Wenn das Original nicht erhalten bleiben muss, ist sort() sparsamer.
Vergleichsfunktion bei BigInt: (a, b) => b - a liefert dort einen BigInt statt einer Zahl. Das führt zu einem TypeError. Verwenden Sie stattdessen (a, b) => (a < b ? 1 : a > b ? -1 : 0).
Ist compareFn weder undefined noch eine Funktion, wird ein TypeError ausgelöst. Einen Fehler gibt es auch, wenn der zugrunde liegende ArrayBuffer abgekoppelt (detached) ist.
Anders als Array.prototype.toSorted() behandelt die Methode keine Lücken, denn TypedArrays haben keine. Außerdem wird numerisch statt lexikografisch sortiert.
Die Sortierung ist stabil: Gleich bewertete Elemente behalten ihre ursprüngliche Reihenfolge.

Siehe auch

TypedArray.prototype.sort() TypedArray.prototype.toReversed() TypedArray.prototype.with() Array.prototype.toSorted() TypedArray.prototype.slice() TypedArray