String.prototype.charCodeAt()

O método charCodeAt() retorna um integer entre 0 e 65535 representando a unidade de código UTF-16 em seu dado índice (a unidade de código UTF-16 corresponde ao ponto de código Unicode para pontos de códigos representáveis em uma única unidade de código UTF-16 , mas também pode ser a primeira unidade de código de um par substituto não representável em uma única unidade de código UTF-16. Exemplo: pontos de código Unicode  > 0x10000). Se você quer o valor do ponto de código inteiro, use codePointAt().

Sintaxe

str.charCodeAt(índice)

Parâmetros

índice
Um integer maior ou igual a 0 e menor que o comprimento da string; se não for um número, o padrão será 0.

Valor de Retorno

Um número representando o valor de unidade de código UTF-16 do caracter no dado índice; NaN se o índice estiver fora do alcance.

Descrição

Pontos de código Unicode variam de 0 a 1114111 (0x10FFFF). Os primeiros 128 pontos de código Unicode são uma correspondência direta a codificação de caracteres ASCII. Para informações sobre Unicode, veja o  JavaScript Guide.

Note que o charCodeAt() sempre irá retornar um valor menor do que 65536. Isso ocorre pois os pontos de código mais altos são representados por um par de pseudo-caracteres "substitutos" (de menor valor) que são usados para compreender o caracter real. Por isso, para examinar  ou reproduzir o caracter completo para caracteres individuais de valor 65536 e acima, para esses caracteres é necessário recuperar não apenas o charCodeAt(i), mas também o charCodeAt(i+1) (como se examinando/reproduzindo a string com duas letras), ou usar o codePointAt(i). Veja o exemplo 2 e 3 abaixo.

charCodeAt() retorna NaN se o dado índice for menor que 0 ou é maior ou igual ao comprimento da string.

Compatibilidade com versões anteriores: Em versões históricas (como JavaScript 1.2) o método charCodeAt() returna um número indicando o valor de conjunto de códigos ISO-Latin-1 do caracter no dado índice. O conjunto de códigos ISO-Latin-1 varia de 0 a 255. Os primeiros 128 são uma correspondência direta ao conjunto de caracteres ASCII.

Exemplos

Usando charCodeAt()

O exemplo a seguir retorna 65, o valor Unicode para A.

'ABC'.charCodeAt(0); // retorna 65

Corrigindo o charCodeAt() para manipular caracteres de Plano Multilingual não Básico se sua presença na string é desconhecida

Essa versão talvez seja usada em loops for e afins quando não sabemos se caracteres de Plano Multilingual não Básico existem antes da posição do índice especificado.

function fixedCharCodeAt(str, idx) {
  // ex. fixedCharCodeAt('\uD800\uDC00', 0); // 65536
  // ex. fixedCharCodeAt('\uD800\uDC00', 1); // false
  idx = idx || 0;
  var code = str.charCodeAt(idx);
  var hi, low;
  
  // Substituto elevado (poderia mudar o último hex para 0xDB7F para tratar
  // substitutos privados elevados como caracteres únicos)
  if (0xD800 <= code && code <= 0xDBFF) {
    hi = code;
    low = str.charCodeAt(idx + 1);
    if (isNaN(low)) {
      throw 'High surrogate not followed by low surrogate in fixedCharCodeAt()';
    }
    return ((hi - 0xD800) * 0x400) + (low - 0xDC00) + 0x10000;
  }
  if (0xDC00 <= code && code <= 0xDFFF) { // Low surrogate
    // Retornamos false para permitir os loops pularem essa iteração já que já deveria 
    //ter tratado os substitutos elevados acima, na iteração anterior
    return false;
    /*hi = str.charCodeAt(idx - 1);
    low = code;
    return ((hi - 0xD800) * 0x400) + (low - 0xDC00) + 0x10000;*/
  }
  return code;
}

Corrigindo o charCodeAt() para manipular caracteres de Plano Multilingual não Básico se sua presença na string é desconhecida

function knownCharCodeAt(str, idx) {
  str += '';
  var code,
      end = str.length;

  var surrogatePairs = /[\uD800-\uDBFF][\uDC00-\uDFFF]/g;
  while ((surrogatePairs.exec(str)) != null) {
    var li = surrogatePairs.lastIndex;
    if (li - 2 < idx) {
      idx++;
    }
    else {
      break;
    }
  }

  if (idx >= end || idx < 0) {
    return NaN;
  }

  code = str.charCodeAt(idx);

  var hi, low;
  if (0xD800 <= code && code <= 0xDBFF) {
    hi = code;
    low = str.charCodeAt(idx + 1);
    // Vá um adiante, já que um dos "characters" é parte de um par substituto
    return ((hi - 0xD800) * 0x400) + (low - 0xDC00) + 0x10000;
  }
  return code;
}

Especificações

Especificação Status Comentário
ECMAScript 1st Edition (ECMA-262) Standard Definição inicial. Implementado no JavaScript 1.2.
ECMAScript 5.1 (ECMA-262)
The definition of 'String.prototype.charCodeAt' in that specification.
Standard  
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'String.prototype.charCodeAt' in that specification.
Standard  
ECMAScript 2017 Draft (ECMA-262)
The definition of 'String.prototype.charCodeAt' in that specification.
Draft  

Compatibilidade com Browsers

Característica Chrome Firefox (Gecko) Internet Explorer Opera Safari
Suporte Básico (Yes) (Yes) (Yes) (Yes) (Yes)
Característica Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Suporte Básico (Yes) (Yes) (Yes) (Yes) (Yes) (Yes)

 

Veja também

Etiquetas do documento e colaboradores

 Colaboradores desta página: NicholasBraga
 Última atualização por: NicholasBraga,