2 @node Compound Data Types
3 @chapter Compound Data Types
5 This chapter describes Guile's compound data types. By @dfn{compound}
6 we mean that the primary purpose of these data types is to act as
7 containers for other kinds of data (including other compound objects).
8 For instance, a (non-uniform) vector with length 5 is a container that
9 can hold five arbitrary Scheme objects.
11 The various kinds of container object differ from each other in how
12 their memory is allocated, how they are indexed, and how particular
13 values can be looked up within them.
16 * Pairs:: Scheme's basic building block.
17 * Lists:: Special list functions supported by Guile.
18 * Vectors:: One-dimensional arrays of Scheme objects.
21 * Arrays:: Arrays of values.
22 * Association Lists and Hash Tables:: Dictionary data types.
30 Pairs are used to combine two Scheme objects into one compound object.
31 Hence the name: A pair stores a pair of objects.
33 The data type @dfn{pair} is extremely important in Scheme, just like in
34 any other Lisp dialect. The reason is that pairs are not only used to
35 make two values available as one object, but that pairs are used for
36 constructing lists of values. Because lists are so important in Scheme,
37 they are described in a section of their own (@pxref{Lists}).
39 Pairs can literally get entered in source code or at the REPL, in the
40 so-called @dfn{dotted list} syntax. This syntax consists of an opening
41 parentheses, the first element of the pair, a dot, the second element
42 and a closing parentheses. The following example shows how a pair
43 consisting of the two numbers 1 and 2, and a pair containing the symbols
44 @code{foo} and @code{bar} can be entered. It is very important to write
45 the whitespace before and after the dot, because otherwise the Scheme
46 parser would not be able to figure out where to split the tokens.
53 But beware, if you want to try out these examples, you have to
54 @dfn{quote} the expressions. More information about quotation is
55 available in the section (REFFIXME). The correct way to try these
56 examples is as follows.
67 A new pair is made by calling the procedure @code{cons} with two
68 arguments. Then the argument values are stored into a newly allocated
69 pair, and the pair is returned. The name @code{cons} stands for
70 "construct". Use the procedure @code{pair?} to test whether a
71 given Scheme object is a pair or not.
74 @deffn {Scheme Procedure} cons x y
75 @deffnx {C Function} scm_cons (x, y)
76 Return a newly allocated pair whose car is @var{x} and whose
77 cdr is @var{y}. The pair is guaranteed to be different (in the
78 sense of @code{eq?}) from every previously existing object.
82 @deffn {Scheme Procedure} pair? x
83 @deffnx {C Function} scm_pair_p (x)
84 Return @code{#t} if @var{x} is a pair; otherwise return
88 The two parts of a pair are traditionally called @dfn{car} and
89 @dfn{cdr}. They can be retrieved with procedures of the same name
90 (@code{car} and @code{cdr}), and can be modified with the procedures
91 @code{set-car!} and @code{set-cdr!}. Since a very common operation in
92 Scheme programs is to access the car of a pair, or the car of the cdr of
93 a pair, etc., the procedures called @code{caar}, @code{cadr} and so on
98 @deffn {Scheme Procedure} car pair
99 @deffnx {Scheme Procedure} cdr pair
100 Return the car or the cdr of @var{pair}, respectively.
103 @deffn {Scheme Procedure} caar pair
104 @deffnx {Scheme Procedure} cadr pair @dots{}
105 @deffnx {Scheme Procedure} cdddar pair
106 @deffnx {Scheme Procedure} cddddr pair
107 These procedures are compositions of @code{car} and @code{cdr}, where
108 for example @code{caddr} could be defined by
111 (define caddr (lambda (x) (car (cdr (cdr x)))))
116 @deffn {Scheme Procedure} set-car! pair value
117 @deffnx {C Function} scm_set_car_x (pair, value)
118 Stores @var{value} in the car field of @var{pair}. The value returned
119 by @code{set-car!} is unspecified.
123 @deffn {Scheme Procedure} set-cdr! pair value
124 @deffnx {C Function} scm_set_cdr_x (pair, value)
125 Stores @var{value} in the cdr field of @var{pair}. The value returned
126 by @code{set-cdr!} is unspecified.
134 A very important data type in Scheme---as well as in all other Lisp
135 dialects---is the data type @dfn{list}.@footnote{Strictly speaking,
136 Scheme does not have a real datatype @dfn{list}. Lists are made up of
137 @dfn{chained pairs}, and only exist by definition---a list is a chain
138 of pairs which looks like a list.}
140 This is the short definition of what a list is:
144 Either the empty list @code{()},
147 or a pair which has a list in its cdr.
150 @c FIXME::martin: Describe the pair chaining in more detail.
152 @c FIXME::martin: What is a proper, what an improper list?
153 @c What is a circular list?
155 @c FIXME::martin: Maybe steal some graphics from the Elisp reference
159 * List Syntax:: Writing literal lists.
160 * List Predicates:: Testing lists.
161 * List Constructors:: Creating new lists.
162 * List Selection:: Selecting from lists, getting their length.
163 * Append/Reverse:: Appending and reversing lists.
164 * List Modification:: Modifying existing lists.
165 * List Searching:: Searching for list elements
166 * List Mapping:: Applying procedures to lists.
170 @subsection List Read Syntax
172 The syntax for lists is an opening parentheses, then all the elements of
173 the list (separated by whitespace) and finally a closing
174 parentheses.@footnote{Note that there is no separation character between
175 the list elements, like a comma or a semicolon.}.
178 (1 2 3) ; @r{a list of the numbers 1, 2 and 3}
179 ("foo" bar 3.1415) ; @r{a string, a symbol and a real number}
180 () ; @r{the empty list}
183 The last example needs a bit more explanation. A list with no elements,
184 called the @dfn{empty list}, is special in some ways. It is used for
185 terminating lists by storing it into the cdr of the last pair that makes
186 up a list. An example will clear that up:
197 This example also shows that lists have to be quoted (REFFIXME) when
198 written, because they would otherwise be mistakingly taken as procedure
199 applications (@pxref{Simple Invocation}).
202 @node List Predicates
203 @subsection List Predicates
205 Often it is useful to test whether a given Scheme object is a list or
206 not. List-processing procedures could use this information to test
207 whether their input is valid, or they could do different things
208 depending on the datatype of their arguments.
211 @deffn {Scheme Procedure} list? x
212 @deffnx {C Function} scm_list_p (x)
213 Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
216 The predicate @code{null?} is often used in list-processing code to
217 tell whether a given list has run out of elements. That is, a loop
218 somehow deals with the elements of a list until the list satisfies
219 @code{null?}. Then, the algorithm terminates.
222 @deffn {Scheme Procedure} null? x
223 @deffnx {C Function} scm_null_p (x)
224 Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
227 @node List Constructors
228 @subsection List Constructors
230 This section describes the procedures for constructing new lists.
231 @code{list} simply returns a list where the elements are the arguments,
232 @code{cons*} is similar, but the last argument is stored in the cdr of
233 the last pair of the list.
235 @c C Function scm_list(rest) used to be documented here, but it's a
236 @c no-op since it does nothing but return the list the caller must
237 @c have already created.
239 @deffn {Scheme Procedure} list elem1 @dots{} elemN
240 @deffnx {C Function} scm_list_1 (elem1)
241 @deffnx {C Function} scm_list_2 (elem1, elem2)
242 @deffnx {C Function} scm_list_3 (elem1, elem2, elem3)
243 @deffnx {C Function} scm_list_4 (elem1, elem2, elem3, elem4)
244 @deffnx {C Function} scm_list_5 (elem1, elem2, elem3, elem4, elem5)
245 @deffnx {C Function} scm_list_n (elem1, @dots{}, elemN, @nicode{SCM_UNDEFINED})
247 Return a new list containing elements @var{elem1} to @var{elemN}.
249 @code{scm_list_n} takes a variable number of arguments, terminated by
250 the special @code{SCM_UNDEFINED}. That final @code{SCM_UNDEFINED} is
251 not included in the list. None of @var{elem1} to @var{elemN} can
252 themselves be @code{SCM_UNDEFINED}, or @code{scm_list_n} will
253 terminate at that point.
256 @c C Function scm_cons_star(arg1,rest) used to be documented here,
257 @c but it's not really a useful interface, since it expects the
258 @c caller to have already consed up all but the first argument
261 @deffn {Scheme Procedure} cons* arg1 arg2 @dots{}
262 Like @code{list}, but the last arg provides the tail of the
263 constructed list, returning @code{(cons @var{arg1} (cons
264 @var{arg2} (cons @dots{} @var{argn})))}. Requires at least one
265 argument. If given one argument, that argument is returned as
266 result. This function is called @code{list*} in some other
267 Schemes and in Common LISP.
270 @deffn {Scheme Procedure} list-copy lst
271 @deffnx {C Function} scm_list_copy (lst)
272 Return a (newly-created) copy of @var{lst}.
275 @deffn {Scheme Procedure} make-list n [init]
276 Create a list containing of @var{n} elements, where each element is
277 initialized to @var{init}. @var{init} defaults to the empty list
278 @code{()} if not given.
281 Note that @code{list-copy} only makes a copy of the pairs which make up
282 the spine of the lists. The list elements are not copied, which means
283 that modifying the elements of the new list also modifies the elements
284 of the old list. On the other hand, applying procedures like
285 @code{set-cdr!} or @code{delv!} to the new list will not alter the old
286 list. If you also need to copy the list elements (making a deep copy),
287 use the procedure @code{copy-tree} (@pxref{Copying}).
290 @subsection List Selection
292 These procedures are used to get some information about a list, or to
293 retrieve one or more elements of a list.
296 @deffn {Scheme Procedure} length lst
297 @deffnx {C Function} scm_length (lst)
298 Return the number of elements in list @var{lst}.
301 @deffn {Scheme Procedure} last-pair lst
302 @deffnx {C Function} scm_last_pair (lst)
303 Return a pointer to the last pair in @var{lst}, signalling an error if
304 @var{lst} is circular.
308 @deffn {Scheme Procedure} list-ref list k
309 @deffnx {C Function} scm_list_ref (list, k)
310 Return the @var{k}th element from @var{list}.
314 @deffn {Scheme Procedure} list-tail lst k
315 @deffnx {Scheme Procedure} list-cdr-ref lst k
316 @deffnx {C Function} scm_list_tail (lst, k)
317 Return the "tail" of @var{lst} beginning with its @var{k}th element.
318 The first element of the list is considered to be element 0.
320 @code{list-tail} and @code{list-cdr-ref} are identical. It may help to
321 think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list,
322 or returning the results of cdring @var{k} times down @var{lst}.
325 @deffn {Scheme Procedure} list-head lst k
326 @deffnx {C Function} scm_list_head (lst, k)
327 Copy the first @var{k} elements from @var{lst} into a new list, and
332 @subsection Append and Reverse
334 @code{append} and @code{append!} are used to concatenate two or more
335 lists in order to form a new list. @code{reverse} and @code{reverse!}
336 return lists with the same elements as their arguments, but in reverse
337 order. The procedure variants with an @code{!} directly modify the
338 pairs which form the list, whereas the other procedures create new
339 pairs. This is why you should be careful when using the side-effecting
343 @deffn {Scheme Procedure} append lst1 @dots{} lstN
344 @deffnx {Scheme Procedure} append! lst1 @dots{} lstN
345 @deffnx {C Function} scm_append (lstlst)
346 @deffnx {C Function} scm_append_x (lstlst)
347 Return a list comprising all the elements of lists @var{lst1} to
351 (append '(x) '(y)) @result{} (x y)
352 (append '(a) '(b c d)) @result{} (a b c d)
353 (append '(a (b)) '((c))) @result{} (a (b) (c))
356 The last argument @var{lstN} may actually be any object; an improper
357 list results if the last argument is not a proper list.
360 (append '(a b) '(c . d)) @result{} (a b c . d)
361 (append '() 'a) @result{} a
364 @code{append} doesn't modify the given lists, but the return may share
365 structure with the final @var{lstN}. @code{append!} modifies the
366 given lists to form its return.
368 For @code{scm_append} and @code{scm_append_x}, @var{lstlst} is a list
369 of the list operands @var{lst1} @dots{} @var{lstN}. That @var{lstlst}
370 itself is not modified or used in the return.
374 @deffn {Scheme Procedure} reverse lst
375 @deffnx {Scheme Procedure} reverse! lst [newtail]
376 @deffnx {C Function} scm_reverse (lst)
377 @deffnx {C Function} scm_reverse_x (lst, newtail)
378 Return a list comprising the elements of @var{lst}, in reverse order.
380 @code{reverse} constructs a new list, @code{reverse!} modifies
381 @var{lst} in constructing its return.
383 For @code{reverse!}, the optional @var{newtail} is appended to to the
384 result. @var{newtail} isn't reversed, it simply becomes the list
385 tail. For @code{scm_reverse_x}, the @var{newtail} parameter is
386 mandatory, but can be @code{SCM_EOL} if no further tail is required.
389 @node List Modification
390 @subsection List Modification
392 The following procedures modify an existing list, either by changing
393 elements of the list, or by changing the list structure itself.
395 @deffn {Scheme Procedure} list-set! list k val
396 @deffnx {C Function} scm_list_set_x (list, k, val)
397 Set the @var{k}th element of @var{list} to @var{val}.
400 @deffn {Scheme Procedure} list-cdr-set! list k val
401 @deffnx {C Function} scm_list_cdr_set_x (list, k, val)
402 Set the @var{k}th cdr of @var{list} to @var{val}.
405 @deffn {Scheme Procedure} delq item lst
406 @deffnx {C Function} scm_delq (item, lst)
407 Return a newly-created copy of @var{lst} with elements
408 @code{eq?} to @var{item} removed. This procedure mirrors
409 @code{memq}: @code{delq} compares elements of @var{lst} against
410 @var{item} with @code{eq?}.
413 @deffn {Scheme Procedure} delv item lst
414 @deffnx {C Function} scm_delv (item, lst)
415 Return a newly-created copy of @var{lst} with elements
416 @code{eqv?} to @var{item} removed. This procedure mirrors
417 @code{memv}: @code{delv} compares elements of @var{lst} against
418 @var{item} with @code{eqv?}.
421 @deffn {Scheme Procedure} delete item lst
422 @deffnx {C Function} scm_delete (item, lst)
423 Return a newly-created copy of @var{lst} with elements
424 @code{equal?} to @var{item} removed. This procedure mirrors
425 @code{member}: @code{delete} compares elements of @var{lst}
426 against @var{item} with @code{equal?}.
429 @deffn {Scheme Procedure} delq! item lst
430 @deffnx {Scheme Procedure} delv! item lst
431 @deffnx {Scheme Procedure} delete! item lst
432 @deffnx {C Function} scm_delq_x (item, lst)
433 @deffnx {C Function} scm_delv_x (item, lst)
434 @deffnx {C Function} scm_delete_x (item, lst)
435 These procedures are destructive versions of @code{delq}, @code{delv}
436 and @code{delete}: they modify the pointers in the existing @var{lst}
437 rather than creating a new list. Caveat evaluator: Like other
438 destructive list functions, these functions cannot modify the binding of
439 @var{lst}, and so cannot be used to delete the first element of
440 @var{lst} destructively.
443 @deffn {Scheme Procedure} delq1! item lst
444 @deffnx {C Function} scm_delq1_x (item, lst)
445 Like @code{delq!}, but only deletes the first occurrence of
446 @var{item} from @var{lst}. Tests for equality using
447 @code{eq?}. See also @code{delv1!} and @code{delete1!}.
450 @deffn {Scheme Procedure} delv1! item lst
451 @deffnx {C Function} scm_delv1_x (item, lst)
452 Like @code{delv!}, but only deletes the first occurrence of
453 @var{item} from @var{lst}. Tests for equality using
454 @code{eqv?}. See also @code{delq1!} and @code{delete1!}.
457 @deffn {Scheme Procedure} delete1! item lst
458 @deffnx {C Function} scm_delete1_x (item, lst)
459 Like @code{delete!}, but only deletes the first occurrence of
460 @var{item} from @var{lst}. Tests for equality using
461 @code{equal?}. See also @code{delq1!} and @code{delv1!}.
465 @subsection List Searching
467 The following procedures search lists for particular elements. They use
468 different comparison predicates for comparing list elements with the
469 object to be searched. When they fail, they return @code{#f}, otherwise
470 they return the sublist whose car is equal to the search object, where
471 equality depends on the equality predicate used.
474 @deffn {Scheme Procedure} memq x lst
475 @deffnx {C Function} scm_memq (x, lst)
476 Return the first sublist of @var{lst} whose car is @code{eq?}
477 to @var{x} where the sublists of @var{lst} are the non-empty
478 lists returned by @code{(list-tail @var{lst} @var{k})} for
479 @var{k} less than the length of @var{lst}. If @var{x} does not
480 occur in @var{lst}, then @code{#f} (not the empty list) is
485 @deffn {Scheme Procedure} memv x lst
486 @deffnx {C Function} scm_memv (x, lst)
487 Return the first sublist of @var{lst} whose car is @code{eqv?}
488 to @var{x} where the sublists of @var{lst} are the non-empty
489 lists returned by @code{(list-tail @var{lst} @var{k})} for
490 @var{k} less than the length of @var{lst}. If @var{x} does not
491 occur in @var{lst}, then @code{#f} (not the empty list) is
496 @deffn {Scheme Procedure} member x lst
497 @deffnx {C Function} scm_member (x, lst)
498 Return the first sublist of @var{lst} whose car is
499 @code{equal?} to @var{x} where the sublists of @var{lst} are
500 the non-empty lists returned by @code{(list-tail @var{lst}
501 @var{k})} for @var{k} less than the length of @var{lst}. If
502 @var{x} does not occur in @var{lst}, then @code{#f} (not the
503 empty list) is returned.
508 @subsection List Mapping
510 List processing is very convenient in Scheme because the process of
511 iterating over the elements of a list can be highly abstracted. The
512 procedures in this section are the most basic iterating procedures for
513 lists. They take a procedure and one or more lists as arguments, and
514 apply the procedure to each element of the list. They differ in their
518 @c begin (texi-doc-string "guile" "map")
519 @deffn {Scheme Procedure} map proc arg1 arg2 @dots{}
520 @deffnx {Scheme Procedure} map-in-order proc arg1 arg2 @dots{}
521 @deffnx {C Function} scm_map (proc, arg1, args)
522 Apply @var{proc} to each element of the list @var{arg1} (if only two
523 arguments are given), or to the corresponding elements of the argument
524 lists (if more than two arguments are given). The result(s) of the
525 procedure applications are saved and returned in a list. For
526 @code{map}, the order of procedure applications is not specified,
527 @code{map-in-order} applies the procedure from left to right to the list
532 @c begin (texi-doc-string "guile" "for-each")
533 @deffn {Scheme Procedure} for-each proc arg1 arg2 @dots{}
534 Like @code{map}, but the procedure is always applied from left to right,
535 and the result(s) of the procedure applications are thrown away. The
536 return value is not specified.
544 Vectors are sequences of Scheme objects. Unlike lists, the length of a
545 vector, once the vector is created, cannot be changed. The advantage of
546 vectors over lists is that the time required to access one element of a vector
547 given its @dfn{position} (synonymous with @dfn{index}), a zero-origin number,
548 is constant, whereas lists have an access time linear to the position of the
549 accessed element in the list.
551 Vectors can contain any kind of Scheme object; it is even possible to have
552 different types of objects in the same vector. For vectors containing
553 vectors, you may wish to use arrays, instead. Note, too, that some array
554 procedures operate happily on vectors (@pxref{Arrays}).
557 * Vector Syntax:: Read syntax for vectors.
558 * Vector Creation:: Dynamic vector creation and validation.
559 * Vector Accessors:: Accessing and modifying vector contents.
564 @subsection Read Syntax for Vectors
566 Vectors can literally be entered in source code, just like strings,
567 characters or some of the other data types. The read syntax for vectors
568 is as follows: A sharp sign (@code{#}), followed by an opening
569 parentheses, all elements of the vector in their respective read syntax,
570 and finally a closing parentheses. The following are examples of the
571 read syntax for vectors; where the first vector only contains numbers
572 and the second three different object types: a string, a symbol and a
573 number in hexadecimal notation.
577 #("Hello" foo #xdeadbeef)
580 Like lists, vectors have to be quoted (REFFIXME):
583 '#(a b c) @result{} #(a b c)
586 @node Vector Creation
587 @subsection Dynamic Vector Creation and Validation
589 Instead of creating a vector implicitly by using the read syntax just
590 described, you can create a vector dynamically by calling one of the
591 @code{vector} and @code{list->vector} primitives with the list of Scheme
592 values that you want to place into a vector. The size of the vector
593 thus created is determined implicitly by the number of arguments given.
596 @rnindex list->vector
597 @deffn {Scheme Procedure} vector . l
598 @deffnx {Scheme Procedure} list->vector l
599 @deffnx {C Function} scm_vector (l)
600 Return a newly allocated vector composed of the
601 given arguments. Analogous to @code{list}.
604 (vector 'a 'b 'c) @result{} #(a b c)
608 (As an aside, an interesting implementation detail is that the Guile
609 reader reads the @code{#(@dots{})} syntax by reading everything but the
610 initial @code{#} as a @emph{list}, and then passing the list that
611 results to @code{list->vector}. Notice how neatly this fits with the
612 similarity between the read (and print) syntaxes for lists and vectors.)
614 The inverse operation is @code{vector->list}:
616 @rnindex vector->list
617 @deffn {Scheme Procedure} vector->list v
618 @deffnx {C Function} scm_vector_to_list (v)
619 Return a newly allocated list composed of the elements of @var{v}.
622 (vector->list '#(dah dah didah)) @result{} (dah dah didah)
623 (list->vector '(dididit dah)) @result{} #(dididit dah)
627 To allocate a vector with an explicitly specified size, use
628 @code{make-vector}. With this primitive you can also specify an initial
629 value for the vector elements (the same value for all elements, that
633 @deffn {Scheme Procedure} make-vector k [fill]
634 @deffnx {C Function} scm_make_vector (k, fill)
635 Return a newly allocated vector of @var{k} elements. If a
636 second argument is given, then each position is initialized to
637 @var{fill}. Otherwise the initial contents of each position is
641 To check whether an arbitrary Scheme value @emph{is} a vector, use the
642 @code{vector?} primitive:
645 @deffn {Scheme Procedure} vector? obj
646 @deffnx {C Function} scm_vector_p (obj)
647 Return @code{#t} if @var{obj} is a vector, otherwise return
652 @node Vector Accessors
653 @subsection Accessing and Modifying Vector Contents
655 @code{vector-length} and @code{vector-ref} return information about a
656 given vector, respectively its size and the elements that are contained
659 @rnindex vector-length
660 @deffn {Scheme Procedure} vector-length vector
661 @deffnx {C Function} scm_vector_length vector
662 Return the number of elements in @var{vector} as an exact integer.
666 @deffn {Scheme Procedure} vector-ref vector k
667 @deffnx {C Function} scm_vector_ref vector k
668 Return the contents of position @var{k} of @var{vector}.
669 @var{k} must be a valid index of @var{vector}.
671 (vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
672 (vector-ref '#(1 1 2 3 5 8 13 21)
673 (let ((i (round (* 2 (acos -1)))))
680 A vector created by one of the dynamic vector constructor procedures
681 (@pxref{Vector Creation}) can be modified using the following
684 @emph{NOTE:} According to R5RS, it is an error to use any of these
685 procedures on a literally read vector, because such vectors should be
686 considered as constants. Currently, however, Guile does not detect this
690 @deffn {Scheme Procedure} vector-set! vector k obj
691 @deffnx {C Function} scm_vector_set_x vector k obj
692 Store @var{obj} in position @var{k} of @var{vector}.
693 @var{k} must be a valid index of @var{vector}.
694 The value returned by @samp{vector-set!} is unspecified.
696 (let ((vec (vector 0 '(2 2 2 2) "Anna")))
697 (vector-set! vec 1 '("Sue" "Sue"))
698 vec) @result{} #(0 ("Sue" "Sue") "Anna")
702 @rnindex vector-fill!
703 @deffn {Scheme Procedure} vector-fill! v fill
704 @deffnx {C Function} scm_vector_fill_x (v, fill)
705 Store @var{fill} in every position of @var{vector}. The value
706 returned by @code{vector-fill!} is unspecified.
709 @deffn {Scheme Procedure} vector-move-left! vec1 start1 end1 vec2 start2
710 @deffnx {C Function} scm_vector_move_left_x (vec1, start1, end1, vec2, start2)
711 Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
712 to @var{vec2} starting at position @var{start2}. @var{start1} and
713 @var{start2} are inclusive indices; @var{end1} is exclusive.
715 @code{vector-move-left!} copies elements in leftmost order.
716 Therefore, in the case where @var{vec1} and @var{vec2} refer to the
717 same vector, @code{vector-move-left!} is usually appropriate when
718 @var{start1} is greater than @var{start2}.
721 @deffn {Scheme Procedure} vector-move-right! vec1 start1 end1 vec2 start2
722 @deffnx {C Function} scm_vector_move_right_x (vec1, start1, end1, vec2, start2)
723 Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
724 to @var{vec2} starting at position @var{start2}. @var{start1} and
725 @var{start2} are inclusive indices; @var{end1} is exclusive.
727 @code{vector-move-right!} copies elements in rightmost order.
728 Therefore, in the case where @var{vec1} and @var{vec2} refer to the
729 same vector, @code{vector-move-right!} is usually appropriate when
730 @var{start1} is less than @var{start2}.
737 A @dfn{record type} is a first class object representing a user-defined
738 data type. A @dfn{record} is an instance of a record type.
740 @deffn {Scheme Procedure} record? obj
741 Return @code{#t} if @var{obj} is a record of any type and @code{#f}
744 Note that @code{record?} may be true of any Scheme value; there is no
745 promise that records are disjoint with other Scheme types.
748 @deffn {Scheme Procedure} make-record-type type-name field-names
749 Return a @dfn{record-type descriptor}, a value representing a new data
750 type disjoint from all others. The @var{type-name} argument must be a
751 string, but is only used for debugging purposes (such as the printed
752 representation of a record of the new type). The @var{field-names}
753 argument is a list of symbols naming the @dfn{fields} of a record of the
754 new type. It is an error if the list contains any duplicates. It is
755 unspecified how record-type descriptors are represented.
758 @deffn {Scheme Procedure} record-constructor rtd [field-names]
759 Return a procedure for constructing new members of the type represented
760 by @var{rtd}. The returned procedure accepts exactly as many arguments
761 as there are symbols in the given list, @var{field-names}; these are
762 used, in order, as the initial values of those fields in a new record,
763 which is returned by the constructor procedure. The values of any
764 fields not named in that list are unspecified. The @var{field-names}
765 argument defaults to the list of field names in the call to
766 @code{make-record-type} that created the type represented by @var{rtd};
767 if the @var{field-names} argument is provided, it is an error if it
768 contains any duplicates or any symbols not in the default list.
771 @deffn {Scheme Procedure} record-predicate rtd
772 Return a procedure for testing membership in the type represented by
773 @var{rtd}. The returned procedure accepts exactly one argument and
774 returns a true value if the argument is a member of the indicated record
775 type; it returns a false value otherwise.
778 @deffn {Scheme Procedure} record-accessor rtd field-name
779 Return a procedure for reading the value of a particular field of a
780 member of the type represented by @var{rtd}. The returned procedure
781 accepts exactly one argument which must be a record of the appropriate
782 type; it returns the current value of the field named by the symbol
783 @var{field-name} in that record. The symbol @var{field-name} must be a
784 member of the list of field-names in the call to @code{make-record-type}
785 that created the type represented by @var{rtd}.
788 @deffn {Scheme Procedure} record-modifier rtd field-name
789 Return a procedure for writing the value of a particular field of a
790 member of the type represented by @var{rtd}. The returned procedure
791 accepts exactly two arguments: first, a record of the appropriate type,
792 and second, an arbitrary Scheme value; it modifies the field named by
793 the symbol @var{field-name} in that record to contain the given value.
794 The returned value of the modifier procedure is unspecified. The symbol
795 @var{field-name} must be a member of the list of field-names in the call
796 to @code{make-record-type} that created the type represented by
800 @deffn {Scheme Procedure} record-type-descriptor record
801 Return a record-type descriptor representing the type of the given
802 record. That is, for example, if the returned descriptor were passed to
803 @code{record-predicate}, the resulting predicate would return a true
804 value when passed the given record. Note that it is not necessarily the
805 case that the returned descriptor is the one that was passed to
806 @code{record-constructor} in the call that created the constructor
807 procedure that created the given record.
810 @deffn {Scheme Procedure} record-type-name rtd
811 Return the type-name associated with the type represented by rtd. The
812 returned value is @code{eqv?} to the @var{type-name} argument given in
813 the call to @code{make-record-type} that created the type represented by
817 @deffn {Scheme Procedure} record-type-fields rtd
818 Return a list of the symbols naming the fields in members of the type
819 represented by @var{rtd}. The returned value is @code{equal?} to the
820 field-names argument given in the call to @code{make-record-type} that
821 created the type represented by @var{rtd}.
829 [FIXME: this is pasted in from Tom Lord's original guile.texi and should
832 A @dfn{structure type} is a first class user-defined data type. A
833 @dfn{structure} is an instance of a structure type. A structure type is
836 Structures are less abstract and more general than traditional records.
837 In fact, in Guile Scheme, records are implemented using structures.
840 * Structure Concepts:: The structure of Structures
841 * Structure Layout:: Defining the layout of structure types
842 * Structure Basics:: make-, -ref and -set! procedures for structs
843 * Vtables:: Accessing type-specific data
846 @node Structure Concepts
847 @subsection Structure Concepts
849 A structure object consists of a handle, structure data, and a vtable.
850 The handle is a Scheme value which points to both the vtable and the
851 structure's data. Structure data is a dynamically allocated region of
852 memory, private to the structure, divided up into typed fields. A
853 vtable is another structure used to hold type-specific data. Multiple
854 structures can share a common vtable.
856 Three concepts are key to understanding structures.
859 @item @dfn{layout specifications}
861 Layout specifications determine how memory allocated to structures is
862 divided up into fields. Programmers must write a layout specification
863 whenever a new type of structure is defined.
865 @item @dfn{structural accessors}
867 Structure access is by field number. There is only one set of
868 accessors common to all structure objects.
872 Vtables, themselves structures, are first class representations of
873 disjoint sub-types of structures in general. In most cases, when a
874 new structure is created, programmers must specify a vtable for the
875 new structure. Each vtable has a field describing the layout of its
876 instances. Vtables can have additional, user-defined fields as well.
881 @node Structure Layout
882 @subsection Structure Layout
884 When a structure is created, a region of memory is allocated to hold its
885 state. The @dfn{layout} of the structure's type determines how that
886 memory is divided into fields.
888 Each field has a specified type. There are only three types allowed, each
889 corresponding to a one letter code. The allowed types are:
892 @item 'u' -- unprotected
894 The field holds binary data that is not GC protected.
896 @item 'p' -- protected
898 The field holds a Scheme value and is GC protected.
902 The field holds a Scheme value and is GC protected. When a structure is
903 created with this type of field, the field is initialized to refer to
904 the structure's own handle. This kind of field is mainly useful when
905 mixing Scheme and C code in which the C code may need to compute a
906 structure's handle given only the address of its malloc'd data.
910 Each field also has an associated access protection. There are only
911 three kinds of protection, each corresponding to a one letter code.
912 The allowed protections are:
915 @item 'w' -- writable
917 The field can be read and written.
919 @item 'r' -- readable
921 The field can be read, but not written.
925 The field can be neither read nor written. This kind
926 of protection is for fields useful only to built-in routines.
929 A layout specification is described by stringing together pairs
930 of letters: one to specify a field type and one to specify a field
931 protection. For example, a traditional cons pair type object could
935 ; cons pairs have two writable fields of Scheme data
939 A pair object in which the first field is held constant could be:
945 Binary fields, (fields of type "u"), hold one @dfn{word} each. The
946 size of a word is a machine dependent value defined to be equal to the
947 value of the C expression: @code{sizeof (long)}.
949 The last field of a structure layout may specify a tail array.
950 A tail array is indicated by capitalizing the field's protection
951 code ('W', 'R' or 'O'). A tail-array field is replaced by
952 a read-only binary data field containing an array size. The array
953 size is determined at the time the structure is created. It is followed
954 by a corresponding number of fields of the type specified for the
955 tail array. For example, a conventional Scheme vector can be
959 ; A vector is an arbitrary number of writable fields holding Scheme
964 In the above example, field 0 contains the size of the vector and
965 fields beginning at 1 contain the vector elements.
967 A kind of tagged vector (a constant tag followed by conventional
968 vector elements) might be:
975 Structure layouts are represented by specially interned symbols whose
976 name is a string of type and protection codes. To create a new
977 structure layout, use this procedure:
979 @deffn {Scheme Procedure} make-struct-layout fields
980 @deffnx {C Function} scm_make_struct_layout (fields)
981 Return a new structure layout object.
983 @var{fields} must be a string made up of pairs of characters
984 strung together. The first character of each pair describes a field
985 type, the second a field protection. Allowed types are 'p' for
986 GC-protected Scheme data, 'u' for unprotected binary data, and 's' for
987 a field that points to the structure itself. Allowed protections
988 are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque
989 fields. The last field protection specification may be capitalized to
990 indicate that the field is a tail-array.
995 @node Structure Basics
996 @subsection Structure Basics
998 This section describes the basic procedures for creating and accessing
1001 @deffn {Scheme Procedure} make-struct vtable tail_array_size . init
1002 @deffnx {C Function} scm_make_struct (vtable, tail_array_size, init)
1003 Create a new structure.
1005 @var{type} must be a vtable structure (@pxref{Vtables}).
1007 @var{tail-elts} must be a non-negative integer. If the layout
1008 specification indicated by @var{type} includes a tail-array,
1009 this is the number of elements allocated to that array.
1011 The @var{init1}, @dots{} are optional arguments describing how
1012 successive fields of the structure should be initialized. Only fields
1013 with protection 'r' or 'w' can be initialized, except for fields of
1014 type 's', which are automatically initialized to point to the new
1015 structure itself; fields with protection 'o' can not be initialized by
1018 If fewer optional arguments than initializable fields are supplied,
1019 fields of type 'p' get default value #f while fields of type 'u' are
1022 Structs are currently the basic representation for record-like data
1023 structures in Guile. The plan is to eventually replace them with a
1024 new representation which will at the same time be easier to use and
1027 For more information, see the documentation for @code{make-vtable-vtable}.
1030 @deffn {Scheme Procedure} struct? x
1031 @deffnx {C Function} scm_struct_p (x)
1032 Return @code{#t} iff @var{x} is a structure object, else
1037 @deffn {Scheme Procedure} struct-ref handle pos
1038 @deffnx {Scheme Procedure} struct-set! struct n value
1039 @deffnx {C Function} scm_struct_ref (handle, pos)
1040 @deffnx {C Function} scm_struct_set_x (struct, n, value)
1041 Access (or modify) the @var{n}th field of @var{struct}.
1043 If the field is of type 'p', then it can be set to an arbitrary value.
1045 If the field is of type 'u', then it can only be set to a non-negative
1046 integer value small enough to fit in one machine word.
1054 Vtables are structures that are used to represent structure types. Each
1055 vtable contains a layout specification in field
1056 @code{vtable-index-layout} -- instances of the type are laid out
1057 according to that specification. Vtables contain additional fields
1058 which are used only internally to libguile. The variable
1059 @code{vtable-offset-user} is bound to a field number. Vtable fields
1060 at that position or greater are user definable.
1062 @deffn {Scheme Procedure} struct-vtable handle
1063 @deffnx {C Function} scm_struct_vtable (handle)
1064 Return the vtable structure that describes the type of @var{struct}.
1067 @deffn {Scheme Procedure} struct-vtable? x
1068 @deffnx {C Function} scm_struct_vtable_p (x)
1069 Return @code{#t} iff @var{x} is a vtable structure.
1072 If you have a vtable structure, @code{V}, you can create an instance of
1073 the type it describes by using @code{(make-struct V ...)}. But where
1074 does @code{V} itself come from? One possibility is that @code{V} is an
1075 instance of a user-defined vtable type, @code{V'}, so that @code{V} is
1076 created by using @code{(make-struct V' ...)}. Another possibility is
1077 that @code{V} is an instance of the type it itself describes. Vtable
1078 structures of the second sort are created by this procedure:
1080 @deffn {Scheme Procedure} make-vtable-vtable user_fields tail_array_size . init
1081 @deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_array_size, init)
1082 Return a new, self-describing vtable structure.
1084 @var{user-fields} is a string describing user defined fields of the
1085 vtable beginning at index @code{vtable-offset-user}
1086 (see @code{make-struct-layout}).
1088 @var{tail-size} specifies the size of the tail-array (if any) of
1091 @var{init1}, @dots{} are the optional initializers for the fields of
1094 Vtables have one initializable system field---the struct printer.
1095 This field comes before the user fields in the initializers passed
1096 to @code{make-vtable-vtable} and @code{make-struct}, and thus works as
1097 a third optional argument to @code{make-vtable-vtable} and a fourth to
1098 @code{make-struct} when creating vtables:
1100 If the value is a procedure, it will be called instead of the standard
1101 printer whenever a struct described by this vtable is printed.
1102 The procedure will be called with arguments STRUCT and PORT.
1104 The structure of a struct is described by a vtable, so the vtable is
1105 in essence the type of the struct. The vtable is itself a struct with
1106 a vtable. This could go on forever if it weren't for the
1107 vtable-vtables which are self-describing vtables, and thus terminate
1110 There are several potential ways of using structs, but the standard
1111 one is to use three kinds of structs, together building up a type
1112 sub-system: one vtable-vtable working as the root and one or several
1113 "types", each with a set of "instances". (The vtable-vtable should be
1114 compared to the class <class> which is the class of itself.)
1117 (define ball-root (make-vtable-vtable "pr" 0))
1119 (define (make-ball-type ball-color)
1120 (make-struct ball-root 0
1121 (make-struct-layout "pw")
1123 (format port "#<a ~A ball owned by ~A>"
1127 (define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
1128 (define (owner ball) (struct-ref ball 0))
1130 (define red (make-ball-type 'red))
1131 (define green (make-ball-type 'green))
1133 (define (make-ball type owner) (make-struct type 0 owner))
1135 (define ball (make-ball green 'Nisse))
1136 ball @result{} #<a green ball owned by Nisse>
1140 @deffn {Scheme Procedure} struct-vtable-name vtable
1141 @deffnx {C Function} scm_struct_vtable_name (vtable)
1142 Return the name of the vtable @var{vtable}.
1145 @deffn {Scheme Procedure} set-struct-vtable-name! vtable name
1146 @deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name)
1147 Set the name of the vtable @var{vtable} to @var{name}.
1150 @deffn {Scheme Procedure} struct-vtable-tag handle
1151 @deffnx {C Function} scm_struct_vtable_tag (handle)
1152 Return the vtable tag of the structure @var{handle}.
1161 * Conventional Arrays:: Arrays with arbitrary data.
1162 * Array Mapping:: Applying a procedure to the contents of an array.
1163 * Uniform Arrays:: Arrays with data of a single type.
1164 * Bit Vectors:: Vectors of bits.
1167 @node Conventional Arrays
1168 @subsection Conventional Arrays
1170 @dfn{Conventional arrays} are a collection of cells organized into an
1171 arbitrary number of dimensions. Each cell can hold any kind of Scheme
1172 value and can be accessed in constant time by supplying an index for
1173 each dimension. This contrasts with uniform arrays, which use memory
1174 more efficiently but can hold data of only a single type, and lists
1175 where inserting and deleting cells is more efficient, but more time
1176 is usually required to access a particular cell.
1178 A conventional array is displayed as @code{#} followed by the @dfn{rank}
1179 (number of dimensions) followed by the cells, organized into dimensions
1180 using parentheses. The nesting depth of the parentheses is equal to
1183 When an array is created, the number of dimensions and range of each
1184 dimension must be specified, e.g., to create a 2x3 array with a
1188 (make-array 'ho 2 3) @result{}
1189 #2((ho ho ho) (ho ho ho))
1192 The range of each dimension can also be given explicitly, e.g., another
1193 way to create the same array:
1196 (make-array 'ho '(0 1) '(0 2)) @result{}
1197 #2((ho ho ho) (ho ho ho))
1200 A conventional array with one dimension based at zero is identical to
1204 (make-array 'ho 3) @result{}
1208 The following procedures can be used with conventional arrays (or vectors).
1210 @deffn {Scheme Procedure} array? v [prot]
1211 @deffnx {C Function} scm_array_p (v, prot)
1212 Return @code{#t} if the @var{obj} is an array, and @code{#f} if
1213 not. The @var{prototype} argument is used with uniform arrays
1214 and is described elsewhere.
1217 @deffn {Scheme Procedure} make-array initial-value bound1 bound2 @dots{}
1218 Create and return an array that has as many dimensions as there are
1219 @var{bound}s and fill it with @var{initial-value}. Each @var{bound}
1220 may be a positive non-zero integer @var{N}, in which case the index for
1221 that dimension can range from 0 through @var{N-1}; or an explicit index
1222 range specifier in the form @code{(LOWER UPPER)}, where both @var{lower}
1223 and @var{upper} are integers, possibly less than zero, and possibly the
1224 same number (however, @var{lower} cannot be greater than @var{upper}).
1227 @c array-ref's type is `compiled-closure'. There's some weird stuff
1228 @c going on in array.c, too. Let's call it a primitive. -twp
1230 @deffn {Scheme Procedure} uniform-vector-ref v args
1231 @deffnx {Scheme Procedure} array-ref v . args
1232 @deffnx {C Function} scm_uniform_vector_ref (v, args)
1233 Return the element at the @code{(index1, index2)} element in
1237 @deffn {Scheme Procedure} array-in-bounds? v . args
1238 @deffnx {C Function} scm_array_in_bounds_p (v, args)
1239 Return @code{#t} if its arguments would be acceptable to
1243 @c fixme: why do these sigs differ? -ttn 2001/07/19 01:14:12
1244 @deffn {Scheme Procedure} array-set! v obj . args
1245 @deffnx {Scheme Procedure} uniform-array-set1! v obj args
1246 @deffnx {C Function} scm_array_set_x (v, obj, args)
1247 Set the element at the @code{(index1, index2)} element in @var{array} to
1248 @var{new-value}. The value returned by array-set! is unspecified.
1251 @deffn {Scheme Procedure} make-shared-array oldra mapfunc . dims
1252 @deffnx {C Function} scm_make_shared_array (oldra, mapfunc, dims)
1253 @code{make-shared-array} can be used to create shared subarrays of other
1254 arrays. The @var{mapper} is a function that translates coordinates in
1255 the new array into coordinates in the old array. A @var{mapper} must be
1256 linear, and its range must stay within the bounds of the old array, but
1257 it can be otherwise arbitrary. A simple example:
1259 (define fred (make-array #f 8 8))
1260 (define freds-diagonal
1261 (make-shared-array fred (lambda (i) (list i i)) 8))
1262 (array-set! freds-diagonal 'foo 3)
1263 (array-ref fred 3 3) @result{} foo
1264 (define freds-center
1265 (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
1266 (array-ref freds-center 0 0) @result{} foo
1270 @deffn {Scheme Procedure} shared-array-increments ra
1271 @deffnx {C Function} scm_shared_array_increments (ra)
1272 For each dimension, return the distance between elements in the root vector.
1275 @deffn {Scheme Procedure} shared-array-offset ra
1276 @deffnx {C Function} scm_shared_array_offset (ra)
1277 Return the root vector index of the first element in the array.
1280 @deffn {Scheme Procedure} shared-array-root ra
1281 @deffnx {C Function} scm_shared_array_root (ra)
1282 Return the root vector of a shared array.
1285 @deffn {Scheme Procedure} transpose-array ra . args
1286 @deffnx {C Function} scm_transpose_array (ra, args)
1287 Return an array sharing contents with @var{array}, but with
1288 dimensions arranged in a different order. There must be one
1289 @var{dim} argument for each dimension of @var{array}.
1290 @var{dim0}, @var{dim1}, @dots{} should be integers between 0
1291 and the rank of the array to be returned. Each integer in that
1292 range must appear at least once in the argument list.
1294 The values of @var{dim0}, @var{dim1}, @dots{} correspond to
1295 dimensions in the array to be returned, their positions in the
1296 argument list to dimensions of @var{array}. Several @var{dim}s
1297 may have the same value, in which case the returned array will
1298 have smaller rank than @var{array}.
1301 (transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
1302 (transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
1303 (transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
1304 #2((a 4) (b 5) (c 6))
1308 @deffn {Scheme Procedure} enclose-array ra . axes
1309 @deffnx {C Function} scm_enclose_array (ra, axes)
1310 @var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than
1311 the rank of @var{array}. @var{enclose-array} returns an array
1312 resembling an array of shared arrays. The dimensions of each shared
1313 array are the same as the @var{dim}th dimensions of the original array,
1314 the dimensions of the outer array are the same as those of the original
1315 array that did not match a @var{dim}.
1317 An enclosed array is not a general Scheme array. Its elements may not
1318 be set using @code{array-set!}. Two references to the same element of
1319 an enclosed array will be @code{equal?} but will not in general be
1320 @code{eq?}. The value returned by @var{array-prototype} when given an
1321 enclosed array is unspecified.
1325 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
1326 #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
1328 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
1329 #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
1333 @deffn {Scheme Procedure} array-shape array
1334 Return a list of inclusive bounds of integers.
1336 (array-shape (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) (0 4))
1340 @deffn {Scheme Procedure} array-dimensions ra
1341 @deffnx {C Function} scm_array_dimensions (ra)
1342 @code{Array-dimensions} is similar to @code{array-shape} but replaces
1343 elements with a @code{0} minimum with one greater than the maximum. So:
1345 (array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
1349 @deffn {Scheme Procedure} array-rank ra
1350 @deffnx {C Function} scm_array_rank (ra)
1351 Return the number of dimensions of @var{obj}. If @var{obj} is
1352 not an array, @code{0} is returned.
1355 @deffn {Scheme Procedure} array->list v
1356 @deffnx {C Function} scm_array_to_list (v)
1357 Return a list consisting of all the elements, in order, of
1361 @deffn {Scheme Procedure} array-copy! src dst
1362 @deffnx {Scheme Procedure} array-copy-in-order! src dst
1363 @deffnx {C Function} scm_array_copy_x (src, dst)
1364 Copy every element from vector or array @var{source} to the
1365 corresponding element of @var{destination}. @var{destination} must have
1366 the same rank as @var{source}, and be at least as large in each
1367 dimension. The order is unspecified.
1370 @deffn {Scheme Procedure} array-fill! ra fill
1371 @deffnx {C Function} scm_array_fill_x (ra, fill)
1372 Store @var{fill} in every element of @var{array}. The value returned
1376 @c begin (texi-doc-string "guile" "array-equal?")
1377 @deffn {Scheme Procedure} array-equal? ra0 ra1
1378 Return @code{#t} iff all arguments are arrays with the same shape, the
1379 same type, and have corresponding elements which are either
1380 @code{equal?} or @code{array-equal?}. This function differs from
1381 @code{equal?} in that a one dimensional shared array may be
1382 @var{array-equal?} but not @var{equal?} to a vector or uniform vector.
1385 @deffn {Scheme Procedure} array-contents array [strict]
1386 @deffnx {C Function} scm_array_contents (array, strict)
1387 If @var{array} may be @dfn{unrolled} into a one dimensional shared array
1388 without changing their order (last subscript changing fastest), then
1389 @code{array-contents} returns that shared array, otherwise it returns
1390 @code{#f}. All arrays made by @var{make-array} and
1391 @var{make-uniform-array} may be unrolled, some arrays made by
1392 @var{make-shared-array} may not be.
1394 If the optional argument @var{strict} is provided, a shared array will
1395 be returned only if its elements are stored internally contiguous in
1400 @subsection Array Mapping
1402 @c FIXME: array-map! accepts no source arrays at all, and in that
1403 @c case makes calls "(proc)". Is that meant to be a documented
1406 @c FIXME: array-for-each doesn't say what happens if the sources have
1407 @c different index ranges. The code currently iterates over the
1408 @c indices of the first and expects the others to cover those. That
1409 @c at least vaguely matches array-map!, but is is meant to be a
1410 @c documented feature?
1412 @deffn {Scheme Procedure} array-map! dst proc src1 @dots{} srcN
1413 @deffnx {Scheme Procedure} array-map-in-order! dst proc src1 @dots{} srcN
1414 @deffnx {C Function} scm_array_map_x (dst, proc, srclist)
1415 Set each element of the @var{dst} array to values obtained from calls
1416 to @var{proc}. The value returned is unspecified.
1418 Each call is @code{(@var{proc} @var{elem1} @dots{} @var{elemN})},
1419 where each @var{elem} is from the corresponding @var{src} array, at
1420 the @var{dst} index. @code{array-map-in-order!} makes the calls in
1421 row-major order, @code{array-map!} makes them in an unspecified order.
1423 The @var{src} arrays must have the same number of dimensions as
1424 @var{dst}, and must have a range for each dimension which covers the
1425 range in @var{dst}. This ensures all @var{dst} indices are valid in
1429 @deffn {Scheme Procedure} array-for-each proc src1 @dots{} srcN
1430 @deffnx {C Function} scm_array_for_each (proc, src1, srclist)
1431 Apply @var{proc} to each tuple of elements of @var{src1} @dots{}
1432 @var{srcN}, in row-major order. The value returned is unspecified.
1435 @deffn {Scheme Procedure} array-index-map! dst proc
1436 @deffnx {C Function} scm_array_index_map_x (dst, proc)
1437 Set each element of the @var{dst} array to values returned by calls to
1438 @var{proc}. The value returned is unspecified.
1440 Each call is @code{(@var{proc} @var{i1} @dots{} @var{iN})}, where
1441 @var{i1}@dots{}@var{iN} is the destination index, one parameter for
1442 each dimension. The order in which the calls are made is unspecified.
1444 For example, to create a @m{4\times4, 4x4} matrix representing a
1448 \advance\leftskip by 2\lispnarrowing {
1466 (define a (make-array #f 4 4))
1467 (array-index-map! a (lambda (i j)
1468 (modulo (+ i j) 4)))
1472 @node Uniform Arrays
1473 @subsection Uniform Arrays
1474 @tpindex Uniform Arrays
1477 @dfn{Uniform arrays} have elements all of the
1478 same type and occupy less storage than conventional
1479 arrays. Uniform arrays with a single zero-based dimension
1480 are also known as @dfn{uniform vectors}. The procedures in
1481 this section can also be used on conventional arrays, vectors,
1482 bit-vectors and strings.
1485 When creating a uniform array, the type of data to be stored
1486 is indicated with a @var{prototype} argument. The following table
1487 lists the types available and example prototypes:
1490 prototype type printing character
1492 #t boolean (bit-vector) b
1494 #\nul byte (integer) y
1495 's short (integer) h
1496 1 unsigned long (integer) u
1497 -1 signed long (integer) e
1498 'l signed long long (integer) l
1499 1.0 float (single precision) s
1500 1/3 double (double precision float) i
1501 0+i complex (double precision) c
1502 () conventional vector
1506 Unshared uniform arrays of characters with a single zero-based dimension
1507 are identical to strings:
1510 (make-uniform-array #\a 3) @result{}
1515 Unshared uniform arrays of booleans with a single zero-based dimension
1516 are identical to @ref{Bit Vectors, bit-vectors}.
1519 (make-uniform-array #t 3) @result{}
1524 Other uniform vectors are written in a form similar to that of vectors,
1525 except that a single character from the above table is put between
1526 @code{#} and @code{(}. For example, a uniform vector of signed
1527 long integers is displayed in the form @code{'#e(3 5 9)}.
1529 @deffn {Scheme Procedure} array? v [prot]
1530 Return @code{#t} if the @var{obj} is an array, and @code{#f} if not.
1532 The @var{prototype} argument is used with uniform arrays and is described
1536 @deffn {Scheme Procedure} make-uniform-array prototype bound1 bound2 @dots{}
1537 Create and return a uniform array of type corresponding to
1538 @var{prototype} that has as many dimensions as there are @var{bound}s
1539 and fill it with @var{prototype}.
1542 @deffn {Scheme Procedure} array-prototype ra
1543 @deffnx {C Function} scm_array_prototype (ra)
1544 Return an object that would produce an array of the same type
1545 as @var{array}, if used as the @var{prototype} for
1546 @code{make-uniform-array}.
1549 @deffn {Scheme Procedure} list->uniform-array ndim prot lst
1550 @deffnx {Scheme Procedure} list->uniform-vector prot lst
1551 @deffnx {C Function} scm_list_to_uniform_array (ndim, prot, lst)
1552 Return a uniform array of the type indicated by prototype
1553 @var{prot} with elements the same as those of @var{lst}.
1554 Elements must be of the appropriate type, no coercions are
1558 @deffn {Scheme Procedure} uniform-vector-fill! uve fill
1559 Store @var{fill} in every element of @var{uve}. The value returned is
1563 @deffn {Scheme Procedure} uniform-vector-length v
1564 @deffnx {C Function} scm_uniform_vector_length (v)
1565 Return the number of elements in @var{uve}.
1568 @deffn {Scheme Procedure} dimensions->uniform-array dims prot [fill]
1569 @deffnx {Scheme Procedure} make-uniform-vector length prototype [fill]
1570 @deffnx {C Function} scm_dimensions_to_uniform_array (dims, prot, fill)
1571 Create and return a uniform array or vector of type
1572 corresponding to @var{prototype} with dimensions @var{dims} or
1573 length @var{length}. If @var{fill} is supplied, it's used to
1574 fill the array, otherwise @var{prototype} is used.
1577 @c Another compiled-closure. -twp
1579 @deffn {Scheme Procedure} uniform-array-read! ra [port_or_fd [start [end]]]
1580 @deffnx {Scheme Procedure} uniform-vector-read! uve [port-or-fdes] [start] [end]
1581 @deffnx {C Function} scm_uniform_array_read_x (ra, port_or_fd, start, end)
1582 Attempt to read all elements of @var{ura}, in lexicographic order, as
1583 binary objects from @var{port-or-fdes}.
1584 If an end of file is encountered,
1585 the objects up to that point are put into @var{ura}
1586 (starting at the beginning) and the remainder of the array is
1589 The optional arguments @var{start} and @var{end} allow
1590 a specified region of a vector (or linearized array) to be read,
1591 leaving the remainder of the vector unchanged.
1593 @code{uniform-array-read!} returns the number of objects read.
1594 @var{port-or-fdes} may be omitted, in which case it defaults to the value
1595 returned by @code{(current-input-port)}.
1598 @deffn {Scheme Procedure} uniform-array-write v [port_or_fd [start [end]]]
1599 @deffnx {Scheme Procedure} uniform-vector-write uve [port-or-fdes] [start] [end]
1600 @deffnx {C Function} scm_uniform_array_write (v, port_or_fd, start, end)
1601 Writes all elements of @var{ura} as binary objects to
1604 The optional arguments @var{start}
1606 a specified region of a vector (or linearized array) to be written.
1608 The number of objects actually written is returned.
1609 @var{port-or-fdes} may be
1610 omitted, in which case it defaults to the value returned by
1611 @code{(current-output-port)}.
1615 @subsection Bit Vectors
1618 Bit vectors are a specific type of uniform array: an array of booleans
1619 with a single zero-based index.
1622 They are displayed as a sequence of @code{0}s and
1623 @code{1}s prefixed by @code{#*}, e.g.,
1626 (make-uniform-vector 8 #t #f) @result{}
1629 #b(#t #f #t) @result{}
1633 @deffn {Scheme Procedure} bit-count b bitvector
1634 @deffnx {C Function} scm_bit_count (b, bitvector)
1635 Return the number of occurrences of the boolean @var{b} in
1639 @deffn {Scheme Procedure} bit-position item v k
1640 @deffnx {C Function} scm_bit_position (item, v, k)
1641 Return the minimum index of an occurrence of @var{bool} in
1642 @var{bv} which is at least @var{k}. If no @var{bool} occurs
1643 within the specified range @code{#f} is returned.
1646 @deffn {Scheme Procedure} bit-invert! v
1647 @deffnx {C Function} scm_bit_invert_x (v)
1648 Modify @var{bv} by replacing each element with its negation.
1651 @deffn {Scheme Procedure} bit-set*! v kv obj
1652 @deffnx {C Function} scm_bit_set_star_x (v, kv, obj)
1653 If uve is a bit-vector @var{bv} and uve must be of the same
1654 length. If @var{bool} is @code{#t}, uve is OR'ed into
1655 @var{bv}; If @var{bool} is @code{#f}, the inversion of uve is
1656 AND'ed into @var{bv}.
1658 If uve is a unsigned long integer vector all the elements of uve
1659 must be between 0 and the @code{length} of @var{bv}. The bits
1660 of @var{bv} corresponding to the indexes in uve are set to
1661 @var{bool}. The return value is unspecified.
1664 @deffn {Scheme Procedure} bit-count* v kv obj
1665 @deffnx {C Function} scm_bit_count_star (v, kv, obj)
1668 (bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
1670 @var{bv} is not modified.
1674 @node Association Lists and Hash Tables
1675 @section Association Lists and Hash Tables
1677 This chapter discusses dictionary objects: data structures that are
1678 useful for organizing and indexing large bodies of information.
1681 * Dictionary Types:: About dictionary types; what they're good for.
1682 * Association Lists:: List-based dictionaries.
1683 * Hash Tables:: Table-based dictionaries.
1686 @node Dictionary Types
1687 @subsection Dictionary Types
1689 A @dfn{dictionary} object is a data structure used to index
1690 information in a user-defined way. In standard Scheme, the main
1691 aggregate data types are lists and vectors. Lists are not really
1692 indexed at all, and vectors are indexed only by number
1693 (e.g. @code{(vector-ref foo 5)}). Often you will find it useful
1694 to index your data on some other type; for example, in a library
1695 catalog you might want to look up a book by the name of its
1696 author. Dictionaries are used to help you organize information in
1699 An @dfn{association list} (or @dfn{alist} for short) is a list of
1700 key-value pairs. Each pair represents a single quantity or
1701 object; the @code{car} of the pair is a key which is used to
1702 identify the object, and the @code{cdr} is the object's value.
1704 A @dfn{hash table} also permits you to index objects with
1705 arbitrary keys, but in a way that makes looking up any one object
1706 extremely fast. A well-designed hash system makes hash table
1707 lookups almost as fast as conventional array or vector references.
1709 Alists are popular among Lisp programmers because they use only
1710 the language's primitive operations (lists, @dfn{car}, @dfn{cdr}
1711 and the equality primitives). No changes to the language core are
1712 necessary. Therefore, with Scheme's built-in list manipulation
1713 facilities, it is very convenient to handle data stored in an
1714 association list. Also, alists are highly portable and can be
1715 easily implemented on even the most minimal Lisp systems.
1717 However, alists are inefficient, especially for storing large
1718 quantities of data. Because we want Guile to be useful for large
1719 software systems as well as small ones, Guile provides a rich set
1720 of tools for using either association lists or hash tables.
1722 @node Association Lists
1723 @subsection Association Lists
1724 @tpindex Association Lists
1727 @cindex Association List
1731 An association list is a conventional data structure that is often used
1732 to implement simple key-value databases. It consists of a list of
1733 entries in which each entry is a pair. The @dfn{key} of each entry is
1734 the @code{car} of the pair and the @dfn{value} of each entry is the
1738 ASSOCIATION LIST ::= '( (KEY1 . VALUE1)
1746 Association lists are also known, for short, as @dfn{alists}.
1748 The structure of an association list is just one example of the infinite
1749 number of possible structures that can be built using pairs and lists.
1750 As such, the keys and values in an association list can be manipulated
1751 using the general list structure procedures @code{cons}, @code{car},
1752 @code{cdr}, @code{set-car!}, @code{set-cdr!} and so on. However,
1753 because association lists are so useful, Guile also provides specific
1754 procedures for manipulating them.
1757 * Alist Key Equality::
1758 * Adding or Setting Alist Entries::
1759 * Retrieving Alist Entries::
1760 * Removing Alist Entries::
1761 * Sloppy Alist Functions::
1765 @node Alist Key Equality
1766 @subsubsection Alist Key Equality
1768 All of Guile's dedicated association list procedures, apart from
1769 @code{acons}, come in three flavours, depending on the level of equality
1770 that is required to decide whether an existing key in the association
1771 list is the same as the key that the procedure call uses to identify the
1776 Procedures with @dfn{assq} in their name use @code{eq?} to determine key
1780 Procedures with @dfn{assv} in their name use @code{eqv?} to determine
1784 Procedures with @dfn{assoc} in their name use @code{equal?} to
1785 determine key equality.
1788 @code{acons} is an exception because it is used to build association
1789 lists which do not require their entries' keys to be unique.
1791 @node Adding or Setting Alist Entries
1792 @subsubsection Adding or Setting Alist Entries
1794 @code{acons} adds a new entry to an association list and returns the
1795 combined association list. The combined alist is formed by consing the
1796 new entry onto the head of the alist specified in the @code{acons}
1797 procedure call. So the specified alist is not modified, but its
1798 contents become shared with the tail of the combined alist that
1799 @code{acons} returns.
1801 In the most common usage of @code{acons}, a variable holding the
1802 original association list is updated with the combined alist:
1805 (set! address-list (acons name address address-list))
1808 In such cases, it doesn't matter that the old and new values of
1809 @code{address-list} share some of their contents, since the old value is
1810 usually no longer independently accessible.
1812 Note that @code{acons} adds the specified new entry regardless of
1813 whether the alist may already contain entries with keys that are, in
1814 some sense, the same as that of the new entry. Thus @code{acons} is
1815 ideal for building alists where there is no concept of key uniqueness.
1818 (set! task-list (acons 3 "pay gas bill" '()))
1821 ((3 . "pay gas bill"))
1823 (set! task-list (acons 3 "tidy bedroom" task-list))
1826 ((3 . "tidy bedroom") (3 . "pay gas bill"))
1829 @code{assq-set!}, @code{assv-set!} and @code{assoc-set!} are used to add
1830 or replace an entry in an association list where there @emph{is} a
1831 concept of key uniqueness. If the specified association list already
1832 contains an entry whose key is the same as that specified in the
1833 procedure call, the existing entry is replaced by the new one.
1834 Otherwise, the new entry is consed onto the head of the old association
1835 list to create the combined alist. In all cases, these procedures
1836 return the combined alist.
1838 @code{assq-set!} and friends @emph{may} destructively modify the
1839 structure of the old association list in such a way that an existing
1840 variable is correctly updated without having to @code{set!} it to the
1846 (("mary" . "34 Elm Road") ("james" . "16 Bow Street"))
1848 (assoc-set! address-list "james" "1a London Road")
1850 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
1854 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
1860 (assoc-set! address-list "bob" "11 Newington Avenue")
1862 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
1863 ("james" . "1a London Road"))
1867 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
1870 The only safe way to update an association list variable when adding or
1871 replacing an entry like this is to @code{set!} the variable to the
1876 (assoc-set! address-list "bob" "11 Newington Avenue"))
1879 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
1880 ("james" . "1a London Road"))
1883 Because of this slight inconvenience, you may find it more convenient to
1884 use hash tables to store dictionary data. If your application will not
1885 be modifying the contents of an alist very often, this may not make much
1888 If you need to keep the old value of an association list in a form
1889 independent from the list that results from modification by
1890 @code{acons}, @code{assq-set!}, @code{assv-set!} or @code{assoc-set!},
1891 use @code{list-copy} to copy the old association list before modifying
1894 @deffn {Scheme Procedure} acons key value alist
1895 @deffnx {C Function} scm_acons (key, value, alist)
1896 Add a new key-value pair to @var{alist}. A new pair is
1897 created whose car is @var{key} and whose cdr is @var{value}, and the
1898 pair is consed onto @var{alist}, and the new list is returned. This
1899 function is @emph{not} destructive; @var{alist} is not modified.
1902 @deffn {Scheme Procedure} assq-set! alist key val
1903 @deffnx {Scheme Procedure} assv-set! alist key value
1904 @deffnx {Scheme Procedure} assoc-set! alist key value
1905 @deffnx {C Function} scm_assq_set_x (alist, key, val)
1906 @deffnx {C Function} scm_assv_set_x (alist, key, val)
1907 @deffnx {C Function} scm_assoc_set_x (alist, key, val)
1908 Reassociate @var{key} in @var{alist} with @var{value}: find any existing
1909 @var{alist} entry for @var{key} and associate it with the new
1910 @var{value}. If @var{alist} does not contain an entry for @var{key},
1911 add a new one. Return the (possibly new) alist.
1913 These functions do not attempt to verify the structure of @var{alist},
1914 and so may cause unusual results if passed an object that is not an
1918 @node Retrieving Alist Entries
1919 @subsubsection Retrieving Alist Entries
1924 @code{assq}, @code{assv} and @code{assoc} take an alist and a key as
1925 arguments and return the entry for that key if an entry exists, or
1926 @code{#f} if there is no entry for that key. Note that, in the cases
1927 where an entry exists, these procedures return the complete entry, that
1928 is @code{(KEY . VALUE)}, not just the value.
1930 @deffn {Scheme Procedure} assq key alist
1931 @deffnx {Scheme Procedure} assv key alist
1932 @deffnx {Scheme Procedure} assoc key alist
1933 @deffnx {C Function} scm_assq (key, alist)
1934 @deffnx {C Function} scm_assv (key, alist)
1935 @deffnx {C Function} scm_assoc (key, alist)
1936 Fetch the entry in @var{alist} that is associated with @var{key}. To
1937 decide whether the argument @var{key} matches a particular entry in
1938 @var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}
1939 uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}
1940 cannot be found in @var{alist} (according to whichever equality
1941 predicate is in use), then return @code{#f}. These functions
1942 return the entire alist entry found (i.e. both the key and the value).
1945 @code{assq-ref}, @code{assv-ref} and @code{assoc-ref}, on the other
1946 hand, take an alist and a key and return @emph{just the value} for that
1947 key, if an entry exists. If there is no entry for the specified key,
1948 these procedures return @code{#f}.
1950 This creates an ambiguity: if the return value is @code{#f}, it means
1951 either that there is no entry with the specified key, or that there
1952 @emph{is} an entry for the specified key, with value @code{#f}.
1953 Consequently, @code{assq-ref} and friends should only be used where it
1954 is known that an entry exists, or where the ambiguity doesn't matter
1955 for some other reason.
1957 @deffn {Scheme Procedure} assq-ref alist key
1958 @deffnx {Scheme Procedure} assv-ref alist key
1959 @deffnx {Scheme Procedure} assoc-ref alist key
1960 @deffnx {C Function} scm_assq_ref (alist, key)
1961 @deffnx {C Function} scm_assv_ref (alist, key)
1962 @deffnx {C Function} scm_assoc_ref (alist, key)
1963 Like @code{assq}, @code{assv} and @code{assoc}, except that only the
1964 value associated with @var{key} in @var{alist} is returned. These
1965 functions are equivalent to
1968 (let ((ent (@var{associator} @var{key} @var{alist})))
1969 (and ent (cdr ent)))
1972 where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}.
1975 @node Removing Alist Entries
1976 @subsubsection Removing Alist Entries
1978 To remove the element from an association list whose key matches a
1979 specified key, use @code{assq-remove!}, @code{assv-remove!} or
1980 @code{assoc-remove!} (depending, as usual, on the level of equality
1981 required between the key that you specify and the keys in the
1984 As with @code{assq-set!} and friends, the specified alist may or may not
1985 be modified destructively, and the only safe way to update a variable
1986 containing the alist is to @code{set!} it to the value that
1987 @code{assq-remove!} and friends return.
1992 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
1993 ("james" . "1a London Road"))
1995 (set! address-list (assoc-remove! address-list "mary"))
1998 (("bob" . "11 Newington Avenue") ("james" . "1a London Road"))
2001 Note that, when @code{assq/v/oc-remove!} is used to modify an
2002 association list that has been constructed only using the corresponding
2003 @code{assq/v/oc-set!}, there can be at most one matching entry in the
2004 alist, so the question of multiple entries being removed in one go does
2005 not arise. If @code{assq/v/oc-remove!} is applied to an association
2006 list that has been constructed using @code{acons}, or an
2007 @code{assq/v/oc-set!} with a different level of equality, or any mixture
2008 of these, it removes only the first matching entry from the alist, even
2009 if the alist might contain further matching entries. For example:
2012 (define address-list '())
2013 (set! address-list (assq-set! address-list "mary" "11 Elm Street"))
2014 (set! address-list (assq-set! address-list "mary" "57 Pine Drive"))
2017 (("mary" . "57 Pine Drive") ("mary" . "11 Elm Street"))
2019 (set! address-list (assoc-remove! address-list "mary"))
2022 (("mary" . "11 Elm Street"))
2025 In this example, the two instances of the string "mary" are not the same
2026 when compared using @code{eq?}, so the two @code{assq-set!} calls add
2027 two distinct entries to @code{address-list}. When compared using
2028 @code{equal?}, both "mary"s in @code{address-list} are the same as the
2029 "mary" in the @code{assoc-remove!} call, but @code{assoc-remove!} stops
2030 after removing the first matching entry that it finds, and so one of the
2031 "mary" entries is left in place.
2033 @deffn {Scheme Procedure} assq-remove! alist key
2034 @deffnx {Scheme Procedure} assv-remove! alist key
2035 @deffnx {Scheme Procedure} assoc-remove! alist key
2036 @deffnx {C Function} scm_assq_remove_x (alist, key)
2037 @deffnx {C Function} scm_assv_remove_x (alist, key)
2038 @deffnx {C Function} scm_assoc_remove_x (alist, key)
2039 Delete the first entry in @var{alist} associated with @var{key}, and return
2040 the resulting alist.
2043 @node Sloppy Alist Functions
2044 @subsubsection Sloppy Alist Functions
2046 @code{sloppy-assq}, @code{sloppy-assv} and @code{sloppy-assoc} behave
2047 like the corresponding non-@code{sloppy-} procedures, except that they
2048 return @code{#f} when the specified association list is not well-formed,
2049 where the non-@code{sloppy-} versions would signal an error.
2051 Specifically, there are two conditions for which the non-@code{sloppy-}
2052 procedures signal an error, which the @code{sloppy-} procedures handle
2053 instead by returning @code{#f}. Firstly, if the specified alist as a
2054 whole is not a proper list:
2057 (assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
2059 ERROR: In procedure assoc in expression (assoc "mary" (quote #)):
2060 ERROR: Wrong type argument in position 2 (expecting NULLP): "open sesame"
2061 ABORT: (wrong-type-arg)
2063 (sloppy-assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
2069 Secondly, if one of the entries in the specified alist is not a pair:
2072 (assoc 2 '((1 . 1) 2 (3 . 9)))
2074 ERROR: In procedure assoc in expression (assoc 2 (quote #)):
2075 ERROR: Wrong type argument in position 2 (expecting CONSP): 2
2076 ABORT: (wrong-type-arg)
2078 (sloppy-assoc 2 '((1 . 1) 2 (3 . 9)))
2083 Unless you are explicitly working with badly formed association lists,
2084 it is much safer to use the non-@code{sloppy-} procedures, because they
2085 help to highlight coding and data errors that the @code{sloppy-}
2086 versions would silently cover up.
2088 @deffn {Scheme Procedure} sloppy-assq key alist
2089 @deffnx {C Function} scm_sloppy_assq (key, alist)
2090 Behaves like @code{assq} but does not do any error checking.
2091 Recommended only for use in Guile internals.
2094 @deffn {Scheme Procedure} sloppy-assv key alist
2095 @deffnx {C Function} scm_sloppy_assv (key, alist)
2096 Behaves like @code{assv} but does not do any error checking.
2097 Recommended only for use in Guile internals.
2100 @deffn {Scheme Procedure} sloppy-assoc key alist
2101 @deffnx {C Function} scm_sloppy_assoc (key, alist)
2102 Behaves like @code{assoc} but does not do any error checking.
2103 Recommended only for use in Guile internals.
2107 @subsubsection Alist Example
2109 Here is a longer example of how alists may be used in practice.
2112 (define capitals '(("New York" . "Albany")
2113 ("Oregon" . "Salem")
2114 ("Florida" . "Miami")))
2116 ;; What's the capital of Oregon?
2117 (assoc "Oregon" capitals) @result{} ("Oregon" . "Salem")
2118 (assoc-ref capitals "Oregon") @result{} "Salem"
2120 ;; We left out South Dakota.
2122 (assoc-set! capitals "South Dakota" "Pierre"))
2124 @result{} (("South Dakota" . "Pierre")
2125 ("New York" . "Albany")
2126 ("Oregon" . "Salem")
2127 ("Florida" . "Miami"))
2129 ;; And we got Florida wrong.
2131 (assoc-set! capitals "Florida" "Tallahassee"))
2133 @result{} (("South Dakota" . "Pierre")
2134 ("New York" . "Albany")
2135 ("Oregon" . "Salem")
2136 ("Florida" . "Tallahassee"))
2138 ;; After Oregon secedes, we can remove it.
2140 (assoc-remove! capitals "Oregon"))
2142 @result{} (("South Dakota" . "Pierre")
2143 ("New York" . "Albany")
2144 ("Florida" . "Tallahassee"))
2148 @subsection Hash Tables
2149 @tpindex Hash Tables
2151 @c FIXME::martin: Review me!
2153 Hash tables are dictionaries which offer similar functionality as
2154 association lists: They provide a mapping from keys to values. The
2155 difference is that association lists need time linear in the size of
2156 elements when searching for entries, whereas hash tables can normally
2157 search in constant time. The drawback is that hash tables require a
2158 little bit more memory, and that you can not use the normal list
2159 procedures (@pxref{Lists}) for working with them.
2162 * Hash Table Examples:: Demonstration of hash table usage.
2163 * Hash Table Reference:: Hash table procedure descriptions.
2167 @node Hash Table Examples
2168 @subsubsection Hash Table Examples
2170 @c FIXME::martin: Review me!
2172 For demonstration purposes, this section gives a few usage examples of
2173 some hash table procedures, together with some explanation what they do.
2175 First we start by creating a new hash table with 31 slots, and
2176 populate it with two key/value pairs.
2179 (define h (make-hash-table 31))
2181 (hashq-create-handle! h 'foo "bar")
2185 (hashq-create-handle! h 'braz "zonk")
2189 (hashq-create-handle! h 'frob #f)
2194 You can get the value for a given key with the procedure
2195 @code{hashq-ref}, but the problem with this procedure is that you
2196 cannot reliably determine whether a key does exists in the table. The
2197 reason is that the procedure returns @code{#f} if the key is not in
2198 the table, but it will return the same value if the key is in the
2199 table and just happens to have the value @code{#f}, as you can see in
2200 the following examples.
2211 (hashq-ref h 'not-there)
2216 Better is to use the procedure @code{hashq-get-handle}, which makes a
2217 distinction between the two cases. Just like @code{assq}, this
2218 procedure returns a key/value-pair on success, and @code{#f} if the
2222 (hashq-get-handle h 'foo)
2226 (hashq-get-handle h 'not-there)
2231 There is no procedure for calculating the number of key/value-pairs in
2232 a hash table, but @code{hash-fold} can be used for doing exactly that.
2235 (hash-fold (lambda (key value seed) (+ 1 seed)) 0 h)
2240 @node Hash Table Reference
2241 @subsubsection Hash Table Reference
2243 @c FIXME: Describe in broad terms what happens for resizing, and what
2244 @c the initial size means for this.
2246 Like the association list functions, the hash table functions come in
2247 several varieties, according to the equality test used for the keys.
2248 Plain @code{hash-} functions use @code{equal?}, @code{hashq-}
2249 functions use @code{eq?}, @code{hashv-} functions use @code{eqv?}, and
2250 the @code{hashx-} functions use an application supplied test.
2252 A single @code{make-hash-table} creates a hash table suitable for use
2253 with any set of functions, but it's imperative that just one set is
2254 then used consistently, or results will be unpredictable.
2257 Hash tables are implemented as a vector indexed by a hash value formed
2258 from the key, with an association list of key/value pairs for each
2259 bucket in case distinct keys hash together. Direct access to the
2260 pairs in those lists is provided by the @code{-handle-} functions.
2262 When the number of table entries goes above a threshold the vector is
2263 increased and the entries rehashed, to prevent the bucket lists
2264 becoming too long and slowing down accesses. When the number of
2265 entries goes below a threshold the vector is decreased to save space.
2268 For the @code{hashx-} ``extended'' routines, an application supplies a
2269 @var{hash} function producing an integer index like @code{hashq} etc
2270 below, and an @var{assoc} alist search function like @code{assq} etc
2271 (@pxref{Retrieving Alist Entries}). Here's an example of such
2272 functions implementing case-insensitive hashing of string keys,
2275 (use-modules (srfi srfi-1)
2278 (define (my-hash str size)
2279 (remainder (string-hash-ci str) size))
2280 (define (my-assoc str alist)
2281 (find (lambda (pair) (string-ci=? str (car pair))) alist))
2283 (define my-table (make-hash-table))
2284 (hashx-set! my-hash my-assoc my-table "foo" 123)
2286 (hashx-ref my-hash my-assoc my-table "FOO")
2290 In a @code{hashx-} @var{hash} function the aim is to spread keys
2291 across the vector, so bucket lists don't become long. But the actual
2292 values are arbitrary as long as they're in the range 0 to
2293 @math{@var{size}-1}. Helpful functions for forming a hash value, in
2294 addition to @code{hashq} etc below, include @code{symbol-hash}
2295 (@pxref{Symbol Keys}), @code{string-hash} and @code{string-hash-ci}
2296 (@pxref{SRFI-13 Comparison}), and @code{char-set-hash} (@pxref{SRFI-14
2297 Predicates/Comparison}).
2299 Note that currently, unfortunately, there's no @code{hashx-remove!}
2300 function, which rather limits the usefulness of the @code{hashx-}
2304 @deffn {Scheme Procedure} make-hash-table [size]
2305 Create a new hash table, with an optional minimum vector @var{size}.
2307 When @var{size} is given, the table vector will still grow and shrink
2308 automatically, as described above, but with @var{size} as a minimum.
2309 If an application knows roughly how many entries the table will hold
2310 then it can use @var{size} to avoid rehashing when initial entries are
2314 @deffn {Scheme Procedure} hash-ref table key [dflt]
2315 @deffnx {Scheme Procedure} hashq-ref table key [dflt]
2316 @deffnx {Scheme Procedure} hashv-ref table key [dflt]
2317 @deffnx {Scheme Procedure} hashx-ref hash assoc table key [dflt]
2318 @deffnx {C Function} scm_hash_ref (table, key, dflt)
2319 @deffnx {C Function} scm_hashq_ref (table, key, dflt)
2320 @deffnx {C Function} scm_hashv_ref (table, key, dflt)
2321 @deffnx {C Function} scm_hashx_ref (hash, assoc, table, key, dflt)
2322 Lookup @var{key} in the given hash @var{table}, and return the
2323 associated value. If @var{key} is not found, return @var{dflt}, or
2324 @code{#f} if @var{dflt} is not given. (For the C functions,
2325 @var{dflt} must be given.)
2328 @deffn {Scheme Procedure} hash-set! table key val
2329 @deffnx {Scheme Procedure} hashq-set! table key val
2330 @deffnx {Scheme Procedure} hashv-set! table key val
2331 @deffnx {Scheme Procedure} hashx-set! hash assoc table key val
2332 @deffnx {C Function} scm_hash_set_x (table, key, val)
2333 @deffnx {C Function} scm_hashq_set_x (table, key, val)
2334 @deffnx {C Function} scm_hashv_set_x (table, key, val)
2335 @deffnx {C Function} scm_hashx_set_x (hash, assoc, table, key, val)
2336 Associate @var{val} with @var{key} in the given hash @var{table}. If
2337 @var{key} is already present then it's associated value is changed.
2338 If it's not present then a new entry is created.
2341 @deffn {Scheme Procedure} hash-remove! table key
2342 @deffnx {Scheme Procedure} hashq-remove! table key
2343 @deffnx {Scheme Procedure} hashv-remove! table key
2344 @deffnx {C Function} scm_hash_remove_x (table, key)
2345 @deffnx {C Function} scm_hashq_remove_x (table, key)
2346 @deffnx {C Function} scm_hashv_remove_x (table, key)
2347 Remove any association for @var{key} in the given hash @var{table}.
2348 If @var{key} is not in @var{table} then nothing is done.
2351 @deffn {Scheme Procedure} hash key size
2352 @deffnx {Scheme Procedure} hashq key size
2353 @deffnx {Scheme Procedure} hashv key size
2354 @deffnx {C Function} scm_hash (key, size)
2355 @deffnx {C Function} scm_hashq (key, size)
2356 @deffnx {C Function} scm_hashv (key, size)
2357 Return a hash value for @var{key}. This is a number in the range
2358 @math{0} to @math{@var{size}-1}, which is suitable for use in a hash
2359 table of the given @var{size}.
2361 Note that @code{hashq} and @code{hashv} may use internal addresses of
2362 objects, so if an object is garbage collected and re-created it can
2363 have a different hash value, even when the two are notionally
2364 @code{eq?}. For instance with symbols,
2367 (hashq 'something 123) @result{} 19
2369 (hashq 'something 123) @result{} 62
2372 In normal use this is not a problem, since an object entered into a
2373 hash table won't be garbage collected until removed. It's only if
2374 hashing calculations are somehow separated from normal references that
2375 its lifetime needs to be considered.
2378 @deffn {Scheme Procedure} hash-get-handle table key
2379 @deffnx {Scheme Procedure} hashq-get-handle table key
2380 @deffnx {Scheme Procedure} hashv-get-handle table key
2381 @deffnx {Scheme Procedure} hashx-get-handle hash assoc table key
2382 @deffnx {C Function} scm_hash_get_handle (table, key)
2383 @deffnx {C Function} scm_hashq_get_handle (table, key)
2384 @deffnx {C Function} scm_hashv_get_handle (table, key)
2385 @deffnx {C Function} scm_hashx_get_handle (hash, assoc, table, key)
2386 Return the @code{(@var{key} . @var{value})} pair for @var{key} in the
2387 given hash @var{table}, or @code{#f} if @var{key} is not in
2391 @deffn {Scheme Procedure} hash-create-handle! table key init
2392 @deffnx {Scheme Procedure} hashq-create-handle! table key init
2393 @deffnx {Scheme Procedure} hashv-create-handle! table key init
2394 @deffnx {Scheme Procedure} hashx-create-handle! hash assoc table key init
2395 @deffnx {C Function} scm_hash_create_handle_x (table, key, init)
2396 @deffnx {C Function} scm_hashq_create_handle_x (table, key, init)
2397 @deffnx {C Function} scm_hashv_create_handle_x (table, key, init)
2398 @deffnx {C Function} scm_hashx_create_handle_x (hash, assoc, table, key, init)
2399 Return the @code{(@var{key} . @var{value})} pair for @var{key} in the
2400 given hash @var{table}. If @var{key} is not in @var{table} then
2401 create an entry for it with @var{init} as the value, and return that
2405 @deffn {Scheme Procedure} hash-map proc table
2406 @deffnx {Scheme Procedure} hash-for-each proc table
2407 @deffnx {C Function} scm_hash_map (proc, table)
2408 @deffnx {C Function} scm_hash_for_each (proc, table)
2409 Apply @var{proc} to the entries in the given hash @var{table}. Each
2410 call is @code{(@var{proc} @var{key} @var{value})}. @code{hash-map}
2411 returns a list of the results from these calls, @code{hash-for-each}
2412 discards the results and returns an unspecified value.
2414 Calls are made over the table entries in an unspecified order, and for
2415 @code{hash-map} the order of the values in the returned list is
2416 unspecified. Results will be unpredictable if @var{table} is modified
2419 For example the following returns a new alist comprising all the
2420 entries from @code{mytable}, in no particular order.
2423 (hash-map cons mytable)
2427 @deffn {Scheme Procedure} hash-fold proc init table
2428 @deffnx {C Function} scm_hash_fold (proc, init, table)
2429 Accumulate a result by applying @var{proc} to the elements of the
2430 given hash @var{table}. Each call is @code{(@var{proc} @var{key}
2431 @var{value} @var{prior-result})}, where @var{key} and @var{value} are
2432 from the @var{table} and @var{prior-result} is the return from the
2433 previous @var{proc} call. For the first call, @var{prior-result} is
2434 the given @var{init} value.
2436 Calls are made over the table entries in an unspecified order.
2437 Results will be unpredictable if @var{table} is modified while
2438 @code{hash-fold} is running.
2440 For example, the following returns a count of how many keys in
2441 @code{mytable} are strings.
2444 (hash-fold (lambda (key value prior)
2445 (if (string? key) (1+ prior) prior))
2452 @c TeX-master: "guile.texi"