SYNOPSIS

int parse_ranges(char *str, int defmin, int defmax, int defmult, int (*parse_func)(), char **rangeptr, char **errptr);
int range_min(char *rbuf, int r);
int range_max(char *rbuf, int r);
int range_mult(char *rbuf, int r);

DESCRIPTION

parse_ranges() is a function to parse a comma-separated list of range tokens each having the following form:

                num
        or
                min:max[:mult]

any of the values may be blank (ie. min::mult, :max, etc.) and default values for missing arguments may be supplied by the caller.

The special first form is short hand for 'num:num'.

After parsing the string, the ranges are put into an array of integers, which is malloc'd by the routine. The min, max, and mult entries of each range can be extracted from the array using the range_min(), range_max(), and range_mult() functions.

If range_ptr is not NULL, and parse_ranges() successfully parses the range string (ie. does not return -1), *range_ptr will point to space malloc'd by parse_ranges(). The user may free this space by calling free().

parse_ranges() parameters are:

str

The string to parse - assumed to be a comma-separated list of tokens having the above format.

defmin

default value to plug in for min, if it is missing

defmax

default value to plug in for max, if it is missing

defmult

default value to plug in for mult, if missing

parse_func

A user-supplied function pointer, which parse_ranges() can call to parse the min, max, and mult strings. This allows for customized number formats. The function MUST have the following prototype:

        int parse_func(char *str, int *val)

The function should return -1 if str cannot be parsed into an integer, or >= 0 if it was successfully parsed. The resulting integer will be stored in *val. If parse_func is NULL, parse_ranges will parse the tokens in a manner consistent with the the sscanf %i format.

range_ptr

A user-supplied char **, which will be set to point at malloc'd space which holds the parsed range values. If range_ptr is NULL, parse_ranges() just parses the string. The data returned in range_ptr should not be processed directly - use the functions range_min(), range_max(), and range_mult() to access data for a given range.

errptr

user-supplied char ** which can be set to point to a static error string. If errptr is NULL, it is ignored.

range_min(), range_max(), and range_mult() parameters are:

rbuf

An array of ranges set up by parse_ranges().

r

The range number to extract information from. Must be an integer >= 0 and < the number of ranges returned by parse_ranges().

EXAMPLES

/*
 * simple example to take a list of ranges on the cmdline (in argv[1]), and
 * print a random number from within that range.
 */
#include <stdio.h>
main()
{
   extern intparse_ranges(), range_min(), range_max(), range_mult();
   extern longrandom_range(), random_range_seed();
   int      min, max, mult, nranges;
   char     *ep, *rp;
   random_range_seed(getpid());
   if ((nranges = parse_ranges(argv[1], 0, INT_MAX, 1, NULL, &rp, &ep)) < 0) {
      fprintf(stderr, "parse_ranges() failed:  %s, ep);
      exit(1);
   }
   range = random_range(0, nranges-1, 1);
   min = range_min(rp, range);
   max = range_max(rp, range);
   mult = range_mult(rp, range);
   fprintf("%d\n", random_range(min, max-1, mult));
   exit(0);
}

DIAGNOSTICS

parse_ranges() returns -1 on error or the number of ranges parsed. No space will be malloc'd if parse_ranges() fails. Error messages are passed back through the errptr parameter. There are no error conditions for range_min(), range_max(), or range_mult().