Provided by: ltp-dev_20091231+dfsg-1ubuntu2_amd64 bug

NAME

       parse_ranges - function to parse a string formatted like 'min:max:mult,...'

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:  %s0, 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);
       }

SEE ALSO

       random_range(3), random_range_seed(3), str_to_bytes(3).

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().