4.1cBSD/usr/src/ucb/lisp/lisplib/manual/ch2.r
CHAPTER 2
Data Structure Access
The following functions allow one to create and manipu-
late the various types of lisp data structures. Refer to
1.3 for details of the data structures known to FRANZ LISP.
2.1. Lists
The following functions exist for the creation and
manipulating of lists. Lists are composed of a linked list
of objects called either 'list cells', 'cons cells' or 'dtpr
cells'. Lists are normally terminated with the special sym-
bol nil. nil is both a symbol and a representation for the
empty list ().
2.1.1. list creation
(cons 'g_arg1 'g_arg2)
RETURNS: a new list cell whose car is g_arg1 and whose
cdr is g_arg2.
(xcons 'g_arg1 'g_arg2)
EQUIVALENT TO: (_c_o_n_s '_g__a_r_g_2 '_g__a_r_g_1)
(ncons 'g_arg)
EQUIVALENT TO: (_c_o_n_s '_g__a_r_g _n_i_l)
9
9Data Structure Access 2-1
Data Structure Access 2-2
(list ['g_arg1 ... ])
RETURNS: a list whose elements are the g_arg_i.
(append 'l_arg1 'l_arg2)
RETURNS: a list containing the elements of l_arg1 fol-
lowed by l_arg2.
NOTE: To generate the result, the top level list cells
of l_arg1 are duplicated and the cdr of the last
list cell is set to point to l_arg2. Thus this
is an expensive operation if l_arg1 is large.
See the descriptions of _n_c_o_n_c and _t_c_o_n_c for
cheaper ways of doing the _a_p_p_e_n_d if the list
l_arg1 can be altered.
(append1 'l_arg1 'g_arg2)
RETURNS: a list like l_arg1 with g_arg2 as the last
element.
NOTE: this is equivalent to (append 'l_arg1 (list
'g_arg2)).
____________________________________________________
; A common mistake is using append to add one element to the end of a list
-> (_a_p_p_e_n_d '(_a _b _c _d) '_e)
(a b c d . e)
; better is append1
-> (_a_p_p_e_n_d_1 '(_a _b _c _d) '_e)
(a b c d e)
____________________________________________________
(quote! g_form1 ...)
RETURNS: The list resulting from the splicing and
insertion process described below on the list
beginning with g_form1.
NOTE: _q_u_o_t_e! is the complement of the _l_i_s_t function.
_l_i_s_t forms a list by evaluating each for in the
argument list; evaluation is suppressed if the
form is _q_u_o_t_eed. In _q_u_o_t_e!, each form is impli-
citly _q_u_o_t_eed. To be evaluated, a form must be
preceded by one of the evaluate operations ! and
!!. ! g_form evaluates g_form and the value is
inserted in the place of the call; !! g_form
Printed: October 7, 1982
Data Structure Access 2-3
evaluates g_form and the value is spliced into
the place of the call. Splicing in means that
the parentheses surrounding the list are removed
as the example below shows. Use of the evaluate
operators can occur at any level in a form argu-
ment.
Another way to get the effect of the _q_u_o_t_e! func-
tion is to use the backquote character macro (see
Section 8.3.3).
____________________________________________________
(_q_u_o_t_e! _c_o_n_s ! (_c_o_n_s _1 _2) _3) = (_c_o_n_s (_1 . _2) _3)
(_q_u_o_t_e! _1 !! (_l_i_s_t _2 _3 _4) _5) = (_1 _2 _3 _4 _5)
(_q_u_o_t_e! _t_r_y ! '(_t_h_i_s ! _o_n_e)) = (_t_r_y (_t_h_i_s ! _o_n_e))
____________________________________________________
(bignum-to-list 'b_arg)
RETURNS: A list of the fixnums which are used to
represent the bignum.
NOTE: the inverse of this function is _l_i_s_t-_t_o-_b_i_g_n_u_m.
(list-to-bignum 'l_ints)
WHERE: l_ints is a list of fixnums.
RETURNS: a bignum constructed of the given fixnums.
NOTE: the inverse of this function is _b_i_g_n_u_m-_t_o-_l_i_s_t.
2.1.2. list predicates
9
9 Printed: October 7, 1982
Data Structure Access 2-4
(dtpr 'g_arg)
RETURNS: t iff g_arg is a list cell.
NOTE: that (dtpr '()) is nil.
(listp 'g_arg)
RETURNS: t iff g_arg is a list object or nil.
(tailp 'l_x 'l_y)
RETURNS: t iff by _c_d_ring down l_y zero or more times, a
list cell _e_q to l_x is found.
____________________________________________________
-> (_s_e_t_q _x '(_a _b _c _d) _y (_c_d_d_r _x))
(c d)
-> (_a_n_d (_d_t_p_r _x) (_l_i_s_t_p _x)) ; x and y are dtprs and lists
t
-> (_d_t_p_r '()) ; () is the same as nil and is not a dtpr
nil
-> (_l_i_s_t_p '()) ; however it is a list
t
-> (_t_a_i_l_p _y _x)
(c d)
____________________________________________________
(length 'l_arg)
RETURNS: the number of elements in the top level of
list l_arg.
2.1.3. list accessing
9
9 Printed: October 7, 1982
Data Structure Access 2-5
(c..r 'lh_arg)
WHERE: the .. represents any positive number of a's
and d's.
RETURNS: the result of accessing the list structure in
the way determined by the function name. The
a's and d's are read from right to left, a d
directing the access down the cdr part of the
list cell and an a down the car part.
NOTE: lh_arg may also be nil, and it is guaranteed that
the car and cdr of nil is nil. If lh_arg is a
hunk, then (_c_a_r '_l_h__a_r_g) is the same as
(_c_x_r _1 '_l_h__a_r_g) and (_c_d_r '_l_h__a_r_g) is the same as
(_c_x_r _0 '_l_h__a_r_g).
It is generally hard to read and understand the
context of functions with large strings of a's
and d's, but these functions are supported by
rapid accessing and open-compiling (see Chapter
12).
(nthcdr 'x_index 'l_list)
RETURNS: the result of _c_d_ring down the list l_list
x_index times.
NOTE: If x_index is less than 0, then
(_c_o_n_s _n_i_l '_l__l_i_s_t) is returned.
(nthelem 'x_arg1 'l_arg2)
RETURNS: The x_arg1'_s_t element of the list l_arg2.
NOTE: If x_arg1 is non-positive or greater than the
length of the list, nil is returned.
(last 'l_arg)
RETURNS: the last list cell in the list l_arg.
EXAMPLE: _l_a_s_t does NOT return the last element of a
list!
(_l_a_s_t '(_a _b)) = (b)
9
9 Printed: October 7, 1982
Data Structure Access 2-6
(ldiff 'l_x 'l_y)
RETURNS: a list of all elements in l_x but not in l_y
, i.e., the list difference of l_x and l_y.
NOTE: l_y must be a tail of l_x, i.e., _e_q to the result
of applying some number of _c_d_r's to l_x. Note
that the value of _l_d_i_f_f is always new
list structure unless l_y is nil, in which case
(_l_d_i_f_f _l__x _n_i_l) is l_x itself. If l_y is not
a tail of l_x, _l_d_i_f_f generates an error.
EXAMPLE: (_l_d_i_f_f '_l__x (_m_e_m_b_e_r '_g__f_o_o '_l__x)) gives all
elements in l_x up to the first g_foo.
2.1.4. list manipulation
(rplaca 'lh_arg1 'g_arg2)
RETURNS: the modified lh_arg1.
SIDE EFFECT: the car of lh_arg1 is set to g_arg2. If
lh_arg1 is a hunk then the second element
of the hunk is set to g_arg2.
(rplacd 'lh_arg1 'g_arg2)
RETURNS: the modified lh_arg1.
SIDE EFFECT: the cdr of lh_arg2 is set to g_arg2. If
lh_arg1 is a hunk then the first element
of the hunk is set to g_arg2.
(attach 'g_x 'l_l)
RETURNS: l_l whose _c_a_r is now g_x, whose _c_a_d_r is the
original (_c_a_r _l__l), and whose _c_d_d_r is the ori-
ginal (_c_d_r _l__l).
NOTE: what happens is that g_x is added to the begin-
ning of list l_l yet maintaining the same list
cell at the beginning of the list.
9
9 Printed: October 7, 1982
Data Structure Access 2-7
(delete 'g_val 'l_list ['x_count])
RETURNS: the result of splicing g_val from the top
level of l_list no more than x_count times.
NOTE: x_count defaults to a very large number, thus if
x_count is not given, all occurrences of g_val
are removed from the top level of l_list. g_val
is compared with successive _c_a_r's of l_list using
the function _e_q_u_a_l.
SIDE EFFECT: l_list is modified using rplacd, no new
list cells are used.
(delq 'g_val 'l_list ['x_count])
(dremove 'g_val 'l_list ['x_count])
RETURNS: the result of splicing g_val from the top
level of l_list no more than x_count times.
NOTE: _d_e_l_q (and _d_r_e_m_o_v_e) are the same as _d_e_l_e_t_e except
that _e_q is used for comparison instead of _e_q_u_a_l.
(remove 'g_x 'l_l)
RETURNS: a _c_o_p_y of l_l with all top level elements
_e_q_u_a_l to g_x removed.
NOTE: remove does not modify its arguments like _d_e_l_e_t_e,
and _d_e_l_q do.
____________________________________________________
; note that you should use the value returned by _d_e_l_e_t_e or _d_e_l_q
; and not assume that g_val will always show the deletions.
; For example
-> (_s_e_t_q _t_e_s_t '(_a _b _c _a _d _e))
(a b c a d e)
-> (_d_e_l_e_t_e '_a _t_e_s_t)
(b c d e) ; the value returned is what we would expect
-> _t_e_s_t
(a b c d e) ; but test still has the first a in the list!
____________________________________________________
9
9 Printed: October 7, 1982
Data Structure Access 2-8
(insert 'g_object 'l_list 'u_comparefn 'g_nodups)
RETURNS: a list consisting of l_list with g_object des-
tructively inserted in a place determined by
the ordering function u_comparefn.
NOTE: (_c_o_m_p_a_r_e_f_n '_g__x '_g__y) should return something
non-nil if g_x can precede g_y in sorted order,
nil if g_y must precede g_x. If u_comparefn is
nil, alphabetical order will be used. If g_nodups
is non-nil, an element will not be inserted if an
equal element is already in the list. _i_n_s_e_r_t
does binary search to determine where to insert
the new element.
(merge 'l_data1 'l_data2 'u_comparefn)
RETURNS: the merged list of the two input sorted lists
l_data1 and l_data1 using binary comparison
function u_comparefn.
NOTE: (_c_o_m_p_a_r_e_f_n '_g__x '_g__y) should return something
non-nil if g_x can precede g_y in sorted order,
nil if g_y must precede g_x. If u_comparefn is
nil, alphabetical order will be used.
u_comparefn should be thought of as "less than or
equal". _m_e_r_g_e changes both of its data argu-
ments.
(subst 'g_x 'g_y 'l_s)
(dsubst 'g_x 'g_y 'l_s)
RETURNS: the result of substituting g_x for all _e_q_u_a_l
occurrences of g_y at all levels in l_s.
NOTE: If g_y is a symbol, _e_q will be used for comparis-
ons. The function _s_u_b_s_t does not modify l_s but
the function _d_s_u_b_s_t (destructive substitution)
does.
(lsubst 'l_x 'g_y 'l_s)
RETURNS: a copy of l_s with l_x spliced in for every
occurrence of of g_y at all levels. Splicing
in means that the parentheses surrounding the
list l_x are removed as the example below
shows.
9
9 Printed: October 7, 1982
Data Structure Access 2-9
____________________________________________________
-> (_s_u_b_s_t '(_a _b _c) '_x '(_x _y _z (_x _y _z) (_x _y _z)))
((a b c) y z ((a b c) y z) ((a b c) y z))
-> (_l_s_u_b_s_t '(_a _b _c) '_x '(_x _y _z (_x _y _z) (_x _y _z)))
(a b c y z (a b c y z) (a b c y z))
____________________________________________________
(subpair 'l_old 'l_new 'l_expr)
WHERE: there are the same number of elements in
l_old as l_new.
RETURNS: the list l_expr with all occurrences of a
object in l_old replaced by the corresponding
one in l_new. When a substitution is made, a
copy of the value to substitute in is not
made.
EXAMPLE: (_s_u_b_p_a_i_r '(_a _c)' (_x _y) '(_a _b _c _d)) = (_x _b _y _d)
(nconc 'l_arg1 'l_arg2 ['l_arg3 ...])
RETURNS: A list consisting of the elements of l_arg1
followed by the elements of l_arg2 followed by
l_arg3 and so on.
NOTE: The _c_d_r of the last list cell of l_arg_i is
changed to point to l_arg_i+_1.
9
9 Printed: October 7, 1982
Data Structure Access 2-10
____________________________________________________
; _n_c_o_n_c is faster than _a_p_p_e_n_d because it doesn't allocate new list cells.
-> (_s_e_t_q _l_i_s_1 '(_a _b _c))
(a b c)
-> (_s_e_t_q _l_i_s_2 '(_d _e _f))
(d e f)
-> (_a_p_p_e_n_d _l_i_s_1 _l_i_s_2)
(a b c d e f)
-> _l_i_s_1
(a b c) ; note that lis1 has not been changed by _a_p_p_e_n_d
-> (_n_c_o_n_c _l_i_s_1 _l_i_s_2)
(a b c d e f) ; _n_c_o_n_c returns the same value as _a_p_p_e_n_d
-> _l_i_s_1
(a b c d e f) ; but in doing so alters lis1
____________________________________________________
(reverse 'l_arg)
(nreverse 'l_arg)
(dreverse 'l_arg)
RETURNS: the list l_arg with the elements at the top
level in reverse order.
NOTE: The functions _n_r_e_v_e_r_s_e and _d_r_e_v_e_r_s_e do the rever-
sal in place, that is the list structure is modi-
fied.
(nreconc 'l_arg 'g_arg)
EQUIVALENT TO: (_n_c_o_n_c (_n_r_e_v_e_r_s_e '_l__a_r_g) '_g__a_r_g)
2.2. Predicates
The following functions test for properties of
data objects. When the result of the test is either
'false' or 'true', then nil will be returned for
'false' and something other than nil (often t) will be
returned for 'true'.
9
9 Printed: October 7, 1982
Data Structure Access 2-11
(arrayp 'g_arg)
RETURNS: t iff g_arg is of type array.
(atom 'g_arg)
RETURNS: t iff g_arg is not a list or hunk object.
NOTE: (_a_t_o_m '()) returns t.
(bcdp 'g_arg)
RETURNS: t iff g_arg is a data object of type binary.
NOTE: the name of this function is a throwback to the
PDP-11 Lisp system.
(bigp 'g_arg)
RETURNS: t iff g_arg is a bignum.
(dtpr 'g_arg)
RETURNS: t iff g_arg is a list cell.
NOTE: that (dtpr '()) is nil.
(hunkp 'g_arg)
RETURNS: t iff g_arg is a hunk.
(listp 'g_arg)
RETURNS: t iff g_arg is a list object or nil.
(stringp 'g_arg)
RETURNS: t iff g_arg is a string.
(symbolp 'g_arg)
RETURNS: t iff g_arg is a symbol.
9
9 Printed: October 7, 1982
Data Structure Access 2-12
(valuep 'g_arg)
RETURNS: t iff g_arg is a value cell
(type 'g_arg)
(typep 'g_arg)
RETURNS: a symbol whose pname describes the type of
g_arg.
(signp 's_test 'g_val)
RETURNS: t iff g_val is a number and the given test
s_test on g_val returns true.
NOTE: The fact that _s_i_g_n_p simply returns nil if g_val
is not a number is probably the most important
reason that _s_i_g_n_p is used. The permitted values
for s_test and what they mean are given in this
table.
8 ____________________
s_test tested
8 ________________________________________
l g_val < 0
le g_val <_ 0
e g_val = 0
n g_val =/ 0
ge g_val >_ 0
g g_val > 0
8 ____________________
7 |7|7|7|7|7|7|7|7|
|7|7|7|7|7|7|7|7|
(eq 'g_arg1 'g_arg2)
RETURNS: t if g_arg1 and g_arg2 are the exact same lisp
object.
NOTE: _E_q simply tests if g_arg1 and g_arg2 are located
in the exact same place in memory. Lisp objects
which print the same are not necessarily _e_q. The
only objects guaranteed to be _e_q are interned
symbols with the same print name. [Unless a sym-
bol is created in a special way (such as with
_u_c_o_n_c_a_t or _m_a_k_n_a_m) it will be interned.]
9 Printed: October 7, 1982
Data Structure Access 2-13
(neq 'g_x 'g_y)
RETURNS: t if g_x is not _e_q to g_y, otherwise nil.
(equal 'g_arg1 'g_arg2)
(eqstr 'g_arg1 'g_arg2)
RETURNS: t iff g_arg1 and g_arg2 have the same struc-
ture as described below.
NOTE: g_arg and g_arg2 are _e_q_u_a_l if
(1) they are _e_q.
(2) they are both fixnums with the same value
(3) they are both flonums with the same value
(4) they are both bignums with the same value
(5) they are both strings and are identical.
(6) they are both lists and their cars and cdrs are
_e_q_u_a_l.
____________________________________________________
; _e_q is much faster than _e_q_u_a_l, especially in compiled code,
; however you cannot use _e_q to test for equality of numbers outside
; of the range -1024 to 1023. _e_q_u_a_l will always work.
-> (_e_q _1_0_2_3 _1_0_2_3)
t
-> (_e_q _1_0_2_4 _1_0_2_4)
nil
-> (_e_q_u_a_l _1_0_2_4 _1_0_2_4)
t
____________________________________________________
9
9 Printed: October 7, 1982
Data Structure Access 2-14
(not 'g_arg)
(null 'g_arg)
RETURNS: t iff g_arg is nil.
(member 'g_arg1 'l_arg2)
(memq 'g_arg1 'l_arg2)
RETURNS: that part of the l_arg2 beginning with the
first occurrence of g_arg1. If g_arg1 is not
in the top level of l_arg2, nil is returned.
NOTE: _m_e_m_b_e_r tests for equality with _e_q_u_a_l, _m_e_m_q tests
for equality with _e_q.
2.3. Symbols and Strings
In many of the following functions the distinction
between symbols and strings is somewhat blurred. The
difference is that a symbol is a lisp object with a
value, property list, function binding and a external
representation (print name) which happens to be a
string. A string is a simply a constant, the value of
a string is the same string. If a symbol is given to
one of the string manipulation functions below, its
print name will be used.
Another popular way to represent strings in Lisp
is as a list of fixnums which represent characters.
The suffix 'n' to a string manipulation function indi-
cates that it returns a string in this form.
2.3.1. symbol and string creation
9
9 Printed: October 7, 1982
Data Structure Access 2-15
(concat ['stn_arg1 ... ])
(uconcat ['stn_arg1 ... ])
RETURNS: a symbol whose print name is the result of
concatenating the print names, string charac-
ters or numerical representations of the
sn_arg_i.
NOTE: If no arguments are given, a symbol with a null
pname is returned. _c_o_n_c_a_t places the symbol
created on the oblist, the function _u_c_o_n_c_a_t does
the same thing but does not place the new symbol
on the oblist.
EXAMPLE: (_c_o_n_c_a_t '_a_b_c (_a_d_d _3 _4) "_d_e_f") = abc7def
(concatl 'l_arg)
EQUIVALENT TO: (_a_p_p_l_y '_c_o_n_c_a_t '_l__a_r_g)
(implode 'l_arg)
(maknam 'l_arg)
WHERE: l_arg is a list of symbols, strings and small
fixnums.
RETURNS: The symbol whose print name is the result of
concatenating the first characters of the
print names of the symbols and strings in the
list. Any fixnums are converted to the
equivalent ascii character. In order to con-
catenate entire strings or print names, use
the function _c_o_n_c_a_t.
NOTE: _i_m_p_l_o_d_e interns the symbol it creates, _m_a_k_n_a_m
does not.
(gensym ['s_leader])
RETURNS: a new uninterned atom beginning with the first
character of s_leader's pname, or beginning
with g if s_leader is not given.
NOTE: The symbol looks like x0nnnnn where x is
s_leader's first character and nnnnn is the
number of times you have called gensym.
9
9 Printed: October 7, 1982
Data Structure Access 2-16
(copysymbol 's_arg 'g_pred)
RETURNS: an uninterned symbol with the same print name
as s_arg. If g_pred is non nil, then the
value, function binding and property list of
the new symbol are made _e_q to those of s_arg.
(ascii 'x_charnum)
WHERE: x_charnum is between 0 and 255.
RETURNS: a symbol whose print name is the single char-
acter whose fixnum representation is
x_charnum.
(intern 's_arg)
RETURNS: s_arg
SIDE EFFECT: s_arg is put on the oblist if it is not
already there.
(remob 's_symbol)
RETURNS: s_symbol
SIDE EFFECT: s_symbol is removed from the oblist.
(rematom 's_arg)
RETURNS: t if s_arg is indeed an atom.
SIDE EFFECT: s_arg is put on the free atoms list,
effectively reclaiming an atom cell.
NOTE: This function does _n_o_t check to see if s_arg is
on the oblist or is referenced anywhere. Thus
calling _r_e_m_a_t_o_m on an atom in the oblist may
result in disaster when that atom cell is reused!
2.3.2. string and symbol predicates
9
9 Printed: October 7, 1982
Data Structure Access 2-17
(symbolp 'g_arg)
RETURNS: t iff g_arg is a symbol.
(stringp 'g_arg)
RETURNS: t iff g_arg is a string.
(boundp 's_name)
RETURNS: nil if s_name is unbound, that is it has
never be given a value. If x_name has the
value g_val, then (nil . g_val) is returned.
(alphalessp 'st_arg1 'st_arg2)
RETURNS: t iff the `name' of st_arg1 is alphabetically
less than the name of st_arg2. If st_arg is a
symbol then its `name' is its print name. If
st_arg is a string, then its `name' is the
string itself.
2.3.3. symbol and string accessing
(symeval 's_arg)
RETURNS: the value of symbol s_arg.
NOTE: It is illegal to ask for the value of an unbound
symbol.
(get_pname 's_arg)
RETURNS: the string which is the print name of s_arg.
(plist 's_arg)
RETURNS: the property list of s_arg.
9
9 Printed: October 7, 1982
Data Structure Access 2-18
(getd 's_arg)
RETURNS: the function definition of s_arg or nil if
there is no function definition.
NOTE: the function definition may turn out to be an
array header.
(getchar 's_arg 'x_index)
(nthchar 's_arg 'x_index)
(getcharn 's_arg 'x_index)
RETURNS: the x_index_t_h character of the print name of
s_arg or nil if x_index is less than 1 or
greater than the length of s_arg's print name.
NOTE: _g_e_t_c_h_a_r and _n_t_h_c_h_a_r return a symbol with a single
character print name, _g_e_t_c_h_a_r_n returns the fixnum
representation of the character.
(substring 'st_string 'x_index ['x_length])
(substringn 'st_string 'x_index ['x_length])
RETURNS: a string of length at most x_length starting
at x_index_t_h character in the string.
NOTE: If x_length is not given, the maximum length
string is returned. If x_index is negative the
string begins at the x_index_t_h character from the
end. If x_index is out of bounds, nil is
returned.
NOTE: _s_u_b_s_t_r_i_n_g returns a list of symbols, _s_u_b_s_t_r_i_n_g_n
returns a list of fixnums. If _s_u_b_s_t_r_i_n_g_n is
given a 0 x_length argument then a single fixnum
which is the x_index_t_h character is returned.
2.3.4. symbol and string manipulation
9
9 Printed: October 7, 1982
Data Structure Access 2-19
(set 's_arg1 'g_arg2)
RETURNS: g_arg2.
SIDE EFFECT: the value of s_arg1 is set to g_arg2.
(setq s_atm1 'g_val1 [ s_atm2 'g_val2 ... ... ])
WHERE: the arguments are pairs of atom names and
expressions.
RETURNS: the last g_val_i.
SIDE EFFECT: each s_atm_i is set to have the value
g_val_i.
(desetq sl_pattern1 'g_exp1 [... ...])
RETURNS: g_expn
SIDE EFFECT: This acts just like _s_e_t_q if all the
sl_pattern_i are symbols. If sl_pattern_i
is a list then it is a template which
should have the same structure as g_exp_i
The symbols in sl_pattern are assigned to
the corresponding parts of g_exp.
EXAMPLE: (_d_e_s_e_t_q (_a _b (_c . _d)) '(_1 _2 (_3 _4 _5)))
sets a to 1, b to 2, c to 3, and d to (4 5).
(setplist 's_atm 'l_plist)
RETURNS: l_plist.
SIDE EFFECT: the property list of s_atm is set to
l_plist.
(makunbound 's_arg)
RETURNS: s_arg
SIDE EFFECT: the value of s_arg is made `unbound'. If
the interpreter attempts to evaluate s_arg
before it is again given a value, an
unbound variable error will occur.
9
9 Printed: October 7, 1982
Data Structure Access 2-20
(aexplode 's_arg)
(explode 'g_arg)
(aexplodec 's_arg)
(explodec 'g_arg)
(aexploden 's_arg)
(exploden 'g_arg)
RETURNS: a list of the characters used to print out
s_arg or g_arg.
NOTE: The functions beginning with 'a' are internal
functions which are limited to symbol arguments.
The functions _a_e_x_p_l_o_d_e and _e_x_p_l_o_d_e return a list
of characters which _p_r_i_n_t would use to print the
argument. These characters include all necessary
escape characters. Functions _a_e_x_p_l_o_d_e_c and
_e_x_p_l_o_d_e_c return a list of characters which _p_a_t_o_m
would use to print the argument (i.e. no escape
characters). Functions _a_e_x_p_l_o_d_e_n and _e_x_p_l_o_d_e_n
are similar to _a_e_x_p_l_o_d_e_c and _e_x_p_l_o_d_e_c except that
a list of fixnum equivalents of characters are
returned.
____________________________________________________
-> (_s_e_t_q _x '|_q_u_o_t_e _t_h_i_s _\| _o_k?|)
|quote this \| ok?|
-> (_e_x_p_l_o_d_e _x)
(q u o t e |\\| | | t h i s |\\| | | |\\| |\|| |\\| | | o k ?)
; note that |\\| just means the single character: backslash.
; and |\|| just means the single character: vertical bar
; and | | means the single character: space
-> (_e_x_p_l_o_d_e_c _x)
(q u o t e | | t h i s | | |\|| | | o k ?)
-> (_e_x_p_l_o_d_e_n _x)
(113 117 111 116 101 32 116 104 105 115 32 124 32 111 107 63)
____________________________________________________
2.4. Arrays
See Chapter 9 for a complete description of
arrays. Some of these functions are part of a Maclisp
array compatibility package represent only one simple
way of using the array structure of FRANZ LISP.
9
9 Printed: October 7, 1982
Data Structure Access 2-21
2.4.1. array creation
(marray 'g_data 's_access 'g_aux 'x_length 'x_delta)
RETURNS: an array type with the fields set up from the
above arguments in the obvious way (see
1.3.9).
(*array 's_name 's_type 'x_dim1 ... 'x_dim_n)
(array s_name s_type x_dim1 ... x_dim_n)
WHERE: s_type may be one of t, nil, fixnum, flonum,
fixnum-block and flonum-block.
RETURNS: an array of type s_type with n dimensions of
extents given by the x_dim_i.
SIDE EFFECT: If s_name is non nil, the function defini-
tion of s_name is set to the array struc-
ture returned.
NOTE: These functions create a Maclisp compatible
array. In FRANZ LISP arrays of type t, nil, fix-
num and flonum are equivalent and the elements of
these arrays can be any type of lisp object.
Fixnum-block and flonum-block arrays are res-
tricted to fixnums and flonums respectively and
are used mainly to communicate with foreign func-
tions (see 8.4).
NOTE: *_a_r_r_a_y evaluates its arguments, _a_r_r_a_y does not.
2.4.2. array predicate
(arrayp 'g_arg)
RETURNS: t iff g_arg is of type array.
2.4.3. array accessors
9
9 Printed: October 7, 1982
Data Structure Access 2-22
(getaccess 'a_array)
(getaux 'a_array)
(getdelta 'a_array)
(getdata 'a_array)
(getlength 'a_array)
RETURNS: the field of the array object a_array given by
the function name.
(arrayref 'a_name 'x_ind)
RETURNS: the x_ind_t_h element of the array object
a_name. x_ind of zero accesses the first ele-
ment.
NOTE: _a_r_r_a_y_r_e_f uses the data, length and delta fields
of a_name to determine which object to return.
(arraycall s_type 'as_array 'x_ind1 ... )
RETURNS: the element selected by the indicies from the
array a_array of type s_type.
NOTE: if as_array is a symbol then the function binding
of this symbol should contain an array object.
s_type is ignored by _a_r_r_a_y_c_a_l_l but is included
for compatibility with Maclisp.
(arraydims 's_name)
RETURNS: a list of the type and bounds of the array
s_name.
(listarray 'sa_array ['x_elements])
RETURNS: a list of all of the elements in array
sa_array. If x_elements is given, then only
the first x_elements are returned.
9
9 Printed: October 7, 1982
Data Structure Access 2-23
____________________________________________________
; We will create a 3 by 4 array of general lisp objects
-> (_a_r_r_a_y _e_r_n_i_e _t _3 _4)
array[12]
; the array header is stored in the function definition slot of the
; symbol ernie
-> (_a_r_r_a_y_p (_g_e_t_d '_e_r_n_i_e))
t
-> (_a_r_r_a_y_d_i_m_s (_g_e_t_d '_e_r_n_i_e))
(t 3 4)
; store in ernie[2][2] the list (test list)
-> (_s_t_o_r_e (_e_r_n_i_e _2 _2) '(_t_e_s_t _l_i_s_t))
(test list)
; check to see if it is there
-> (_e_r_n_i_e _2 _2)
(test list)
; now use the low level function _a_r_r_a_y_r_e_f to find the same element
; arrays are 0 based and row-major (the last subscript varies the fastest)
; thus element [2][2] is the 10th element , (starting at 0).
-> (_a_r_r_a_y_r_e_f (_g_e_t_d '_e_r_n_i_e) _1_0)
(ptr to)(test list) ; the result is a value cell (thus the (ptr to))
____________________________________________________
2.4.4. array manipulation
(putaccess 'a_array 'su_func)
(putaux 'a_array 'g_aux)
(putdata 'a_array 'g_arg)
(putdelta 'a_array 'x_delta)
(putlength 'y_func 'x_length)
RETURNS: the second argument to the function.
SIDE EFFECT: The field of the array object given by the
function name is replaced by the second
argument to the function.
9
9 Printed: October 7, 1982
Data Structure Access 2-24
(store 'l_arexp 'g_val)
WHERE: l_arexp is an expression which references an
array element.
RETURNS: g_val
SIDE EFFECT: the array location which contains the ele-
ment which l_arexp references is changed
to contain g_val.
(fillarray 's_array 'l_itms)
RETURNS: s_array
SIDE EFFECT: the array s_array is filled with elements
from l_itms. If there are not enough ele-
ments in l_itms to fill the entire array,
then the last element of l_itms is used to
fill the remaining parts of the array.
2.5. Hunks
Hunks are vector like objects whose size can range
from 1 to 128 elements. Internally hunks are allocated
in sizes which are powers of 2. In order to create
hunks of a given size, a hunk with at least that many
elements is allocated and a distinguished symbol EMPTY
is placed in those elements not requested. Most hunk
functions respect those distinguished symbols, but
there are two (*_m_a_k_h_u_n_k and *_r_p_l_a_c_x) which will
overwrite the distinguished symbol.
2.5.1. hunk creation
(hunk 'g_val1 ['g_val2 ... 'g_val_n])
RETURNS: a hunk of length n whose elements are initial-
ized to the g_val_i.
NOTE: the maximum size of a hunk is 128.
EXAMPLE: (_h_u_n_k _4 '_s_h_a_r_p '_k_e_y_s) = {4 sharp keys}
9
9 Printed: October 7, 1982
Data Structure Access 2-25
(makhunk 'xl_arg)
RETURNS: a hunk of length xl_arg initialized to all
nils if xl_arg is a fixnum. If xl_arg is a
list, then we return a hunk of size
(_l_e_n_g_t_h '_x_l__a_r_g) initialized to the elements
in xl_arg.
NOTE: (_m_a_k_h_u_n_k '(_a _b _c)) is equivalent to
(_h_u_n_k '_a '_b '_c).
EXAMPLE: (_m_a_k_h_u_n_k _4) = {_n_i_l _n_i_l _n_i_l _n_i_l}
(*makhunk 'x_arg)
RETURNS: a hunk of size 2[x_arg] initialized to EMPTY.
NOTE: This is only to be used by such functions as _h_u_n_k
and _m_a_k_h_u_n_k which create and initialize hunks for
users.
2.5.2. hunk predicates
(hunkp 'g_arg)
RETURNS: t iff g_arg is a hunk.
(hunksize 'h_arg)
RETURNS: the size of the hunk h_arg.
EXAMPLE: (_h_u_n_k_s_i_z_e (_h_u_n_k _1 _2 _3)) = 3
2.5.3. hunk accessor
(cxr 'x_ind 'h_hunk)
RETURNS: element x_ind (starting at 0) of hunk h_hunk.
2.5.4. hunk manipulators
9
9 Printed: October 7, 1982
Data Structure Access 2-26
(rplacx 'x_ind 'h_hunk 'g_val)
(*rplacx 'x_ind 'h_hunk 'g_val)
RETURNS: h_hunk
SIDE EFFECT: Element x_ind (starting at 0) of h_hunk is
set to g_val.
NOTE: _r_p_l_a_c_x will not modify one of the distinguished
(EMPTY) elements whereas *_r_p_l_a_c_x will.
2.6. Bcds
A bcd object contains a pointer to compiled code
and to the type of function object the compiled code
represents.
(getdisc 'y_bcd)
(getentry 'y_bcd)
RETURNS: the field of the bcd object given by the func-
tion name.
(putdisc 'y_func 's_discipline)
RETURNS: s_discipline
SIDE EFFECT: Sets the discipline field of y_func to
s_discipline.
2.7. Structures
There are three common structures constructed out
of list cells: the assoc list, the property list and
the tconc list. The functions below manipulate these
structures.
2.7.1. assoc list
An `assoc list' (or alist) is a common lisp data
structure. It has the form
((key1 . value1) (key2 . value2) (key3 . value3) ... (keyn . valuen))
9
9 Printed: October 7, 1982
Data Structure Access 2-27
(assoc 'g_arg1 'l_arg2)
(assq 'g_arg1 'l_arg2)
RETURNS: the first top level element of l_arg2 whose
_c_a_r is _e_q_u_a_l (with _a_s_s_o_c) or _e_q (with _a_s_s_q) to
g_arg1.
NOTE: Usually l_arg2 has an _a-_l_i_s_t structure and g_arg1
acts as key.
(sassoc 'g_arg1 'l_arg2 'sl_func)
RETURNS: the result of
(_c_o_n_d ((_a_s_s_o_c '_g__a_r_g '_l__a_r_g_2) (_a_p_p_l_y '_s_l__f_u_n_c _n_i_l)))
NOTE: sassoc is written as a macro.
(sassq 'g_arg1 'l_arg2 'sl_func)
RETURNS: the result of
(_c_o_n_d ((_a_s_s_q '_g__a_r_g '_l__a_r_g_2) (_a_p_p_l_y '_s_l__f_u_n_c _n_i_l)))
NOTE: sassq is written as a macro.
____________________________________________________
; _a_s_s_o_c or _a_s_s_q is given a key and an assoc list and returns
; the key and value item if it exists, they differ only in how they test
; for equality of the keys.
-> (_s_e_t_q _a_l_i_s_t '((_a_l_p_h_a . _a) ( (_c_o_m_p_l_e_x _k_e_y) . _b) (_j_u_n_k . _x)))
((alpha . a) ((complex key) . b) (junk . x))
; we should use _a_s_s_q when the key is an atom
-> (_a_s_s_q '_a_l_p_h_a _a_l_i_s_t)
(alpha . a)
; but it may not work when the key is a list
-> (_a_s_s_q '(_c_o_m_p_l_e_x _k_e_y) _a_l_i_s_t)
nil
; however _a_s_s_o_c will always work
-> (_a_s_s_o_c '(_c_o_m_p_l_e_x _k_e_y) _a_l_i_s_t)
((complex key) . b)
____________________________________________________
9
9 Printed: October 7, 1982
Data Structure Access 2-28
(sublis 'l_alst 'l_exp)
WHERE: l_alst is an assoc list, that is it has the
form
((_k_e_y_1 . _v_a_l_1) (_k_e_y_2 . _v_a_l_2) ...)
RETURNS: the list l_exp with every occurrence of key_i
replaced by val_i.
NOTE: new list structure is returned to prevent modifi-
cation of l_exp. When a substitution is made, a
copy of the value to substitute in is not made.
2.7.2. property list
A property list consists of an alternating
sequence of keys and values. Normally a property list
is stored on a symbol. A list is a 'disembodied' pro-
perty list if it contains an odd number of elements,
the first of which is ignored.
(plist 's_name)
RETURNS: the property list of s_name.
(setplist 's_atm 'l_plist)
RETURNS: l_plist.
SIDE EFFECT: the property list of s_atm is set to
l_plist.
(get 'ls_name 'g_ind)
RETURNS: the value under indicator g_ind in ls_name's
property list if ls_name is a symbol.
NOTE: If there is no indicator g_ind in ls_name's pro-
perty list nil is returned. If ls_name is a list
of an odd number of elements then it is a disem-
bodied property list. _g_e_t searches a disembodied
property list by starting at its _c_d_r and looking
at every other element for g_ind.
9
9 Printed: October 7, 1982
Data Structure Access 2-29
(getl 'ls_name 'l_indicators)
RETURNS: the property list ls_name beginning at the
first indicator which is a member of the list
l_indicators, or nil if none of the indicators
in l_indicators are on ls_name's property
list.
NOTE: If ls_name is a list, then it is assumed to be a
disembodied property list.
(putprop 'ls_name 'g_val 'g_ind)
(defprop ls_name g_val g_ind)
RETURNS: g_val.
SIDE EFFECT: Adds to the property list of ls_name the
value g_val under the indicator g_ind.
NOTE: _p_u_t_p_r_o_p evaluates it arguments, _d_e_f_p_r_o_p does not.
ls_name may be a disembodied property list, see
_g_e_t.
(remprop 'ls_name 'g_ind)
RETURNS: the portion of ls_name's property list begin-
ning with the property under the indicator
g_ind. If there is no g_ind indicator in
ls_name's plist, nil is returned.
SIDE EFFECT: the value under indicator g_ind and g_ind
itself is removed from the property list
of ls_name.
NOTE: ls_name may be a disembodied property list, see
_g_e_t.
9
9 Printed: October 7, 1982
Data Structure Access 2-30
____________________________________________________
-> (_p_u_t_p_r_o_p '_x_l_a_t_e '_a '_a_l_p_h_a)
a
-> (_p_u_t_p_r_o_p '_x_l_a_t_e '_b '_b_e_t_a)
b
-> (_p_l_i_s_t '_x_l_a_t_e)
(alpha a beta b)
-> (_g_e_t '_x_l_a_t_e '_a_l_p_h_a)
a
; use of a disembodied property list:
-> (_g_e_t '(_n_i_l _f_a_t_e_m_a_n _r_j_f _s_k_l_o_w_e_r _k_l_s _f_o_d_e_r_a_r_o _j_k_f) '_s_k_l_o_w_e_r)
kls
____________________________________________________
2.7.3. tconc structure
A tconc structure is a special type of list
designed to make it easy to add objects to the end. It
consists of a list cell whose _c_a_r points to a list of
the elements added with _t_c_o_n_c or _l_c_o_n_c and whose _c_d_r
points to the last list cell of the list pointed to by
the _c_a_r.
(tconc 'l_ptr 'g_x)
WHERE: l_ptr is a tconc structure.
RETURNS: l_ptr with g_x added to the end.
(lconc 'l_ptr 'l_x)
WHERE: l_ptr is a tconc structure.
RETURNS: l_ptr with the list l_x spliced in at the end.
9
9 Printed: October 7, 1982
Data Structure Access 2-31
____________________________________________________
; A _t_c_o_n_c structure can be initialized in two ways.
; nil can be given to _t_c_o_n_c in which case _t_c_o_n_c will generate
; a _t_c_o_n_c structure.
->(_s_e_t_q _f_o_o (_t_c_o_n_c _n_i_l _1))
((1) 1)
; Since _t_c_o_n_c destructively adds to
; the list, you can now add to foo without using _s_e_t_q again.
->(_t_c_o_n_c _f_o_o _2)
((1 2) 2)
->_f_o_o
((1 2) 2)
; Another way to create a null _t_c_o_n_c structure
; is to use (_n_c_o_n_s _n_i_l).
->(_s_e_t_q _f_o_o (_n_c_o_n_s _n_i_l))
(nil)
->(_t_c_o_n_c _f_o_o _1)
((1) 1)
; now see what _l_c_o_n_c can do
-> (_l_c_o_n_c _f_o_o _n_i_l)
((1) 1) ; no change
-> (_l_c_o_n_c _f_o_o '(_2 _3 _4))
((1 2 3 4) 4)
____________________________________________________
2.8. Random functions
The following functions don't fall into any of the
classifications above.
9
9 Printed: October 7, 1982
Data Structure Access 2-32
(bcdad 's_funcname)
RETURNS: a fixnum which is the address in memory where
the function s_funcname begins. If s_funcname
is not a machine coded function (binary) then
_b_c_d_a_d returns nil.
(copy 'g_arg)
RETURNS: A structure _e_q_u_a_l to g_arg but with new list
cells.
(copyint* 'x_arg)
RETURNS: a fixnum with the same value as x_arg but in a
freshly allocated cell.
(cpy1 'xvt_arg)
RETURNS: a new cell of the same type as xvt_arg with
the same value as xvt_arg.
(getaddress 's_entry1 's_binder1 'st_discipline1 [... ...])
RETURNS: the binary object which s_binder1's function
field is set to.
NOTE: This looks in the running lisp's symbol table for
a symbol with the same name as s_entry_i. It then
creates a binary object whose entry field points
to s_entry_i and whose discipline is
st_discipline_i. This binary object is stored in
the function field of s_binder_i. If
st_discipline_i is nil, then "subroutine" is used
by default. This is especially useful for _c_f_a_s_l
users.
(macroexpand 'g_form)
RETURNS: g_form after all macros in it are expanded.
NOTE: This function will only macroexpand expressions
which could be evaluated and it does not know
about the special nlambdas such as _c_o_n_d and _d_o,
thus it misses many macro expansions.
9
9 Printed: October 7, 1982
Data Structure Access 2-33
(ptr 'g_arg)
RETURNS: a value cell initialized to point to g_arg.
(quote g_arg)
RETURNS: g_arg.
NOTE: the reader allows you to abbreviate (quote foo)
as 'foo.
(kwote 'g_arg)
RETURNS: (_l_i_s_t (_q_u_o_t_e _q_u_o_t_e) _g__a_r_g).
(replace 'g_arg1 'g_arg2)
WHERE: g_arg1 and g_arg2 must be the same type of
lispval and not symbols or hunks.
RETURNS: g_arg2.
SIDE EFFECT: The effect of _r_e_p_l_a_c_e is dependent on the
type of the g_arg_i although one will
notice a similarity in the effects. To
understand what _r_e_p_l_a_c_e does to fixnum and
flonum arguments you must first understand
that such numbers are `boxed' in FRANZ
LISP. What this means is that if the sym-
bol x has a value 32412, then in memory
the value element of x's symbol structure
contains the address of another word of
memory (called a box) with 32412 in it.
Thus there are two ways of changing the
value of x, one is to change the value
element of x's symbol structure to point
to a word of memory with a different
value. Another way is to change the value
in the box which x points to. The former
method is used almost all of the time, the
latter is used very rarely and has the
potential to cause great confusion. The
function _r_e_p_l_a_c_e allows you to do the
latter, that is to actually change the
value in the box. You should watch out
for these situations. If you do
(_s_e_t_q _y _x) then both x and y will point
to the same box. If you now
(_r_e_p_l_a_c_e _x _1_2_3_4_5) then y will also have
the value 12345. And in fact there may be
many other pointers to that box. Another
problem with replacing fixnums is that
some boxes are read only. The fixnums
Printed: October 7, 1982
Data Structure Access 2-34
between -1024 and 1023 are stored in a
read only area and attempts to replace
them will result in an "Illegal memory
reference" error (see the description of
_c_o_p_y_i_n_t* for a way around this problem).
For the other valid types, the effect of
_r_e_p_l_a_c_e is easy to understand. The fields
of g_val1's structure are made eq to the
corresponding fields of g_val2's struc-
ture. For example, if x and y have
lists as values then the effect of
(_r_e_p_l_a_c_e _x _y) is the same as
(_r_p_l_a_c_a _x (_c_a_r _y)) and (_r_p_l_a_c_d _x (_c_d_r _y)).
(scons 'x_arg 'bs_rest)
WHERE: bs_rest is a bignum or nil.
RETURNS: a bignum whose first bigit is x_arg and whose
higher order bigits are bs_rest.
(sload 's_file)
SIDE EFFECT: the file s_file (in the current directory)
is opened for reading and each form is
read, printed and evaluated. If the form
is recognizable as a function definition,
only its name will be printed, otherwise
the whole form is printed.
NOTE: This function is useful when a file refuses to
load because of a syntax error and you would like
to narrow down where the error is.
(sort 'l_data 'u_comparefn)
RETURNS: a list of the elements of l_data ordered by
the comparison function u_comparefn
SIDE EFFECT: the list l_data is modified rather than
allocate new storage.
NOTE: (_c_o_m_p_a_r_e_f_n '_g__x '_g__y) should return something
non-nil if g-x can precede g_y in sorted order;
nil if g_y must precede g_x. If u_comparefn is
nil, alphabetical order will be used.
9
9 Printed: October 7, 1982
Data Structure Access 2-35
(sortcar 'l_list 'u_comparefn)
RETURNS: a list of the elements of l_list with the
_c_a_r's ordered by the sort function
u_comparefn.
SIDE EFFECT: the list l_list is modified rather than
allocating new storage.
9
9 Printed: October 7, 1982