Compartilhar via

Funções de valor da cadeia de caracteres para numérico

  • Artigo

Comentários

Cada função na família strto* converte uma cadeia de caracteres terminada em nulo em um valor numérico. As funções disponíveis estão listadas na tabela a seguir.

Função Descrição
strtod Converter cadeia de caracteres no valor de ponto flutuante de precisão dupla
strtol Converter cadeia de caracteres em um inteiro long
strtoul Converter cadeia de caracteres em um inteiro unsigned long
_strtoi64 Converter a cadeia de caracteres para inteiro __int64 de 64 bits
_strtoui64 Converter cadeia de caracteres em inteiro __int64 de 64 bits

wcstod, wcstol, wcstoul e _wcstoi64 são versões de caractere largo de strtod, strtol, strtoul e _strtoi64, respectivamente. O argumento de cadeia de caracteres para cada uma dessas funções de caractere largo é uma cadeia de caracteres largos. Cada função comporta-se identicamente para sua equivalente de único caractere de byte, caso contrário.

A função strtod recebe dois argumentos: o primeiro é a cadeia de caracteres de entrada e o segundo um ponteiro para o caractere que encerra o processo de conversão. strtol, strtoul, _strtoi64 e _strtoui64 usam um terceiro argumento como base numérica para usar no processo de conversão.

A cadeia de caracteres de entrada é uma sequência de caracteres que pode ser interpretada como um valor numérico do tipo especificado. Cada função para de ler a cadeia de caracteres no primeiro caractere que não é possível reconhecer como parte de um número. Este pode ser o caractere nulo de terminação. Para strtol, strtoul, _strtoi64, e _strtoui64, esse caractere de terminação também pode ser o primeiro caractere numérico maior ou igual ao número fornecido pelo usuário base.

Se o ponteiro fornecido pelo usuário para um caractere de fim de conversão não estiver definido como NULL ou nullptr no momento da chamada, um ponteiro para o caractere que interrompeu a verificação será armazenado nele. Se nenhuma conversão puder ser executada (nenhum dígito válido foi encontrado ou uma base inválida foi especificada), o valor do ponteiro de cadeia de caracteres estará armazenado nesse endereço.

strtod espera uma cadeia de caracteres com o seguinte formato:

[whitespace] [sign] [digits] [.digits] [{d | D | e | E}[sign]digits]

Um whitespace pode consistir em caracteres de espaço ou tabulação, que são ignorados; sign é um sinal de mais (+) ou um sinal de menos (-); e digits é composto por um ou mais dígitos decimais. Se nenhum dígito aparecer antes do caractere fracionário, pelo menos um deverá aparecer após o caractere fracionário. Os dígitos decimais podem ser seguidos por um expoente, que consiste em uma letra de apresentação (d, D, e ou E) e um inteiro opcionalmente com sinal. Se nenhuma parte do expoente ou caractere de base aparecer, assume-se que um caractere de base segue o último dígito da cadeia de caracteres. O primeiro caractere que não é adequado a esse formato interrompe a verificação.

As funções strtol, strtoul, _strtoi64 e _strtoui64 esperam uma cadeia de caracteres com o seguinte formato:

[whitespace] [{+ | -}] [0 [{ x | X }]] [digits]

Se o argumento base estiver entre 2 e 36, ele será usado como base do número. Se for 0, os caracteres iniciais referenciados pelo ponteiro final de conversão são usados para determinar a base. Se o primeiro caractere é 0 e o segundo caractere não for 'x' ou 'X', a cadeia de caracteres é interpretada como um inteiro octal; Caso contrário, ela será interpretada como um número decimal. Se o primeiro caractere for '0' e o segundo caractere for 'x' ou 'X', a cadeia de caracteres será interpretada como um inteiro hexadecimal. Se o primeiro caractere for de '1' até '9', a cadeia de caracteres será interpretada como um inteiro hexadecimal. As letras 'a' a 'z' (ou 'A' a 'Z') recebem os valores 10 a 35; somente são permitidas letras cujos valores atribuídos são menores que base. strtoul e _strtoui64 permitem um prefixo com sinal de mais (+) ou de menos (-). Um sinal de subtração à esquerda indica que o valor retornado é negado.

O valor de saída é afetado pela configuração da categoria LC_NUMERIC da localidade. Para obter mais informações, consulte setlocale. As versões dessas funções sem o sufixo _l usam a localidade atual desse comportamento dependente da localidade. As versões com o sufixo _l são idênticas, exceto por usarem o parâmetro de localidade passado em seu lugar.

Quando o valor retornado por essas funções puder causar um estouro ou estouro negativo, ou quando a conversão não for possível, os valores especiais são retornados como mostrado:

Função Condição Valor retornado
strtod Estouro +/- HUGE_VAL
strtod Estouro negativo ou sem conversão 0
strtol + Estouro LONG_MAX
strtol - Estouro LONG_MIN
strtol Estouro negativo ou sem conversão 0
_strtoi64 + Estouro _I64_MAX
_strtoi64 - Estouro _I64_MIN
_strtoi64 Sem conversão 0
_strtoui64 Estouro _UI64_MAX
_strtoui64 Sem conversão 0

_I64_MAX, _I64_MIN e _UI64_MAX são definidos em <LIMITS.H>.

wcstod, wcstol, wcstoul, _wcstoi64, e _wcstoui64 são versões de caractere largo de strtod, strtol, strtoul, _strtoi64, e _strtoui64, respectivamente; o ponteiro para um argumento de final de conversão para cada uma dessas funções de caractere largo é uma cadeia de caracteres largos. Caso contrário, cada uma dessas funções de caractere largo se comporta de forma idêntica à sua equivalente de caractere de byte único.

Confira também

Conversão de dados
Localidade
Interpretação de sequências de caracteres multibyte
Suporte a matemática e ponto flutuante
atof, _atof_l, _wtof, _wtof_l