strtoul() -- General Function (libc)

Convert string to unsigned long integer
#include <stdlib.h>
unsigned long strtoul(string, tailptr, base)
char *string; char **tailptr; int base;

strtoul()  converts the  number  given in  string  to a  unsigned long  and
returns its value.   It is the unsigned long counterpart  of strtol() and a
more  general  version of  the  function atol().  strtoul()  also stores  a
pointer  to  the  first character  following  the  number through  tailptr,
provided tailptr does not equal NULL.

base gives the  base of the number being read,  either zero or a value from
two to  36.  If the  given base is  zero, strtoul() determines  an implicit
base for the number: hexadecimal if the number starts with  0x or 0X, octal
if the number starts with 0, or decimal otherwise.  Alternatively, the user
can specify an explicit base between two and 36.

strtoul()  parses  the  string  into  three  portions:  beginning,  subject
sequence, and tail.

The beginning  consists of zero  or more white-space  characters that begin
the string.

The subject  sequence is the portion of the  string that strtoul() converts
into  an unsigned  long.  It consists  of  an optional  sign character,  an
optional prefix  0x or  0X if the  base is 16,  and a nonempty  sequence of
digits  in the  specified  base.  For  example,  if the  base  is 16,  then
strtoul()  recognizes   numeric  characters  `0'  to   `9'  and  alphabetic
characters `A' through `F' and `a'  to `f' as digits.  It continues to scan
until it encounters a nondigit.

The  tail continues  from  the end  of  the subject  sequence  to the  null
character that ends the string.

strtoul() ignores  the beginning  portion of  the string.  It  converts the
subject sequence  to an unsigned  long. Finally, if tailptr  does not equal
NULL ,  it sets  the pointer pointed  to by tailptr  to the address  of the
first character of the string's tail.

strtoul() returns  an unsigned long  representing the value  of the subject
sequence.  If the input string does  not specify a valid number, it returns
zero and stores the initial value  of string through tailptr. If the number
it builds  is too large  to fit into  an unsigned long, it  sets the global
variable errno to the value of the macro ERANGE and returns ULONG_MAX.

Example

This  example uses  strtoul()  as a  hash  function for  table lookup.   It
demonstrates both hashing and  linked lists.  Hash-table lookup is the most
efficient when used to look up  entries in large tables; this is an example
only.

#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/*
 * For fastest results, use a prime about 15% bigger
 * than the table. If short of space, use a smaller prime.
 */
#define HASHP 11
struct symbol {
    struct symbol *next;
    char *name;
    char *descr;
} *hasht[HASHP], codes[] = {

    NULL,    "a286",     "frogs togs",
    NULL,    "xy7800",   "doughnut holes",
    NULL,    "z678abc",  "used bits",
    NULL,    "xj781",    "black-hole varnish",
    NULL,    "h778a",    "table hash",
    NULL,    "q167",     "log(-5.2)",
    NULL,    "18888",    "quid pro quo",
    NULL,    NULL,       NULL /* end marker */
};

void
buildTable()
{
    long h;
    register struct symbol *sym, **symp;

    for(symp = hasht; symp != (hasht + HASHP); symp++)
             *symp = NULL;

    for(sym = codes; sym->descr != NULL; sym++) {
             /*
              * hash by converting to base 36. There are
              * many ways to hash, but use all the data.
              */

             h = strtoul(sym->name, NULL, 36) % HASHP;
             sym->next = hasht[h];
             hasht[h] = sym;
    }
}

struct symbol *
lookup(s)
char *s;
{
    long h;
    register struct symbol *sym;

    h = strtoul(s, NULL, 36) % HASHP;
    for(sym = hasht[h]; sym != NULL; sym = sym->next)
             if(!strcmp(sym->name, s))
                         return(sym);
    return(NULL);
}

main()
{
    char buf[80];
    struct symbol *sym;

    buildTable();
    for(;;) {
             printf("Enter name ");
             fflush(stdout);

             if(gets(buf) == NULL)
                         exit(EXIT_SUCCESS);

             if((sym = lookup(buf)) == NULL)
                         printf("%s not found\n", buf);

             else
                         printf("%s is %s\n", buf, sym->descr);
    }
}

See Also

errno,
libc,
limits.h,
stdlib.h,
strtol()
ANSI Standard, §7.10.1.6

Notes

strtoul() ignores  initial white space in the input  string. White space is
defined as being all characters so recognized by the function isspace().

© 2012 by Stephen A. Ness