HELP EQUALTO                                        John Gibson Jan 1996

The * FOR_FORM

    for var equalto pattern [in list] do ... endfor

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

That is, for each item in list such that item = pattern, item is
assigned to the specified variable var and the body of the loop
executed.

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

    vars item, x;

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

    for item equalto =?x:isword in list1 do
        item =>
    endfor;
    ** a
    ** b
    ** c

    vars list2 = [[A is big] [B is small] [C is big] [D is small]];

    for item equalto [=?x is big] in list2 do
        [^item therefore ^x is heavy] =>
    endforpresent;

    ** [[A is big] therefore A is heavy]
    ** [[C is big] therefore C is heavy]


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

    for item equalto [=??x b =**] in [[c a b b a g e]] do
        item=> 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].)


The form for...allequalto (see HELP * allequalto) generalises
for...equalto to matching multiple items rather than single ones.

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



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