PLOGHELP COMPARE             Jonathan Laventhol, Tuesday 20th March 1984
                                Revised by Kathryn Seifert  October 1986

Operators to perform metalogical comparisons on Prolog objects

    ?- compare(Relation, Item1, Item2).
    ?- sort(List, Sorted_List).
    ?- keysort(List, Sorted_List).
    ?- A @< B.
    ?- A @=< B.
    ?- A @> B.
    ?- A @>= B.

Keywords: metalogical comparisons, comparison

There are builtin predicates for comparison of arbitrary Prolog objects.
They are metalogical, in that they treat uninstantiated variables as
objects, and never instantiate them.  Normally you want either
arithmetic comparison or unification (see PLOGHELP * EQUAL, *LESSTHAN
and PLOGHELP * GREATERTHAN), but sometimes they are useful.  There is a
standard ordering of terms, which has no status other than that it is a
standard, and it does order all terms.

-- Standard Ordering --------------------------------------------------

This is the standard ordering:
    FIRST
        All non-Prolog objects
        Uninstantiated variables.
        Numbers
        Atoms
        Compound terms.
    LAST

Notes:
    Non-Prolog items (such as POP11 strings, procedures, booleans), are
ordered alphabetically by their printed notation.
    Uninstantiated variables are ordered by their printing numbers.
This number is undefined unless the number has already been compared or
printed, or it shares with a variable which already has a number.
    No distinction is made between numbers of different representations
(decimals are the same as integers for comparison purposes).
    Atoms are sorted alphabetically.
    Compound terms are ordered first by arity (lowest first), then
alphabetically by functor, then by standard comparison of arguments
(left- to-right).

This ordering will be the same as in DEC10 Prolog for all data types
which exist in that system -- POPLOG Prolog has more data types
(notably, more kinds of numbers, plus objects from POP11 programs).


-- Predicates ---------------------------------------------------------

These are the built in predicates which use the standard ordering:

    ?- compare(Relation, Item1, Item2).
Relation will be unified with '<', '>' or '=', for where the first item
is before, after, or the same as the second in the standard ordering.

    ?- sort(List, Sorted).
List is sorted by the standard ordering, and unified with Sorted.
Identical items are merged -- that is, if two items come out as '=' by
compare/3, only one of them remain in the sorted list.

    ?- keysort(List, Sorted).
List should be a list of terms of arity 2.  The elements are sorted by
standard ordering of the first argument of the elements.  No merging
takes place, and items which are '=' by compare/3 remain in the order
they started off in.

There are also four comparison operators:

    A @< B          A is before B in the standard ordering
    A @=< B         A isn't after B
    A @> B          A is after B
    A @>= B         A isn't before B


-- Examples -----------------------------------------------------------

    ?- sort([hello, there, jonathan, X, Y, Z, hello(8), there], T).
    X = _1
    Y = _2
    Z = _3
    T = [_1, _2, _3, hello, jonathan, there, hello(8)] ?
    yes

    ?- sort([a(1,2,3), a(3,2,1), a(1,2), a], X).
    X = [a, a(1, 2), a(1, 2, 3), a(3, 2, 1)] ?
    yes

    ?- keysort([10-foo, 2-foo(hello), X-100], T).
    X = _1
    T = [_1 - 100, 2 - foo(hello), 10 - foo] ?
    yes

    ?- compare(X, foo, foo(1,2,3)).
    X = < ?
    yes

    ?- foo @> foo(1,2,3).
    no

-- RELATED DOCUMENTATION ----------------------------------------------

PLOGHELP * IS
 Evaluating POP-11 and arithmetic expressions which return one result

PLOGHELP * SYMBOLS
 Summary and index of HELP files for symbols used in Prolog

PLOGHELP * OPERATORS
 Operator declarations made when the Prolog system is loaded

PLOGHELP * OP
 How to declare operators

PLOGHELP * SORT
 Predicate for sorting lists

PLOGHELP * KEYSORT
 Predicate for sorting lists of terms with an arity of two