---
name: "parse_ranges"
section: "3"
platform: "linux"
package: "ltp-dev"
version: "20091231+dfsg-1"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/parse_ranges"
---

# parse\_ranges(3)

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

## 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 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:  %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/3.md), [random\_range\_seed(3)](/random_range_seed/3.md), [str\_to\_bytes(3)](/str_to_bytes/3.md).

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