NAME
    cmp - compare two values of certain simple or object types

SYNOPSIS
    cmp(x, y)

TYPES
    If x is an object of type xx, or x is not an object and y is an object
    of type xx, the function xx_rel has to have been defined; any
    further conditions on x and y, and the type of the returned
    value depends on the definition of xx_rel.

    For non-object x and y:

    x		any
    y		any

    return	if x and y are both real: -1, 0, or 1
		if x and y are both numbers but not both real:
			-1, 0, 1, -1+1i, 1i, 1+1i, -1-1i, -1i, or 1-1i
		if x and y are both strings: -1, 0, or 1
		all other cases: the null value

DESCRIPTION

    x and y both real: cmp(x, y) = sgn(x - y), i.e. -1, 0, or 1
	according as x < y, x == y, or x > y

    x and y both numbers, at least one being complex:
	cmp(x,y) = sgn(re(x) - re(y)) + sgn(im(x) - im(y)) * 1i

    x and y both strings: successive characters are compared until either
	different characters are encountered or at least one string is
	completed.  If the comparison ends because of different characters,
	cmp(x,y) = 1 or -1 according as the greater character is in x or y.
	If all characters compared in both strings are equal, then
	cmp(x,y) = -1, 0 or 1 according as the length of x is less than,
	equal to, or greater than the length of y.  (This comparison
	is performed via the strcmp() libc function.)

    objects: comparisons of objects are usually intended for some total or
	partial ordering and appropriate definitions of cmp(a,b) may
	make use of comparison of numerical or string components.
	definitions using comparison of numbers or strings are usually
	appropriate.  For example, after

		obj point {x,y};

	if points with real components are to be partially ordered by their
	Euclidean distance from the origin, an appropriate point_rel
	function may be that given by

		define point_rel(a,b) = sgn(a.x^2 + a.y^2 - b.x^2 - b.y^2);

	A total "lexicographic" ordering is that given by:

		define point_rel(a,b) {
			if (a.y != b.y)
				return sgn(a.y - b.y);
			return (a.x - b.x);
		}

	A comparison function that compares points analogously to
	cmp(a,b) for real and complex numbers is that given by

		define point_rel(P1, P2) {
			return obj point = {sgn(P1.x-P2.x), sgn(P1.y-P2.y)};
		}

	The range of this function is the set of nine points with zero
	or unit components.


    Some properties of cmp(a,b) for real or complex a and b are:

	cmp(a + c, b + c) = cmp(a, b)

	cmp(a, b) == 0 if and only if a == b

	cmp(b, a) = -cmp(a, b)

	if c is real or pure imaginary, cmp(c * a, c * b) = c * cmp(a,b)

    Then a function that defines "b is between a and c" in an often useful
    sense is

	define between(a,b,c) = (cmp(a,b) == cmp(b,c)).

    For example, in this sense, 3 + 4i is between 1 + 5i and 4 + 2i.

    Note that using cmp to compare non-object values of different types,
    for example, cmp(2, "2"), returns the null value.

EXAMPLE
    ; print cmp(3,4), cmp(4,3), cmp(4,4), cmp("a","b"), cmp("abcd","abc")
    -1 1 0 -1 1

    ; print cmp(3,4i), cmp(4,4i), cmp(5,4i), cmp(-5,4i), cmp(-4i,5), cmp(-4i,-5)
    1-1i 1-1i 1-1i -1-1i -1-1i 1-1i

    ; print cmp(3i,4i), cmp(4i,4i), cmp(5i,4i), cmp(3+4i,5), cmp(3+4i,-5)
    -1i 0 1i -1+1i 1+1i

    ; print cmp(3+4i,3+4i), cmp(3+4i,3-4i), cmp(3+4i,2+3i), cmp(3+4i,-4-5i)
    0 1i 1+1i 1+1i

LIMITS
    none

LINK LIBRARY
    FLAG qrel(NUMBER *q1, NUMBER *q2)
    FLAG zrel(ZVALUE z1, ZVALUE z2)

SEE ALSO
    sgn, test, operator

## Copyright (C) 1999  Landon Curt Noll
##
## Calc is open software; you can redistribute it and/or modify it under
## the terms of the version 2.1 of the GNU Lesser General Public License
## as published by the Free Software Foundation.
##
## Calc is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
## or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU Lesser General
## Public License for more details.
##
## A copy of version 2.1 of the GNU Lesser General Public License is
## distributed with calc under the filename COPYING-LGPL.  You should have
## received a copy with calc; if not, write to Free Software Foundation, Inc.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## Under source code control:	1994/10/20 02:52:30
## File existed as early as:	1994
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/