HELP ALLEQUALTO                                     John Gibson Jan 1996

The * FOR_FORM

    for var allequalto pattern_list [in list] do ... endfor

allows iteration over all possible lists of elements from a list which
are equal to a given pattern_list (list defaults to the value of the
variable database if the 'in list' clause is omitted).

That is, for every possible item_list that can be constructed from the
elements of list such that item_list = pattern_list, item_list is
assigned to the specified variable var and the body of the loop
executed.

This form is normally used with a pattern_list containing matchvars,
whose corresponding variables will be side-effected by the call to =
(see Pattern Matching With = in HELP * EQUAL). For example:

    vars itemlist, x, y, z;

    vars list = [a 1 b 2 c 3];

    for itemlist allequalto [=?x:isword =?y:isinteger] in list do
        itemlist =>
    endfor;

    ** [a 1]
    ** [a 2]
    ** [a 3]
    ** [b 1]
    ** [b 2]
    ** [b 3]
    ** [c 1]
    ** [c 2]
    ** [c 3]

Another example, using the variable database:

    [
      [1 ison 2] [2 ison 3]
      [A ison B] [B ison C] [D ison E] [E ison F] [G ison H] [A ison I]
    ]
        -> database;

    for itemlist allequalto [[=?x ison =?y:isword][=?y ison =?z]] do
        [^itemlist implies ^x is above ^z] =>
    endfor;

    ** [[[A ison B] [B ison C]] implies A is above C]
    ** [[[D ison E] [E ison F]] implies D is above F]


(Note: If pattern_list contains =** or =?? matchvars, capable of
matching the same list in different ways, then for...allequalto will
only find one way of matching the pattern with that item. E.g.

    for itemlist allequalto [[=??x b =**]] in [[c a b b a g e]] do
        itemlist=> x=>
    endfor;
    ** [[c a b b a g e]]
    ** [c a]

This does not supply the second possible way of of matching the list
[c a b b a g e], namely with x = [c a b].)


for...allequalto is a generalisation of the form for...equalto (see
HELP * equalto), which matches single items rather than multiple items.

(In terms of Pop-11 database procedures, allequalto is to
database_allpresent as equalto is to database_present. See
REF * DATABASE.)



--- C.all/help/allequalto
--- Copyright University of Sussex 1996. All rights reserved.