[Copyright status: this file is in the public domain.]

This file documents geometry spec processing utility types and
routines.

Geometry specs are used to specify window sizes and locations,
typically on the command line, as in "-geometry 80x24+300+100".  These
utility routines may - but need not - be used by applications to handle
such specs.  In regex syntax, an X geometry spec matches

	^([0-9]+x[0-9]+)?([-+]-?[0-9]+-?[0-9]+)?$

liblx extends this somewhat, allowing each number to replaced by a dot:

	(([0-9]+|\.)x([0-9]+|\.))?([-+](-?[0-9]+|\.)[-+](-?[0-9]+|\.))?

A dot means "not specified", which allows (for example) modifying the
width without affecting the height.

Note that the position values always have a + or - before them and,
after that sign, the number may be positive or negative.  It is
important to track the sign separately, because (for example) +0+0 is
very different from -0-0; similarly, +100+0, -100+0, +-100+0, and
--100+0 are all very different.

There are two routines, one (lx_parse_geometry) which parses a geometry
string into an LX_GEOMETRY, and another (lx_apply_geometry) which uses
an LX_GEOMETRY to affect a (putative) window's size and location.  They
share the LX_GEOMETRY type.  The reason for the division between the
two is that some programs want to modify the LX_GEOMETRY between the
two; for example, some terminal emulators want to multiply the
specified width and height by a character-cell size before applying it.

An LX_GEOMETRY represents a parsed geometry spec.  It consists of four
ints (x, y, w, and h), which represent a position-and-size, and a flags
word.  The + or - before position values does not affect the x and y
values' signs; that information is carried in the flags bits.

The flag bits are:

	LX_GEOM_PX
		A "positive" X position was specified, one with a +
		before it.
	LX_GEOM_PY
		A "positive" Y position was specified, one with a +
		before it.
	LX_GEOM_NX
		A "negative" X position was specified, one with a -
		before it.
	LX_GEOM_NY
		A "negative" Y position was specified, one with a -
		before it.
	LX_GEOM_W
		A width was specified.
	LX_GEOM_H
		A height was specified.

There are also convenience definitions LX_GEOM_X, which is
(LX_GEOM_PX|LX_GEOM_NX) bits, and LX_GEOM_Y, which is
(LX_GEOM_PY|LX_GEOM_MY).  These are intended for code which merely
wants to know (for example) "was an X position specified?", such as
when setting ICCCM window hints.

int lx_parse_geometry(const char *str, LX_GEOMETRY *gp)

	Parses a geometry spec string.

	str is the geometry spec.  It may be nil, which is semantically
	equivalent to a zero-length string (meaning no geometry
	specification).

	On success, the parsed geometry is written through gp, and
	lx_parse_geometry returns 0.  On failure, one of the
	LX_GEOM_ERR_* values (see below) is returned.  In the error
	case, it is specifically unspecified which, if any, fields of
	*gp have been written; for any that have, it is also
	unspecified what value(s) were written.

int lx_apply_geometry(const LX_GEOMETRY *gp, int pw, int ph, int bw, int *xp, int *yp, int *wp, int *hp)

	Applies a parsed geometry spec.

	gp is the parsed geometry, such as is produced by
	lx_parse_geometry (possibly modified, eg by a terminal emulator
	that wants to multiply the width and height values by character
	cell sizes).

	pw and ph are the width and height values that negative
	position values are to be interpreted relative to (typically, a
	parent window size).

	bw is the window's border width.  This is needed because
	geometry specs describe the size of the window _excluding_ its
	border, but the position is specified in terms of the window
	_including_ its border.

	xp, yp, wp, and hp point to the location and size to be used.
	Depending on the geometry spec, zero or more of these are
	overwritten with values computed from the geometry spec and, in
	some cases, the pw and ph values.  These are program-specified
	defaults on input; on output, they are the input values, as
	modified by the geometry spec.  (Out-of-range values on input
	may or may not be detected, but the library does promise that
	any value which is written will be written with an in-range value.)

	On success, returns 0.  On error, returns an LX_GEOM_ERR_*
	value.  On error, it is specifically undefined which, if any,
	of the xp/yp/wp/hp values are written through; if any are, what
	values are written is also undefined.

These routines return error values.  liblx promises that these values
are negative compile-time constants which can be stored in an int, but
does not promise more than that:

	LX_GEOM_ERR_SYNTAX
		(lx_parse_geometry only.)  The input string did not fit
		the syntax.

	LX_GEOM_ERR_RANGE
		Some value was out of range.  For lx_parse_geometry,
		it must be a value in the string; for
		lx_apply_geometry, it can be in *gp, pw, or ph, or can
		be a value computed from (in-range) input values.
		(lx_parse_geometry will not generate out-of-range
		values in non-error cases, but the LX_GEOMETRY may not
		come directly from lx_parse_geometry, and position
		specs with a - before them can lead to out-of-range
		computed values.)

		The valid ranges are the ones imposed by the X
		protocol: for X and Y positions, [-32768..32767]; for
		widths and heights, [1..65535].

		For lx_apply_geometry, if the input values are out of
		range but the values which would be computed based on
		them are in range, it is undefined whether an error
		occurs or the in-range computed value is stored without
		error, but it will be one of the two.

	LX_GEOM_ERR_INVALID
		Returned when the input LX_GEOMETRY is invalid for a
		reason other than a value being out of range (for
		example, if it has both LX_GEOM_PX and LX_GEOM_NX set
		in its flags field).

There is also LX_GEOM_ERR_NONE, a convenience definition, defined as
zero (indicating success from routines which return error values).