.ll 70
.lt 70
.he 'LISTSUMMARY''Page %'
.fo 'Aaron Sloman''\n(dy-\n(mo\-19\n(yr'

.sp 4
.ce 2
SUMMARY OF LIST-PROCESSING IN POP11
------- -- --------------- -- -----

1. Creating lists
   -------- -----
 [     ]

 These "list constant brackets" may contain text items, i.e  words, numbers
and strings. A list of them will be created at compile time.
 E.g
 	[ A B C D] is a list of four words
 	[1 CAT 2 DOG 3 PIG ] is a list of six items.
 	[string 'a short string' 66] is a list with a word a string and a number.

They may also contain lists,
 E.g.
 	[ [1 2]  [3] 4 ] is a list with two lists and one number.




 [%    %]

 These "decorated list brackets" are used to create lists whose
contents depend on the values of variables or the results of executing functions.
 e.g.
 	[% 3, CAT,  HD(L)  %] is
 		a list containing the number 3, the value of the variable CAT
 		and the first element of L, which must be a list.
 	[% [% A %], [% B, C%], [% D %] %] is a list of three lists, whose
 		contents depend on the values of A B C and D.



 ::

 This is an operation for joining an element onto an existing list, to make a
new list,
 e.g.
 	3 :: [4 5 6]   is  a list of four numbers.
.	"CAT" :: []  is  the same as [CAT],
 		but not created at compile time.



 CONS

 This is a function, which can be thought of as equivalent to :: . That is
 	CONS(X,L) is the same as  X :: L



.tp6
 <>

 This is an operator which takes two lists and "concatenates" them to produce
a new list. The first list is copied, so that the original does not have any
extra elements added to its end.
 e.g.
 	[CAT DOG ] <> [PIG MOUSE]  is the same as
 		[CAT DOG PIG MOUSE]
 	LISTA <> LISTB means make a new list containing the
 		elements of LISTA and the elements of LISTB.



 REV

 This is a function which takes a list as argument and creates a new one containing
the same elements in reverse order.
 E.g.
 	REV([A B C])   is   [C B A]





 MAPLIST

 This is a function which takes a list and a function and applies the
function to every element of the list, finally creating a new list containing
all the results.
 E.g.
 	MAPLIST(L, IDENTFN) makes a copy of the list L.
 	MAPLIST([CAT DOG 2 MOUSE 3 4 ], ISWORD) =>
 	** [<TRUE> <TRUE> <FALSE> <TRUE> <FALSE> <FALSE> ]

It could have been defined thus, were it not in the system:
 	FUNCTION MAPLIST (L,F);
 	  [% UNTIL L is [] THEN
 		F(HD(L));
 		TL(L) -> L
 	     CLOSE %]
 	END;

Compare the function APPLIST.




DATALIST

 This function can be applied to a word, string, or strip. It
will create a list containing all the elements of the word string or
strip. The elements of a word or string will be the numbers representing
the characters in it.  (The code for A is 97, for B 98, for Z 122.)
So:
 	DATALIST('ABZ') and DATALIST("ABZ")
 	   both give the list [97 98 122]
 	MAPLIST([CAT DOG MOUSE], DATALIST) =>
 	** [ [99 97 116] [100 111 103] [109 111 117 115 101] ]
.br
This produces a list of lists of character codes. (See MAPLIST, above.)






 2. Accessing components of lists
   --------- ---------- -- -----

 HD

 This function  takes a list as argument and returns the first element of the
list.


 TL

 This function takes a list as argument and returns as its result the sublist
containing all but the first element.

 e.g.
 if L is a list then:
 	HD(TL(L)) is the second element
 	HD(TL(TL(L))) is the third element

 	HD(HD(L)) is the first element of the first element of L


 FRONT  BACK
 These two functions are equivalent to HD and TL, respectively.





3. Miscellaneous functions.
   ------------- ---------

 LENGTH

 This function takes a list and counts the elements, returning a number as its
result.
 E.g
 	LENGTH([1 A [A B C] D])  is 4
 	LENGTH([])  is  0










 ATOM

 This is a type-testing function, which returns TRUE or FALSE as its
result. IF it is applied to a non-empty list (i.e. a list other than []), its
result is FALSE. If it is applied to anything else, e.g. a word,
a function, a string, or [], the result is TRUE.
 So:
 	ATOM([])	is TRUE
 	ATOM(99)		is TRUE
 	ATOM("cat")		is TRUE
 	ATOM(HD)		is TRUE
 	ATOM([CAT DOG])		is FALSE
 	ATOM(3 :: [])		is FALSE





 EQUAL

 This function takes two arguments and produces the result TRUE or FALSE.
Like the operator = it is used for testing for equality. However it is a bit
more intelligent than =. If you create two lists with the same elements
then if you apply = to them, the result will be FALSE, whereas if you
apply EQUAL to them the result will be TRUE.
 So:
 	[CAT DOG] = [CAT DOG]
 			is FALSE

 	EQUAL([CAT DOG], [CAT DOG])
 			is TRUE

EQUAL will dig into embedded lists if necessary, so
 	EQUAL([ 1 [1 2] 3], [ 1 [1 2] 3])
 			is TRUE

EQUAL can be used to compare other data-structures besides lists
for identity of elements. EG. you can compare two strings, and if they have the
same characters EQUAL will return TRUE (whereas 'CAT'='CAT' is
FALSE). It will also compare a word and a string, so:
 	EQUAL(\"CAT", 'CAT')  is TRUE

For other things than lists numbers strings and words, EQUAL applies
DATALIST to its arguments to get two lists of their components,
then compares the two lists.







 APPLIST

 This function takes a list and a function and applies the function to
every element of the list. (Compare MAPLIST.)
 E.g.
 	APPLIST([ 99 ], ISINTEGER) yields <TRUE),
 	APPLIST([ 1 2 A B 3], ISINTEGER) puts on the stack:
 	<TRUE>,<TRUE>,<FALSE>,<FALSE>,<TRUE>
 	APPLIST([], F) does nothing, whatever function F is.

APPLIST could have been defined like MAPLIST (above),
without the decorated list brackets.





4. Global variable  (empty lists)
   ------ --------  ------ ------

NIL

 This is a variable provided by the system whose value is the word "[]"
so that [], NIL, and VALOF("NIL") all refer to the same thing.
[] is conventionally used to represent the "empty" list, so that if you
take a list L and then assign TL(L) to L repeatedly, you'll end up with
L having the value []. Trying to apply HD or TL to [] will
produce an error ("non-list argument for list function, culprit []").
