_strtoui64, _wcstoui64, _strtoui64_l, _wcstoui64_l

Converta uma cadeia de caracteres em valor unsigned __int64.

Sintaxe

unsigned __int64 _strtoui64(
   const char *strSource,
   char **endptr,
   int base
);
unsigned __int64 _wcstoui64(
   const wchar_t *strSource,
   wchar_t **endptr,
   int base
);
unsigned __int64 _strtoui64_l(
   const char *strSource,
   char **endptr,
   int base,
   _locale_t locale
);
unsigned __int64 _wcstoui64_l(
   const wchar_t *strSource,
   wchar_t **endptr,
   int base,
   _locale_t locale
);

Parâmetros

strSource
Cadeia de caracteres terminada em nulo a ser convertida.

endptr
Ponteiro para o caractere que interrompe a verificação.

base
O número base a ser usado.

locale
Localidade a usar.

Valor retornado

_strtoui64 retorna o valor representado na cadeia de caracteres strSource, exceto quando a representação causaria um estouro, caso em que ele retorna _UI64_MAX. _strtoui64 retorna 0 se nenhuma conversão pode ser realizada.

_UI64_MAX é definido em LIMITS.H.

Se strSource é NULL ou base é diferente de zero e menos que 2 ou maior que 36, errno é definido como EINVAL.

Para obter mais informações sobre códigos de retorno, confira errno, _doserrno, _sys_errlist e _sys_nerr.

Comentários

A função _strtoui64 converte strSource para um unsigned __int64. _wcstoui64 é uma versão de caractere largo de _strtoui64; seu argumento strSource é uma cadeia de caracteres largos. Caso contrário, essas funções se comportam de forma idêntica.

Ambas as funções param de ler a cadeia de caracteres strSource no primeiro caractere que não reconhecem como parte de um número. Pode ser o caractere nulo de terminação ou pode ser o primeiro caractere numérico superior ou igual a base.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar isso, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

A configuração da categoria LC_NUMERIC da localidade atual determina o reconhecimento do caractere fracionário em strSource; para obter mais informações, confira setlocale. As funções sem o sufixo _l usam a localidade atual; _strtoui64_l e _wcstoui64_l são idênticas as funções correspondentes sem o sufixo _l, exceto por usarem o parâmetro de localidade informado. Para obter mais informações, consulte Localidade.

Se endptr não for NULL, um ponteiro para o caractere que parou a verificação será armazenado no local apontado por endptr. Se nenhuma conversão pode ser executada (Nenhum dígito válido foi encontrado ou uma base inválida foi especificada), o valor de strSource é armazenado no local apontado pela endptr.

_strtoui64 espera que strSource aponte para uma cadeia de caracteres do seguinte formato:

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

Um whitespace pode consistir de caracteres de espaço ou tabulação, que são ignorados. digits é um ou mais dígitos decimais. letters são uma ou mais das letras 'a' a 'z' (ou 'A' a 'Z'). O primeiro caractere que não é adequado a esse formato interrompe a verificação. Se base estiver entre 2 e 36, ele será usado como a base do número. Se base é 0, os caracteres inicias da cadeia de caracteres apontada por strSource são usados para determinar a base. Se o primeiro caractere for '0' e o segundo caractere não for 'x' nem 'X', a cadeia de caracteres será interpretada como um inteiro octal. 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. O primeiro caractere fora do intervalo da base interrompe o exame. Por exemplo, se base é 0 e o primeiro caractere verificado é '0', é considerado um inteiro octal e um caractere '8' ou '9' interromperá a verificação.

Requisitos

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// crt_strtoui64.c
#include <stdio.h>

unsigned __int64 atoui64(const char *szUnsignedInt) {
   return _strtoui64(szUnsignedInt, NULL, 10);
}

int main() {
   unsigned __int64 u = atoui64("18446744073709551615");
   printf( "u = %I64u\n", u );
}

u = 18446744073709551615

Confira também

Conversão de dados
Localidade
localeconv
setlocale, _wsetlocale
String para funções de valor numérico
strtod, _strtod_l, wcstod, _wcstod_l
strtoul, _strtoul_l, wcstoul, _wcstoul_l
atof, _atof_l, _wtof, _wtof_l