Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Array.prototype.toSorted: cópia ordenada de forma estável

toSorted ordena de forma estável um novo array denso, sem alterar o recetor nem a sua ordem original.

Versão: ECMAScript 2023; stable ordering required; example target: Node.js 24.22.2

Sintaxe

array.toSorted(compareFn?)

array.toSorted(compareFn?) devolve um novo Array normal com valores ordenados de forma estável, sem alterar array. compareFn(a, b) segue sort(): um resultado negativo coloca a antes, um positivo depois, e zero ou NaN preserva a ordem de valores iguais. O callback nunca recebe undefined.

Sem callback, os valores diferentes de undefined são comparados como strings por unidades UTF-16. undefined fica no fim. Os espaços vazios do recetor são lidos como undefined, tornando o resultado denso. O método ignora Symbol.species e faz uma cópia superficial das referências.

É genérico para valores array-like. Um callback não invocável ou recetor null ou undefined lança TypeError; erros de conversão, leitura, callback e proxy propagam-se, e um comprimento demasiado grande para um Array normal pode produzir RangeError. A API foi normalizada no ECMAScript 2023.

Exemplos

const tasks = [
  { label: "deploy", priority: 2 },
  { label: "test", priority: 1 },
  { label: "docs", priority: 2 },
];
const ordered = tasks.toSorted((a, b) => a.priority - b.priority);
console.log(ordered.map(item => item.label).join(","));
console.log(tasks.map(item => item.label).join(","));

console.log([80, 9, 100].toSorted().join(","));
const dense = [3, , 1].toSorted((a, b) => a - b);
console.log(dense.length, 0 in dense, 1 in dense, 2 in dense, dense[0], dense[1], String(dense[2]));

Resultado

test,deploy,docs
deploy,test,docs
100,80,9
3 true true true 1 3 undefined

Fontes