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

• strtod, _strtod_l, wcstod, _wcstod_l

• strtol, wcstol, _strtol_l, _wcstol_l

• strtoul, _strtoul_l, wcstoul, _wcstoul_l

• _strtoi64, _wcstoi64, _strtoi64_l, _wcstoi64_l

• _strtoui64, _wcstoui64, _strtoui64_l, _wcstoui64_l

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.

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:

_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 matemático e de ponto flutuante
atof, _atof_l, _wtof, _wtof_l