strtoul, _strtoul_l, wcstoul, _wcstoul_l

Converte uma cadeia de caracteres para um valor inteiro longo não assinado.

Sintaxe

unsigned long strtoul(
   const char *strSource,
   char **endptr,
   int base
);
unsigned long _strtoul_l(
   const char *strSource,
   char **endptr,
   int base,
   _locale_t locale
);
unsigned long wcstoul(
   const wchar_t *strSource,
   wchar_t **endptr,
   int base
);
unsigned long _wcstoul_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

strtoul retornará o valor convertido, se houver ou ULONG_MAX no estouro. strtoul retorna 0 se nenhuma conversão pode ser realizada. wcstoul retorna valores de maneira semelhante a strtoul. Para ambas as funções, errno será definido como ERANGE se ocorrer um estouro ou estouro negativo.

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

Comentários

Cada uma dessas funções converte a cadeia de caracteres de entrada strSource para um unsigned long.

strtoul interrompe a leitura da cadeia de caracteres strSource no primeiro caractere que ela não puder reconhecer como parte de um número. Esse caractere pode ser o terminado NULL, ou pode ser o primeiro caractere numérico maior ou igual a base. A configuração de categoria LC_NUMERIC da localidade determina o reconhecimento do caractere base em strSource; para saber mais, confira setlocale. strtoul e wcstoul usam a localidade atual; _strtoul_l e _wcstoul_l são idênticos, com exceção de que usam a localidade passada, em vez da localidade atual. 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.

wcstoul é uma versão de caractere largo de strtoul; seu argumento strSource é uma cadeia de caracteres largos. Caso contrário, essas funções se comportam de forma idêntica.

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

Mapeamentos de rotina de texto genérico

strtoul 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 refere-se a uma ou mais das letras a até z (ou A até 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 ou 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 até z (ou A até Z) são atribuídas com os valores de 10 até 35. Somente são permitidas letras cujos valores atribuídos sejam 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. strtoul permite um prefixo com sinal de mais (+) ou de menos (-); um sinal de subtração à esquerda indica que o valor retornado é negado.

Requisitos

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

Exemplo

Confira o exemplo de strtod.

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
strtol, wcstol, _strtol_l, _wcstol_l
atof, _atof_l, _wtof, _wtof_l