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

CKTIS / JavaScript

String.prototype.at — ler uma unidade de código UTF-16 por índice

String.prototype.at(index) devolve uma cadeia com uma unidade de código UTF-16. Os índices negativos contam a partir do fim; uma posição fora do intervalo devolve undefined.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

string.at(index)

String.prototype.at(index) lê uma unidade de código UTF-16 sem alterar a cadeia. Os índices começam em 0; -1 indica a última unidade e -2 a penúltima. O resultado é uma cadeia com comprimento 1 ou undefined se a posição calculada estiver fora do intervalo. Para uma cadeia vazia, o método devolve undefined se a conversão do índice for bem-sucedida. O índice é convertido antes da verificação dos limites, pelo que "".at(0n) lança um TypeError.

O argumento é convertido num número inteiro, truncando a parte fracionária em direção a zero. Um argumento omitido, undefined e NaN correspondem ao índice 0; os infinitos devolvem undefined. Para um índice negativo, depois da conversão, a posição é string.length + index.

Ao contrário de at(), charAt() não conta para trás com índices negativos e devolve "" fora do intervalo. A expressão text[-1] lê uma propriedade chamada "-1", não a última unidade da cadeia.

Uma unidade de código UTF-16 não é necessariamente um caráter Unicode completo nem um caráter percecionado pelo utilizador: "😀".at(0) devolve apenas a primeira metade de um par substituto. O método faz parte do ECMAScript 2022, não de uma API do browser. A especificação não define as versões de browser que o suportam; verifica os ambientes de destino antes da implementação, por exemplo com typeof String.prototype.at === "function".

Exemplos

const text = "JavaScript";
console.log(text.at(0));
console.log(text.at(-1));
console.log(text.at(-2));
console.log(text.at(10));
console.log(text.charAt(10) === "");
console.log("😀".at(0).length);

Resultado

J
t
p
undefined
true
1

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes