JavaScript parseInt: Como Converter Strings em Números

A função JavaScript parseInt é um dos recursos mais conhecidos para converter texto em números inteiros dentro de aplicações web, APIs, formulários e rotinas de processamento de dados. Embora pareça simples, seu comportamento envolve detalhes importantes, como a leitura parcial de caracteres, a escolha da base numérica e o retorno de NaN em entradas inválidas. Compreender esses aspectos ajuda a evitar falhas silenciosas, cálculos incorretos e validações frágeis. Neste guia, você verá como usar parseInt(), quando ela é apropriada, quais são seus limites e quais alternativas fazem mais sentido em cenários específicos.

Como funciona o JavaScript parseInt na prática

parseInt() é uma função global do JavaScript usada para interpretar uma string e retornar um número inteiro. Sua sintaxe básica é parseInt(string, radix), em que string representa o valor que será analisado e radix define a base numérica utilizada. O resultado é um valor do tipo number, mesmo quando a entrada original é um texto.

Um exemplo simples é parseInt("42", 10), que retorna 42. O segundo argumento, 10, informa que a conversão deve ocorrer na base decimal. Embora certos casos funcionem sem esse argumento, informar explicitamente o radix é uma boa prática essencial, pois torna a intenção do código clara e evita ambiguidades relacionadas a formatos numéricos.

A função ignora espaços em branco no início da string. Assim, parseInt(" 25", 10) também retorna 25. Ela aceita ainda um sinal positivo ou negativo: parseInt("-18", 10) produz -18. Porém, a leitura é interrompida assim que surge um caractere incompatível com a base escolhida. Por exemplo, parseInt("123px", 10) retorna 123, pois a conversão termina antes da letra p.

Esse comportamento é útil ao extrair valores inteiros de medidas CSS, identificadores formatados ou campos que contenham unidades anexadas. Entretanto, também pode mascarar dados malformados. Se um sistema espera exclusivamente um número e recebe "12abc", o resultado 12 talvez não seja aceitável do ponto de vista de validação. Portanto, converter uma string em número não é apenas uma questão técnica: é preciso avaliar a regra de negócio e a qualidade esperada da entrada.

Quando não há nenhum caractere inicial que possa ser convertido, o retorno é NaN, sigla para “Not a Number”. Por exemplo, parseInt("abc", 10) resulta em NaN. Para verificar esse caso, utilize Number.isNaN(valor). Evite a comparação direta valor === NaN, pois NaN não é igual a si próprio segundo as regras da linguagem.

A documentação da MDN Web Docs sobre parseInt detalha esse algoritmo e seus casos especiais. Para uma leitura normativa, a especificação ECMAScript também descreve formalmente o comportamento da função.

Radix: a base numérica que não deve ser esquecida

O parâmetro radix determina como os caracteres serão interpretados. Em sistemas digitais, as bases mais comuns são decimal, binária, octal e hexadecimal. O valor permitido normalmente fica entre 2 e 36, porque a função utiliza algarismos de 0 a 9 e letras de A a Z para representar dígitos adicionais. Assim, em base 16, a letra F equivale a 15.

Observe alguns exemplos: parseInt("1010", 2) retorna 10, pois o texto é lido como binário; parseInt("17", 8) retorna 15; e parseInt("FF", 16) retorna 255. Esse recurso é muito usado em conversões de cores, permissões de arquivos, protocolos, manipulação de flags e integração com dados técnicos.

Usar parseInt("08") sem radix costuma produzir 8 nos ambientes modernos, mas não há motivo para depender de inferência. A forma mais legível e segura é parseInt("08", 10). Ao declarar a base, outros desenvolvedores entendem imediatamente o formato desejado, e revisões de código se tornam mais objetivas.

Também é necessário saber que o prefixo hexadecimal 0x pode ser reconhecido em determinadas situações. Ainda assim, quando os dados são externos, declarar explicitamente 16 é preferível: parseInt("0xFF", 16). Para dados binários com prefixo 0b, parseInt() não deve ser tratado como uma solução universal de reconhecimento de literais; valide e normalize o valor de acordo com o formato recebido.

Boas práticas para converter string em número

