doc/man3/parse_ranges.3

.\"
.\" $Id: parse_ranges.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of version 2 of the GNU General Public License as
.\" published by the Free Software Foundation.
.\"
.\" This program is distributed in the hope that it would be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\" Further, this software is distributed without any warranty that it is
.\" free of the rightful claim of any third person regarding infringement
.\" or the like.  Any license provided herein, whether implied or
.\" otherwise, applies only to this software file.  Patent licenses, if
.\" any, provided herein do not apply to combinations of this program with
.\" other software, or any other product whatsoever.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with this program; if not, write the Free Software Foundation, Inc.,
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
.\" Mountain View, CA  94043, or:
.\"
.\" http://www.sgi.com
.\"
.\" For further information regarding this notice, see:
.\"
.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
.\"
.TH PARSE_RANGES 3 07/25/2000 "Linux Test Project"
.SH NAME
parse_ranges \- function to parse a string formatted like 'min:max:mult,...'
.SH SYNOPSIS
.nf
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);
.fi
.SH DESCRIPTION
parse_ranges() is a function to parse a comma-separated list of range
tokens each having the following form:
.SP
.nf
		num
	or
		min:max[:mult]
.fi

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 \fIrange_ptr\fP 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:
.SP
.TP 1i
\fIstr\fP
The string to parse - assumed to be a comma-separated
list of tokens having the above format.
.TP 1i
\fIdefmin\fP
default value to plug in for min, if it is missing
.TP 1i
\fIdefmax\fP
default value to plug in for max, if it is missing
.TP 1i
\fIdefmult\fP
default value to plug in for mult, if missing
.TP 1i
\fIparse_func\fP
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:
.SP
.nf
	int parse_func(char *str, int *val)
.fi
.SP
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.
.TP 1i
\fIrange_ptr\fP
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.
.TP 1i
\fIerrptr\fP
user-supplied char ** which can be set to point to a
static error string.  If errptr is NULL, it is ignored.
.in -1i

.SP
range_min(), range_max(), and range_mult() parameters are:
.SP
.SP
.TP 1i
\fIrbuf\fP
An array of ranges set up by parse_ranges().
.TP 1i
\fIr\fP
The range number to extract information from.  Must be an integer >= 0 and
< the number of ranges returned by parse_ranges().
.in -1i

.SH EXAMPLES
\fC
.ta .25i +.25i +.25i +.25i
.nf
/*
 * 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 int	parse_ranges(), range_min(), range_max(), range_mult();
	extern long	random_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\n", 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);
}
\fP
.DT
.SH "SEE ALSO"
random_range(3),
random_range_seed(3),
bytes_by_prefix(3).
.SH 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().