IRAF help page for package xtools, program ranges

• 4 decode_ranges
• 4 get_next_number, get_last_number
• 4 is_in_range

These tools parse a string using a syntax to represent integer values, ranges, and steps. The parsed string is used to generate a list of integers for various purposes such as specifying lines or columns in an image or tape file numbers.

The syntax for the range string consists of positive integers, '-' (minus), 'x', ',' (comma), and whitespace. The commas and whitespace are ignored and may be freely used for clarity. The remainder of the string consists of sequences of five fields. The first field is the beginning of a range, the second is a '-', the third is the end of the range, the fourth is a 'x', and the fifth is a step size. Any of the five fields may be missing causing various default actions. The defaults are illustrated in the following table.

-3x1	A missing starting value defaults to 1.
2-x1	A missing ending value defaults to MAX_INT.
2x1	A missing ending value defaults to MAX_INT.
2-4	A missing step defaults to 1.
4	A missing ending value and step defaults to an ending
	value equal to the starting value and a step of 1.
x2	Missing starting and ending values defaults to
	the range 1 to MAX_INT with the specified step.
""	The null string is equivalent to "1 - MAX_INT x 1",
	i.e all positive integers.

The specification of several ranges yields the union of the ranges.

The following examples further illustrate the range syntax.

-	All positive integers.
1,5,9	A list of integers equivalent to 1-1x1,5-5x1,9-9x1.
x2	Every second positive integer starting with 1.
2x3	Every third positive integer starting with 2.
-10	All integers between 1 and 10.
5-	All integers greater than or equal to 5.
9-3x1	The integers 3,6,9.

PROCEDURES

4 decode_ranges

int procedure decode_ranges (range_string, ranges, max_ranges, nvalues)
char	range_string[ARB]	# Range string to be decoded
int	ranges[3, max_ranges]	# Range array
int	max_ranges		# Maximum number of ranges
int	nvalues			# The number of values in the ranges

The range string is decoded into an integer array of maximum dimension 3 * max_ranges. Each range consists of three consecutive integers corresponding to the starting and ending points of the range and the step size. The number of integers covered by the ranges is returned as nvalue. The end of the set of ranges is marked by a NULL. The returned status is either ERR or OK.

4 get_next_number, get_last_number

int procedure get_next_number (ranges, number)
int procedure get_previous_number (ranges, number)
int	ranges[ARB]		# Range array
int	number			# Both input and output parameter

Given a value for number the procedures find the next (previous) number in increasing (decreasing) value within the set of ranges. The next (previous) number is returned in the number argument. A returned status is either OK or EOF. EOF indicates that there are no greater values. The usual usage would be in a loop of the form:

	number = 0
	while (get_next_number (ranges, number) != EOF) {
	    
	}

bool procedure is_in_range (ranges, number)
int	ranges[ARB]		# Ranges array
int	number			# Number to check againts ranges

A boolean value is returned indicating whether number is covered by the ranges.