List and text utilities

This document explains the various list manipulation utilities
available in Isis. Since strings are represented as lists of
characters in Isis, all of these routines may be used on strings and
text in an analogous way.

Creating and retrieving items from lists

To create a new list, use the Isis list formation construct (simply
place the expressions inside of square brackets []):

[expexp ... ]

To retrieve a particular item from a list, use the Isis list reference construct:

Basic operators

(length list) # number of items in list
(head list) # first item in list, equivalent to (list 0)
(tail list) # last item in list, equivalent to (list (- (length list) 1))
If the given list is empty, head and tail will
return Null.

Inserting and appending

(insert-before k val list) # insert val before item k in list
(insert-after k val list) # insert val after item k in list
(head-insert val list) # insert val at beginning of list
(tail-insert val list) # insert val at end of list
(append list1 list2 ...) # append lists together into one big list
In these routines, k should be an integer list index,
indicating where to insert the new item in the list. If k is
negative, the value will be inserted at the beginning of the list, and
if k is greater than the length of the list, the item will be
inserted at the end of the list.

Sublist operators

(sublist n m list) # return section of list between index m and n, inclusive
(first k list) # return the first k items in list
(last k list) # return the last k items in the list
(allbutfirst k list) # return all but the first k items in the list
(allbutlast k list) # return all but the last k items in the list
In these routines, n, m, and k should be
integer list indices, which will be clamped between 0 and the size of
the list before the operation is performed.

Changing and removing items

(change-item index val list) # change specified index to val in list
(remove-item index list) # remove specified index from list
(change-items indexlist vallist list) # change specified indices in list
(remove-items indexlist list) # remove specified indices in list
In these routines, index should be an integer list index, and
indexlist should be a list of indices. change-items
changes the specified indices in indexlist to the
corresponding values in vallist. If any indices are out of
range, an error message is printed, and the list is not affected.

Lists and procedures

(apply procedure arglist) # apply procedure to a list of arguments
(map procedure arg1list arg2list ...) # apply procedure to corresponding elements in lists
apply applies a procedure to the arguments given in a list.

-> (+ 1 2 3)
6
-> (apply + [1 2 3])
6

map is a powerful operator that applies a procedure to
corresponding items in any number of argument lists, and returns a
list of the results. The number of arguments the procedure accepts
must match the number of argument lists passed.

Sorting and reordering

(sort sortproc list) # sort list using sortproc as the predicate
(foremost sortproc list) # find foremost item in list using sortproc as the predicate
(hindmost sortproc list) # find hindmost item in list using sortproc as the predicate
(reorder indexlist list) # reorder list in the order specified in indexlist
sort sorts a list using the given procedure to determine how
it's ordered. foremost and hindmost are similar to
sort, but instead of sorting the entire list, they just return the
index of the item that would be first or last if the list was
sorted. reorder rearrages the items in a list in the order
specified by the given list of indices, which does not have to be the
same length as the list.

Other basic utilities

(reverse list) # reverse the order of the items in a list
(make-list len val) # make a new list filled with val
(make-series start len increment) # make a new list with a mathematical series
(assoc key list) # search a list of lists for a particular head item
reverse reverses the order of a list, and make-list
forms a new list of a certain length filled with a single value.

assoc searches a list of lists for a particular item. If the
given key matches the first item of one of the lists, the
entire matching list is returned. Otherwise, Null is
returned. As such, assoc can be useful in searching a
database that takes the form of a list of lists.

search-all looks for all occurrences of a value in a list and
returns a list of indices. remove-all removes all
occurrences of a value from a list and returns the modified list.
replace-all replaces all occurrences of a value and returns
the modified list.

search-list looks for a list l1 embedded in another
list l2 and returns the starting index of the first
occurrence or Null if not found. Since strings are just lists of
characters, search-string points to the same function as
search-list and has the same effect.

remove-list and remove-string also point to the same
function, as do replace-list and replace-string.
The former function removes all occurrences of a list l1
embedded in another list l2 and return the modified list.
The latter replaces all occurrences of an embedded list with a new
list and returns the modified list.

string-to-line-list separates a string to a list of lines,
where each line is of a length less than maxlinelength.
The only exception is if there is a word in the string which is
itself longer than maxlinelength; in this case the word is given
its own line and is not truncated. Any existing newline characters
are NOT given special treatment and do not force a line break.

-> (string-to-line-list 20 "Bob, please do not speak out of turn.")
[ "Bob, please do not" "speak out of turn." ]
-> (string-to-line-list 5 "But I was only trying to be a good boy.")
[ "But I" "was" "only" "trying" "to be" "a" "good" "boy." ]

fill-text fills a piece of text, adding newline characters to
keep lines at a maximum length. If a word is too long for the line,
it is not broken. It leaves any newlines already in the text
untouched.

-> (fill-text 20 "this is a test of the emergency broadcast system.")
"this is a test of
the emergency
broadcast system."
-> (fill-text 10 "this is a test of the emergency broadcast system.")
"this is a
test of
the
emergency
broadcast
system."