help/cmp

   1 NAME
   2     cmp - compare two values of certain simple or object types
   3
   4 SYNOPSIS
   5     cmp(x, y)
   6
   7 TYPES
   8     If x is an object of type xx, or x is not an object and y is an object
   9     of type xx, the function xx_rel has to have been defined; any
  10     further conditions on x and y, and the type of the returned
  11     value depends on the definition of xx_rel.
  12
  13     For non-object x and y:
  14
  15     x           any
  16     y           any
  17
  18     return      if x and y are both real: -1, 0, or 1
  19                 if x and y are both numbers but not both real:
  20                         -1, 0, 1, -1+1i, 1i, 1+1i, -1-1i, -1i, or 1-1i
  21                 if x and y are both strings: -1, 0, or 1
  22                 all other cases: the null value
  23
  24 DESCRIPTION
  25
  26     x and y both real: cmp(x, y) = sgn(x - y), i.e. -1, 0, or 1
  27         according as x < y, x == y, or x > y
  28
  29     x and y both numbers, at least one being complex:
  30         cmp(x,y) = sgn(re(x) - re(y)) + sgn(im(x) - im(y)) * 1i
  31
  32     x and y both strings: successive characters are compared until either
  33         different characters are encountered or at least one string is
  34         completed.  If the comparison ends because of different characters,
  35         cmp(x,y) = 1 or -1 according as the greater character is in x or y.
  36         If all characters compared in both strings are equal, then
  37         cmp(x,y) = -1, 0 or 1 according as the length of x is less than,
  38         equal to, or greater than the length of y.  (This comparison
  39         is performed via the strcmp() libc function.)
  40
  41     objects: comparisons of objects are usually intended for some total or
  42         partial ordering and appropriate definitions of cmp(a,b) may
  43         make use of comparison of numerical or string components.
  44         definitions using comparison of numbers or strings are usually
  45         appropriate.  For example, after
  46
  47                 obj point {x,y};
  48
  49         if points with real components are to be partially ordered by their
  50         euclidean distance from the origin, an appropriate point_rel
  51         function may be that given by
  52
  53                 define point_rel(a,b) = sgn(a.x^2 + a.y^2 - b.x^2 - b.y^2);
  54
  55         A total "lexicographic" ordering is that given by:
  56
  57                 define point_rel(a,b) {
  58                         if (a.y != b.y)
  59                                 return sgn(a.y - b.y);
  60                         return (a.x - b.x);
  61                 }
  62
  63         A comparison function that compares points analogously to
  64         cmp(a,b) for real and complex numbers is that given by
  65
  66                 define point_rel(P1, P2) {
  67                         return obj point = {sgn(P1.x-P2.x), sgn(P1.y-P2.y)};
  68                 }
  69
  70         The range of this function is the set of nine points with zero
  71         or unit components.
  72
  73
  74     Some properties of cmp(a,b) for real or complex a and b are:
  75
  76         cmp(a + c, b + c) = cmp(a, b)
  77
  78         cmp(a, b) == 0 if and only if a == b
  79
  80         cmp(b, a) = -cmp(a, b)
  81
  82         if c is real or pure imaginary, cmp(c * a, c * b) = c * cmp(a,b)
  83
  84     Then a function that defines "b is between a and c" in an often useful
  85     sense is
  86
  87         define between(a,b,c) = (cmp(a,b) == cmp(b,c)).
  88
  89     For example, in this sense, 3 + 4i is between 1 + 5i and 4 + 2i.
  90
  91     Note that using cmp to compare non-object values of different types,
  92     for example, cmp(2, "2"), returns the null value.
  93
  94 EXAMPLE
  95     > print cmp(3,4), cmp(4,3), cmp(4,4), cmp("a","b"), cmp("abcd","abc")
  96     -1 1 0 -1 1
  97
  98     > print cmp(3,4i), cmp(4,4i), cmp(5,4i), cmp(-5,4i), cmp(-4i,5), cmp(-4i,-5)
  99     1-1i 1-1i 1-1i -1-1i -1-1i 1-1i
 100
 101     > print cmp(3i,4i), cmp(4i,4i), cmp(5i,4i), cmp(3+4i,5), cmp(3+4i,-5)
 102     -1i 0 1i -1+1i 1+1i
 103
 104     > print cmp(3+4i,3+4i), cmp(3+4i,3-4i), cmp(3+4i,2+3i), cmp(3+4i,-4-5i)
 105     0 1i 1+1i 1+1i
 106
 107 LIMITS
 108     none
 109
 110 LINK LIBRARY
 111     FLAG qrel(NUMBER *q1, NUMBER *q2)
 112     FLAG zrel(ZVALUE z1, ZVALUE z2)
 113
 114 SEE ALSO
 115     sgn, test, operator
 116