
			Selection of Items

Most empire "reporting" commands (census, commodity, map, etc) take
command line arguments and use the arguments to determine which
items are reported.  For regularity of interface, these reporting
commands should invoke the empire selection subroutines, named 
snxtitem/nxtitem for historical reasons.


int
snxtitem(ni, type, arg)
	struct	nstr_item *ni;
	int	type;
	char	*arg;

This routine takes a command line string and converts it into a
nstr_item request, storing it's results in the result parameter ni.
Arg can be of the form

	#%d or %d:%d,%d:%d	"area" selection request
	@%d,%d:%d		"ranged" selection request
	*			"all" selection request
	%d/%d/%d...		"enumerated" selection request

Obviously, the range and area selection requests are only valid for
items which have a physical location.  

When invoked, snxtitem also examines the global conditional argument
string set on the command line.  The condarg is instantiated by the
user using a "?" character, followed by a set of conditions.  These
conditions are "compiled" and inserted into the nstr_item structure.
There are a limited number of conditionals allowed.


int
nxtitem(ni, ptr)
	struct	nstr_item *ni;
	caddr_t	ptr;

This routine is used to retrieve the next item from the selection list.
It returns nonzero if such an item was found, and 0 if no more matching
items exist.


Other routines exist which allow the programmer a more active role
in specifying selection.  These routines are in fact called by the
main snxtitem routine to initialize the nstr_item structure.


snxtitem_area(ni, type, range)
	struct	nstr_item *ni;
	int	type;
	struct	range *range;

Given a range structure and the type, set up the ni with the map region
upon which to select the particular unit.


snxtitem_dist(ni, type, cx, cy, dist)
	struct	nstr_item *ni;
	int	type;
	int	cx, cy;
	int	dist;

Given a center x-y and a distance, arrange to select all items of
the given type within the radius specified.


snxtitem_all(ni, type)
	struct	nstr_item *ni;
	int	type;

Arrange to select all items of the given type.


snxtitem_list(ni, type, list)
	struct	nstr_item *ni;
	int	type;
	int	*list;
	int	size;

Arrange to select the items listed in the list.


int
nstr_comp(type, ptr, cond, ncp, arg)
	int	type;
	caddr_t	ptr;
	struct	nscstr *cond;
	int	*ncp;
	char	*arg;

"compile" the arg into an nscstr selection condition expression,
and add it to the current conditionals list.  Return fail if the
condition does not succeed.  This can be used to add a condition
to arguments already supplied by the user, for example, "own#0", etc.
The list of available conditionals will be different for each
item type.


int
nstr_exec(ptr, cond, nc)
	caddr_t	ptr;
	struct	nscstr *cond;
	int	nc;

Execute the conditional list given a pointer to a sample item.  If
any of the conditions fail, then zero is returned.  If all succeed,
then one is returned.
