C++ <cstdlib> - strtoul() Function

The C++ <cstdlib> strtoul() function is used to interpret an integer value of the specified base in a byte string pointed to by str.

The function first discards any whitespace characters (as determined by isspace()) until the first non-whitespace character is found. Then, starting from this character, takes an optional initial plus or minus sign followed by as many characters as possible to form a valid integer number (of specified base) representation and converts them to an integer value.

The valid integer value consists of the following parts:

• (optional) plus or minus sign
• (optional) prefix indicating octal or hexadecimal base ("0" or "0x"/"0X" respectively)
• a sequence of digits.

The set of valid values for base is {0,2,3,...,36}. The set of valid digits for base-2 integers is {0,1}, for base-3 integers is {0,1,2}, and so on. For bases larger than 10, valid digits include alphabetic characters, starting from Aa for base-11 integer, to Zz for base-36 integer. The case of the characters is ignored.

For locales other than the "C" locale, additional numeric formats may be accepted.

If the value of base is 0, the numeric base is auto-detected: if the prefix is 0, the base is octal, if the prefix is 0x or 0X, the base is hexadecimal, otherwise the base is decimal.

If str_end is not a null pointer, the function also sets the value of str_end to point to the first character after the number. If str_end is a null pointer, it is ignored.

If the first sequence of non-whitespace characters in str is not a valid integral number, or if no such sequence exists (because either empty or contains only whitespaces), no conversion is performed and zero is returned.

Syntax

unsigned long int strtoul (const char* str, char** str_end, int base);

Parameters

Return Value

On success, the function returns the converted integral number as a value of type unsigned long int. If no conversion can be performed, zero (0UL) is returned. If the converted value falls out of the range, ULONG_MAX is returned, and errno is set to ERANGE.

Example 1:

The example below shows the usage of <cstdlib> strtoul() function.

#include <cstdio>
#include <cstdlib>

int main (){
  char str1[] = "123";
  char str2[] = "10.55";
  char str3[] = "100 some words";
  char str4[] = "some words 555";

  char *end;

  unsigned long int num1 = strtoul(str1, &end, 10);
  unsigned long int num2 = strtoul(str2, &end, 10);
  unsigned long int num3 = strtoul(str3, &end, 10);
  unsigned long int num4 = strtoul(str4, NULL, 10);

  //displaying the result
  printf("strtoul(\"%s\") = %lu\n", str1, num1);
  printf("strtoul(\"%s\") = %lu\n", str2, num2);
  printf("strtoul(\"%s\") = %lu\n", str3, num3);
  printf("strtoul(\"%s\") = %lu\n", str4, num4);

  return 0;
}

The output of the above code will be:

strtoul("123") = 123
strtoul("10.55") = 10
strtoul("100 some words") = 100
strtoul("some words 555") = 0

Example 2:

Consider the example below where the string contains multiple integral values. The second parameter if not a null pointer then this function sets this parameter to value which points to the first character after the interpreted number. This feature can be used to interpret multiple integral values from the string.

#include <cstdio>
#include <cstdlib>

int main (){
  char str[] = "123 10 555";
  char *pEnd;

  unsigned long int val1 = strtoul(str, &pEnd, 10);
  unsigned long int val2 = strtoul(pEnd, &pEnd, 10);
  unsigned long int val3 = strtoul(pEnd, &pEnd, 10);

  //displaying the result
  printf("val1 = %lu\n", val1);
  printf("val2 = %lu\n", val2);
  printf("val3 = %lu\n", val3);

  return 0;
}

The output of the above code will be:

val1 = 123
val2 = 10
val3 = 555

Example 3:

Consider one more example where the third parameter of this function is used to interpret integral values in different bases.

#include <cstdio>
#include <cstdlib>

int main (){
  char str[] = "11011 55 123 ff 0xff";
  char *pEnd;

  unsigned long int val1 = strtoul(str, &pEnd, 2);
  unsigned long int val2 = strtoul(pEnd, &pEnd, 8);
  unsigned long int val3 = strtoul(pEnd, &pEnd, 10);
  unsigned long int val4 = strtoul(pEnd, &pEnd, 16);
  unsigned long int val5 = strtoul(pEnd, &pEnd, 0);

  //displaying the result
  printf("val1 = %lu\n", val1);
  printf("val2 = %lu\n", val2);
  printf("val3 = %lu\n", val3);
  printf("val4 = %lu\n", val4);
  printf("val5 = %lu\n", val5);

  return 0;
}

The output of the above code will be:

val1 = 27
val2 = 45
val3 = 123
val4 = 255
val5 = 255