• Sempre informe o radix quando utilizar parseInt(), especialmente para valores decimais: parseInt(valor, 10).
• Valide a entrada antes da conversão quando o campo precisar conter apenas inteiros. Expressões regulares, regras de formulário e esquemas de validação podem ser adequados.
• Use Number.isNaN() para identificar falhas de conversão de modo confiável, sem confundir valores válidos como zero.
• Não use parseInt para casas decimais. Para "10.75", ela retorna 10; prefira parseFloat() ou Number(), conforme o caso.
• Evite parseInt como atalho de arredondamento. Para manipular números já numéricos, use Math.trunc(), Math.floor() ou outra operação coerente com a regra desejada.
• Trate valores ausentes antes de converter. Uma string vazia, null ou undefined pode exigir uma decisão explícita de interface ou negócio.
• Considere limites de precisão para identificadores muito longos. Inteiros além da faixa segura de Number podem exigir BigInt ou tratamento como texto.

parseInt, Number e parseFloat: comparação essencial

A escolha da função de conversão modifica o resultado e deve corresponder ao formato de entrada. parseInt() é tolerante com caracteres posteriores, enquanto Number() exige que toda a string represente um número válido, exceto espaços permitidos. Já parseFloat() foi projetada para interpretar números de ponto flutuante, mas também pode interromper a leitura ao encontrar conteúdo inválido.

Em formulários, um padrão frequente é receber dados por input.value, que sempre é string. Se o campo aceitar apenas idade inteira, uma estratégia robusta é verificar o formato, converter com parseInt(valor, 10) e confirmar se o resultado está dentro da faixa permitida. Para preço, distância ou porcentagem, é melhor avaliar se decimais são aceitos e, se necessário, normalizar vírgulas e pontos de acordo com a localidade antes da conversão.

Dúvidas comuns sobre parseInt no JavaScript

O que é parseInt em JavaScript?

parseInt() é uma função global que interpreta uma string e tenta convertê-la em um número inteiro. Ela aceita um segundo argumento opcional, mas recomendado, para definir a base numérica usada na leitura.

Por que parseInt retorna NaN?

O retorno NaN ocorre quando a função não encontra um dígito válido no início do valor analisado para o radix informado. Exemplos incluem parseInt("texto", 10) e parseInt("", 10).

Qual é a diferença entre parseInt e Number?

parseInt() extrai um inteiro da parte inicial válida de uma string, enquanto Number() tenta converter todo o conteúdo. Portanto, parseInt("15px", 10) retorna 15, mas Number("15px") retorna NaN.

É obrigatório usar radix no parseInt?

Não é estritamente obrigatório em todos os casos modernos, porém é altamente recomendado. Informar 10 para números decimais melhora a clareza, reduz dependências de interpretação implícita e segue convenções consolidadas de desenvolvimento.

parseInt arredonda números decimais?

Não exatamente. A função converte a string até o primeiro caractere incompatível com um inteiro. Por isso, parseInt("9.8", 10) retorna 9. Para arredondar um número existente, escolha métodos matemáticos como Math.round(), Math.floor() ou Math.trunc().

Conclusão: quando usar JavaScript parseInt

Dominar o JavaScript parseInt é importante para lidar com dados textuais que precisam se tornar inteiros de forma previsível. A função é particularmente eficiente quando você deseja extrair um número inteiro no início de uma string ou interpretar valores em bases como binária e hexadecimal. Contudo, ela não substitui validação completa, não é indicada para decimais e exige atenção ao risco de aceitar conteúdo adicional inesperado.

A prática recomendada é simples: use parseInt(valor, 10) para inteiros decimais, teste o resultado com Number.isNaN(), valide o formato quando a integridade do dado for relevante e selecione Number() ou parseFloat() em cenários mais adequados. Com essas decisões, a conversão de string em número se torna mais segura, legível e consistente em projetos JavaScript.

Referências e documentação consultada

• MDN Web Docs — parseInt().
• MDN Web Docs — Number.isNaN().
• ECMA-262 — Especificação do algoritmo parseInt.
• MDN Web Docs — Objeto Number.

Isenção de responsabilidade

Este conteúdo possui finalidade educacional e informativa. Os exemplos de JavaScript devem ser adaptados ao contexto técnico, às regras de validação, aos requisitos de segurança e às versões das ferramentas utilizadas em cada projeto. Antes de aplicar conversões em sistemas de produção, especialmente em dados financeiros, identificadores, integrações externas ou informações fornecidas por usuários, realize testes, validações apropriadas e revisão de código.