2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @node Compound Data Types
9 @section Compound Data Types
11 This chapter describes Guile's compound data types. By @dfn{compound}
12 we mean that the primary purpose of these data types is to act as
13 containers for other kinds of data (including other compound objects).
14 For instance, a (non-uniform) vector with length 5 is a container that
15 can hold five arbitrary Scheme objects.
17 The various kinds of container object differ from each other in how
18 their memory is allocated, how they are indexed, and how particular
19 values can be looked up within them.
22 * Pairs:: Scheme's basic building block.
23 * Lists:: Special list functions supported by Guile.
24 * Vectors:: One-dimensional arrays of Scheme objects.
25 * Uniform Numeric Vectors:: Vectors with elements of a single numeric type.
26 * Bit Vectors:: Vectors of bits.
27 * Generalized Vectors:: Treating all vector-like things uniformly.
28 * Arrays:: Matrices, etc.
31 * Dictionary Types:: About dictionary types in general.
32 * Association Lists:: List-based dictionaries.
33 * Hash Tables:: Table-based dictionaries.
41 Pairs are used to combine two Scheme objects into one compound object.
42 Hence the name: A pair stores a pair of objects.
44 The data type @dfn{pair} is extremely important in Scheme, just like in
45 any other Lisp dialect. The reason is that pairs are not only used to
46 make two values available as one object, but that pairs are used for
47 constructing lists of values. Because lists are so important in Scheme,
48 they are described in a section of their own (@pxref{Lists}).
50 Pairs can literally get entered in source code or at the REPL, in the
51 so-called @dfn{dotted list} syntax. This syntax consists of an opening
52 parentheses, the first element of the pair, a dot, the second element
53 and a closing parentheses. The following example shows how a pair
54 consisting of the two numbers 1 and 2, and a pair containing the symbols
55 @code{foo} and @code{bar} can be entered. It is very important to write
56 the whitespace before and after the dot, because otherwise the Scheme
57 parser would not be able to figure out where to split the tokens.
64 But beware, if you want to try out these examples, you have to
65 @dfn{quote} the expressions. More information about quotation is
66 available in the section (REFFIXME). The correct way to try these
67 examples is as follows.
78 A new pair is made by calling the procedure @code{cons} with two
79 arguments. Then the argument values are stored into a newly allocated
80 pair, and the pair is returned. The name @code{cons} stands for
81 "construct". Use the procedure @code{pair?} to test whether a
82 given Scheme object is a pair or not.
85 @deffn {Scheme Procedure} cons x y
86 @deffnx {C Function} scm_cons (x, y)
87 Return a newly allocated pair whose car is @var{x} and whose
88 cdr is @var{y}. The pair is guaranteed to be different (in the
89 sense of @code{eq?}) from every previously existing object.
93 @deffn {Scheme Procedure} pair? x
94 @deffnx {C Function} scm_pair_p (x)
95 Return @code{#t} if @var{x} is a pair; otherwise return
99 @deftypefn {C Function} int scm_is_pair (SCM x)
100 Return 1 when @var{x} is a pair; otherwise return 0.
103 The two parts of a pair are traditionally called @dfn{car} and
104 @dfn{cdr}. They can be retrieved with procedures of the same name
105 (@code{car} and @code{cdr}), and can be modified with the procedures
106 @code{set-car!} and @code{set-cdr!}. Since a very common operation in
107 Scheme programs is to access the car of a car of a pair, or the car of
108 the cdr of a pair, etc., the procedures called @code{caar},
109 @code{cadr} and so on are also predefined.
113 @deffn {Scheme Procedure} car pair
114 @deffnx {Scheme Procedure} cdr pair
115 @deffnx {C Function} scm_car (pair)
116 @deffnx {C Function} scm_cdr (pair)
117 Return the car or the cdr of @var{pair}, respectively.
120 @deftypefn {C Macro} SCM SCM_CAR (SCM pair)
121 @deftypefnx {C Macro} SCM SCM_CDR (SCM pair)
122 These two macros are the fastest way to access the car or cdr of a
123 pair; they can be thought of as compiling into a single memory
126 These macros do no checking at all. The argument @var{pair} must be a
130 @deffn {Scheme Procedure} cddr pair
131 @deffnx {Scheme Procedure} cdar pair
132 @deffnx {Scheme Procedure} cadr pair
133 @deffnx {Scheme Procedure} caar pair
134 @deffnx {Scheme Procedure} cdddr pair
135 @deffnx {Scheme Procedure} cddar pair
136 @deffnx {Scheme Procedure} cdadr pair
137 @deffnx {Scheme Procedure} cdaar pair
138 @deffnx {Scheme Procedure} caddr pair
139 @deffnx {Scheme Procedure} cadar pair
140 @deffnx {Scheme Procedure} caadr pair
141 @deffnx {Scheme Procedure} caaar pair
142 @deffnx {Scheme Procedure} cddddr pair
143 @deffnx {Scheme Procedure} cdddar pair
144 @deffnx {Scheme Procedure} cddadr pair
145 @deffnx {Scheme Procedure} cddaar pair
146 @deffnx {Scheme Procedure} cdaddr pair
147 @deffnx {Scheme Procedure} cdadar pair
148 @deffnx {Scheme Procedure} cdaadr pair
149 @deffnx {Scheme Procedure} cdaaar pair
150 @deffnx {Scheme Procedure} cadddr pair
151 @deffnx {Scheme Procedure} caddar pair
152 @deffnx {Scheme Procedure} cadadr pair
153 @deffnx {Scheme Procedure} cadaar pair
154 @deffnx {Scheme Procedure} caaddr pair
155 @deffnx {Scheme Procedure} caadar pair
156 @deffnx {Scheme Procedure} caaadr pair
157 @deffnx {Scheme Procedure} caaaar pair
158 @deffnx {C Function} scm_cddr (pair)
159 @deffnx {C Function} scm_cdar (pair)
160 @deffnx {C Function} scm_cadr (pair)
161 @deffnx {C Function} scm_caar (pair)
162 @deffnx {C Function} scm_cdddr (pair)
163 @deffnx {C Function} scm_cddar (pair)
164 @deffnx {C Function} scm_cdadr (pair)
165 @deffnx {C Function} scm_cdaar (pair)
166 @deffnx {C Function} scm_caddr (pair)
167 @deffnx {C Function} scm_cadar (pair)
168 @deffnx {C Function} scm_caadr (pair)
169 @deffnx {C Function} scm_caaar (pair)
170 @deffnx {C Function} scm_cddddr (pair)
171 @deffnx {C Function} scm_cdddar (pair)
172 @deffnx {C Function} scm_cddadr (pair)
173 @deffnx {C Function} scm_cddaar (pair)
174 @deffnx {C Function} scm_cdaddr (pair)
175 @deffnx {C Function} scm_cdadar (pair)
176 @deffnx {C Function} scm_cdaadr (pair)
177 @deffnx {C Function} scm_cdaaar (pair)
178 @deffnx {C Function} scm_cadddr (pair)
179 @deffnx {C Function} scm_caddar (pair)
180 @deffnx {C Function} scm_cadadr (pair)
181 @deffnx {C Function} scm_cadaar (pair)
182 @deffnx {C Function} scm_caaddr (pair)
183 @deffnx {C Function} scm_caadar (pair)
184 @deffnx {C Function} scm_caaadr (pair)
185 @deffnx {C Function} scm_caaaar (pair)
186 These procedures are compositions of @code{car} and @code{cdr}, where
187 for example @code{caddr} could be defined by
190 (define caddr (lambda (x) (car (cdr (cdr x)))))
195 @deffn {Scheme Procedure} set-car! pair value
196 @deffnx {C Function} scm_set_car_x (pair, value)
197 Stores @var{value} in the car field of @var{pair}. The value returned
198 by @code{set-car!} is unspecified.
202 @deffn {Scheme Procedure} set-cdr! pair value
203 @deffnx {C Function} scm_set_cdr_x (pair, value)
204 Stores @var{value} in the cdr field of @var{pair}. The value returned
205 by @code{set-cdr!} is unspecified.
213 A very important data type in Scheme---as well as in all other Lisp
214 dialects---is the data type @dfn{list}.@footnote{Strictly speaking,
215 Scheme does not have a real datatype @dfn{list}. Lists are made up of
216 @dfn{chained pairs}, and only exist by definition---a list is a chain
217 of pairs which looks like a list.}
219 This is the short definition of what a list is:
223 Either the empty list @code{()},
226 or a pair which has a list in its cdr.
229 @c FIXME::martin: Describe the pair chaining in more detail.
231 @c FIXME::martin: What is a proper, what an improper list?
232 @c What is a circular list?
234 @c FIXME::martin: Maybe steal some graphics from the Elisp reference
238 * List Syntax:: Writing literal lists.
239 * List Predicates:: Testing lists.
240 * List Constructors:: Creating new lists.
241 * List Selection:: Selecting from lists, getting their length.
242 * Append/Reverse:: Appending and reversing lists.
243 * List Modification:: Modifying existing lists.
244 * List Searching:: Searching for list elements
245 * List Mapping:: Applying procedures to lists.
249 @subsubsection List Read Syntax
251 The syntax for lists is an opening parentheses, then all the elements of
252 the list (separated by whitespace) and finally a closing
253 parentheses.@footnote{Note that there is no separation character between
254 the list elements, like a comma or a semicolon.}.
257 (1 2 3) ; @r{a list of the numbers 1, 2 and 3}
258 ("foo" bar 3.1415) ; @r{a string, a symbol and a real number}
259 () ; @r{the empty list}
262 The last example needs a bit more explanation. A list with no elements,
263 called the @dfn{empty list}, is special in some ways. It is used for
264 terminating lists by storing it into the cdr of the last pair that makes
265 up a list. An example will clear that up:
276 This example also shows that lists have to be quoted (REFFIXME) when
277 written, because they would otherwise be mistakingly taken as procedure
278 applications (@pxref{Simple Invocation}).
281 @node List Predicates
282 @subsubsection List Predicates
284 Often it is useful to test whether a given Scheme object is a list or
285 not. List-processing procedures could use this information to test
286 whether their input is valid, or they could do different things
287 depending on the datatype of their arguments.
290 @deffn {Scheme Procedure} list? x
291 @deffnx {C Function} scm_list_p (x)
292 Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
295 The predicate @code{null?} is often used in list-processing code to
296 tell whether a given list has run out of elements. That is, a loop
297 somehow deals with the elements of a list until the list satisfies
298 @code{null?}. Then, the algorithm terminates.
301 @deffn {Scheme Procedure} null? x
302 @deffnx {C Function} scm_null_p (x)
303 Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
306 @deftypefn {C Function} int scm_is_null (SCM x)
307 Return 1 when @var{x} is the empty list; otherwise return 0.
311 @node List Constructors
312 @subsubsection List Constructors
314 This section describes the procedures for constructing new lists.
315 @code{list} simply returns a list where the elements are the arguments,
316 @code{cons*} is similar, but the last argument is stored in the cdr of
317 the last pair of the list.
319 @c C Function scm_list(rest) used to be documented here, but it's a
320 @c no-op since it does nothing but return the list the caller must
321 @c have already created.
323 @deffn {Scheme Procedure} list elem1 @dots{} elemN
324 @deffnx {C Function} scm_list_1 (elem1)
325 @deffnx {C Function} scm_list_2 (elem1, elem2)
326 @deffnx {C Function} scm_list_3 (elem1, elem2, elem3)
327 @deffnx {C Function} scm_list_4 (elem1, elem2, elem3, elem4)
328 @deffnx {C Function} scm_list_5 (elem1, elem2, elem3, elem4, elem5)
329 @deffnx {C Function} scm_list_n (elem1, @dots{}, elemN, @nicode{SCM_UNDEFINED})
331 Return a new list containing elements @var{elem1} to @var{elemN}.
333 @code{scm_list_n} takes a variable number of arguments, terminated by
334 the special @code{SCM_UNDEFINED}. That final @code{SCM_UNDEFINED} is
335 not included in the list. None of @var{elem1} to @var{elemN} can
336 themselves be @code{SCM_UNDEFINED}, or @code{scm_list_n} will
337 terminate at that point.
340 @c C Function scm_cons_star(arg1,rest) used to be documented here,
341 @c but it's not really a useful interface, since it expects the
342 @c caller to have already consed up all but the first argument
345 @deffn {Scheme Procedure} cons* arg1 arg2 @dots{}
346 Like @code{list}, but the last arg provides the tail of the
347 constructed list, returning @code{(cons @var{arg1} (cons
348 @var{arg2} (cons @dots{} @var{argn})))}. Requires at least one
349 argument. If given one argument, that argument is returned as
350 result. This function is called @code{list*} in some other
351 Schemes and in Common LISP.
354 @deffn {Scheme Procedure} list-copy lst
355 @deffnx {C Function} scm_list_copy (lst)
356 Return a (newly-created) copy of @var{lst}.
359 @deffn {Scheme Procedure} make-list n [init]
360 Create a list containing of @var{n} elements, where each element is
361 initialized to @var{init}. @var{init} defaults to the empty list
362 @code{()} if not given.
365 Note that @code{list-copy} only makes a copy of the pairs which make up
366 the spine of the lists. The list elements are not copied, which means
367 that modifying the elements of the new list also modifies the elements
368 of the old list. On the other hand, applying procedures like
369 @code{set-cdr!} or @code{delv!} to the new list will not alter the old
370 list. If you also need to copy the list elements (making a deep copy),
371 use the procedure @code{copy-tree} (@pxref{Copying}).
374 @subsubsection List Selection
376 These procedures are used to get some information about a list, or to
377 retrieve one or more elements of a list.
380 @deffn {Scheme Procedure} length lst
381 @deffnx {C Function} scm_length (lst)
382 Return the number of elements in list @var{lst}.
385 @deffn {Scheme Procedure} last-pair lst
386 @deffnx {C Function} scm_last_pair (lst)
387 Return the last pair in @var{lst}, signalling an error if
388 @var{lst} is circular.
392 @deffn {Scheme Procedure} list-ref list k
393 @deffnx {C Function} scm_list_ref (list, k)
394 Return the @var{k}th element from @var{list}.
398 @deffn {Scheme Procedure} list-tail lst k
399 @deffnx {Scheme Procedure} list-cdr-ref lst k
400 @deffnx {C Function} scm_list_tail (lst, k)
401 Return the "tail" of @var{lst} beginning with its @var{k}th element.
402 The first element of the list is considered to be element 0.
404 @code{list-tail} and @code{list-cdr-ref} are identical. It may help to
405 think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list,
406 or returning the results of cdring @var{k} times down @var{lst}.
409 @deffn {Scheme Procedure} list-head lst k
410 @deffnx {C Function} scm_list_head (lst, k)
411 Copy the first @var{k} elements from @var{lst} into a new list, and
416 @subsubsection Append and Reverse
418 @code{append} and @code{append!} are used to concatenate two or more
419 lists in order to form a new list. @code{reverse} and @code{reverse!}
420 return lists with the same elements as their arguments, but in reverse
421 order. The procedure variants with an @code{!} directly modify the
422 pairs which form the list, whereas the other procedures create new
423 pairs. This is why you should be careful when using the side-effecting
427 @deffn {Scheme Procedure} append lst1 @dots{} lstN
428 @deffnx {Scheme Procedure} append! lst1 @dots{} lstN
429 @deffnx {C Function} scm_append (lstlst)
430 @deffnx {C Function} scm_append_x (lstlst)
431 Return a list comprising all the elements of lists @var{lst1} to
435 (append '(x) '(y)) @result{} (x y)
436 (append '(a) '(b c d)) @result{} (a b c d)
437 (append '(a (b)) '((c))) @result{} (a (b) (c))
440 The last argument @var{lstN} may actually be any object; an improper
441 list results if the last argument is not a proper list.
444 (append '(a b) '(c . d)) @result{} (a b c . d)
445 (append '() 'a) @result{} a
448 @code{append} doesn't modify the given lists, but the return may share
449 structure with the final @var{lstN}. @code{append!} modifies the
450 given lists to form its return.
452 For @code{scm_append} and @code{scm_append_x}, @var{lstlst} is a list
453 of the list operands @var{lst1} @dots{} @var{lstN}. That @var{lstlst}
454 itself is not modified or used in the return.
458 @deffn {Scheme Procedure} reverse lst
459 @deffnx {Scheme Procedure} reverse! lst [newtail]
460 @deffnx {C Function} scm_reverse (lst)
461 @deffnx {C Function} scm_reverse_x (lst, newtail)
462 Return a list comprising the elements of @var{lst}, in reverse order.
464 @code{reverse} constructs a new list, @code{reverse!} modifies
465 @var{lst} in constructing its return.
467 For @code{reverse!}, the optional @var{newtail} is appended to to the
468 result. @var{newtail} isn't reversed, it simply becomes the list
469 tail. For @code{scm_reverse_x}, the @var{newtail} parameter is
470 mandatory, but can be @code{SCM_EOL} if no further tail is required.
473 @node List Modification
474 @subsubsection List Modification
476 The following procedures modify an existing list, either by changing
477 elements of the list, or by changing the list structure itself.
479 @deffn {Scheme Procedure} list-set! list k val
480 @deffnx {C Function} scm_list_set_x (list, k, val)
481 Set the @var{k}th element of @var{list} to @var{val}.
484 @deffn {Scheme Procedure} list-cdr-set! list k val
485 @deffnx {C Function} scm_list_cdr_set_x (list, k, val)
486 Set the @var{k}th cdr of @var{list} to @var{val}.
489 @deffn {Scheme Procedure} delq item lst
490 @deffnx {C Function} scm_delq (item, lst)
491 Return a newly-created copy of @var{lst} with elements
492 @code{eq?} to @var{item} removed. This procedure mirrors
493 @code{memq}: @code{delq} compares elements of @var{lst} against
494 @var{item} with @code{eq?}.
497 @deffn {Scheme Procedure} delv item lst
498 @deffnx {C Function} scm_delv (item, lst)
499 Return a newly-created copy of @var{lst} with elements
500 @code{eqv?} to @var{item} removed. This procedure mirrors
501 @code{memv}: @code{delv} compares elements of @var{lst} against
502 @var{item} with @code{eqv?}.
505 @deffn {Scheme Procedure} delete item lst
506 @deffnx {C Function} scm_delete (item, lst)
507 Return a newly-created copy of @var{lst} with elements
508 @code{equal?} to @var{item} removed. This procedure mirrors
509 @code{member}: @code{delete} compares elements of @var{lst}
510 against @var{item} with @code{equal?}.
513 @deffn {Scheme Procedure} delq! item lst
514 @deffnx {Scheme Procedure} delv! item lst
515 @deffnx {Scheme Procedure} delete! item lst
516 @deffnx {C Function} scm_delq_x (item, lst)
517 @deffnx {C Function} scm_delv_x (item, lst)
518 @deffnx {C Function} scm_delete_x (item, lst)
519 These procedures are destructive versions of @code{delq}, @code{delv}
520 and @code{delete}: they modify the pointers in the existing @var{lst}
521 rather than creating a new list. Caveat evaluator: Like other
522 destructive list functions, these functions cannot modify the binding of
523 @var{lst}, and so cannot be used to delete the first element of
524 @var{lst} destructively.
527 @deffn {Scheme Procedure} delq1! item lst
528 @deffnx {C Function} scm_delq1_x (item, lst)
529 Like @code{delq!}, but only deletes the first occurrence of
530 @var{item} from @var{lst}. Tests for equality using
531 @code{eq?}. See also @code{delv1!} and @code{delete1!}.
534 @deffn {Scheme Procedure} delv1! item lst
535 @deffnx {C Function} scm_delv1_x (item, lst)
536 Like @code{delv!}, but only deletes the first occurrence of
537 @var{item} from @var{lst}. Tests for equality using
538 @code{eqv?}. See also @code{delq1!} and @code{delete1!}.
541 @deffn {Scheme Procedure} delete1! item lst
542 @deffnx {C Function} scm_delete1_x (item, lst)
543 Like @code{delete!}, but only deletes the first occurrence of
544 @var{item} from @var{lst}. Tests for equality using
545 @code{equal?}. See also @code{delq1!} and @code{delv1!}.
548 @deffn {Scheme Procedure} filter pred lst
549 @deffnx {Scheme Procedure} filter! pred lst
550 Return a list containing all elements from @var{lst} which satisfy the
551 predicate @var{pred}. The elements in the result list have the same
552 order as in @var{lst}. The order in which @var{pred} is applied to
553 the list elements is not specified.
555 @code{filter!} is allowed, but not required to modify the structure of
559 @subsubsection List Searching
561 The following procedures search lists for particular elements. They use
562 different comparison predicates for comparing list elements with the
563 object to be searched. When they fail, they return @code{#f}, otherwise
564 they return the sublist whose car is equal to the search object, where
565 equality depends on the equality predicate used.
568 @deffn {Scheme Procedure} memq x lst
569 @deffnx {C Function} scm_memq (x, lst)
570 Return the first sublist of @var{lst} whose car is @code{eq?}
571 to @var{x} where the sublists of @var{lst} are the non-empty
572 lists returned by @code{(list-tail @var{lst} @var{k})} for
573 @var{k} less than the length of @var{lst}. If @var{x} does not
574 occur in @var{lst}, then @code{#f} (not the empty list) is
579 @deffn {Scheme Procedure} memv x lst
580 @deffnx {C Function} scm_memv (x, lst)
581 Return the first sublist of @var{lst} whose car is @code{eqv?}
582 to @var{x} where the sublists of @var{lst} are the non-empty
583 lists returned by @code{(list-tail @var{lst} @var{k})} for
584 @var{k} less than the length of @var{lst}. If @var{x} does not
585 occur in @var{lst}, then @code{#f} (not the empty list) is
590 @deffn {Scheme Procedure} member x lst
591 @deffnx {C Function} scm_member (x, lst)
592 Return the first sublist of @var{lst} whose car is
593 @code{equal?} to @var{x} where the sublists of @var{lst} are
594 the non-empty lists returned by @code{(list-tail @var{lst}
595 @var{k})} for @var{k} less than the length of @var{lst}. If
596 @var{x} does not occur in @var{lst}, then @code{#f} (not the
597 empty list) is returned.
602 @subsubsection List Mapping
604 List processing is very convenient in Scheme because the process of
605 iterating over the elements of a list can be highly abstracted. The
606 procedures in this section are the most basic iterating procedures for
607 lists. They take a procedure and one or more lists as arguments, and
608 apply the procedure to each element of the list. They differ in their
612 @c begin (texi-doc-string "guile" "map")
613 @deffn {Scheme Procedure} map proc arg1 arg2 @dots{}
614 @deffnx {Scheme Procedure} map-in-order proc arg1 arg2 @dots{}
615 @deffnx {C Function} scm_map (proc, arg1, args)
616 Apply @var{proc} to each element of the list @var{arg1} (if only two
617 arguments are given), or to the corresponding elements of the argument
618 lists (if more than two arguments are given). The result(s) of the
619 procedure applications are saved and returned in a list. For
620 @code{map}, the order of procedure applications is not specified,
621 @code{map-in-order} applies the procedure from left to right to the list
626 @c begin (texi-doc-string "guile" "for-each")
627 @deffn {Scheme Procedure} for-each proc arg1 arg2 @dots{}
628 Like @code{map}, but the procedure is always applied from left to right,
629 and the result(s) of the procedure applications are thrown away. The
630 return value is not specified.
638 Vectors are sequences of Scheme objects. Unlike lists, the length of a
639 vector, once the vector is created, cannot be changed. The advantage of
640 vectors over lists is that the time required to access one element of a vector
641 given its @dfn{position} (synonymous with @dfn{index}), a zero-origin number,
642 is constant, whereas lists have an access time linear to the position of the
643 accessed element in the list.
645 Vectors can contain any kind of Scheme object; it is even possible to
646 have different types of objects in the same vector. For vectors
647 containing vectors, you may wish to use arrays, instead. Note, too,
648 that vectors are the special case of one dimensional non-uniform arrays
649 and that most array procedures operate happily on vectors
653 * Vector Syntax:: Read syntax for vectors.
654 * Vector Creation:: Dynamic vector creation and validation.
655 * Vector Accessors:: Accessing and modifying vector contents.
656 * Vector Accessing from C:: Ways to work with vectors from C.
661 @subsubsection Read Syntax for Vectors
663 Vectors can literally be entered in source code, just like strings,
664 characters or some of the other data types. The read syntax for vectors
665 is as follows: A sharp sign (@code{#}), followed by an opening
666 parentheses, all elements of the vector in their respective read syntax,
667 and finally a closing parentheses. The following are examples of the
668 read syntax for vectors; where the first vector only contains numbers
669 and the second three different object types: a string, a symbol and a
670 number in hexadecimal notation.
674 #("Hello" foo #xdeadbeef)
677 Like lists, vectors have to be quoted:
680 '#(a b c) @result{} #(a b c)
683 @node Vector Creation
684 @subsubsection Dynamic Vector Creation and Validation
686 Instead of creating a vector implicitly by using the read syntax just
687 described, you can create a vector dynamically by calling one of the
688 @code{vector} and @code{list->vector} primitives with the list of Scheme
689 values that you want to place into a vector. The size of the vector
690 thus created is determined implicitly by the number of arguments given.
693 @rnindex list->vector
694 @deffn {Scheme Procedure} vector . l
695 @deffnx {Scheme Procedure} list->vector l
696 @deffnx {C Function} scm_vector (l)
697 Return a newly allocated vector composed of the
698 given arguments. Analogous to @code{list}.
701 (vector 'a 'b 'c) @result{} #(a b c)
705 The inverse operation is @code{vector->list}:
707 @rnindex vector->list
708 @deffn {Scheme Procedure} vector->list v
709 @deffnx {C Function} scm_vector_to_list (v)
710 Return a newly allocated list composed of the elements of @var{v}.
713 (vector->list '#(dah dah didah)) @result{} (dah dah didah)
714 (list->vector '(dididit dah)) @result{} #(dididit dah)
718 To allocate a vector with an explicitly specified size, use
719 @code{make-vector}. With this primitive you can also specify an initial
720 value for the vector elements (the same value for all elements, that
724 @deffn {Scheme Procedure} make-vector len [fill]
725 @deffnx {C Function} scm_make_vector (len, fill)
726 Return a newly allocated vector of @var{len} elements. If a
727 second argument is given, then each position is initialized to
728 @var{fill}. Otherwise the initial contents of each position is
732 @deftypefn {C Function} SCM scm_c_make_vector (size_t k, SCM fill)
733 Like @code{scm_make_vector}, but the length is given as a @code{size_t}.
736 To check whether an arbitrary Scheme value @emph{is} a vector, use the
737 @code{vector?} primitive:
740 @deffn {Scheme Procedure} vector? obj
741 @deffnx {C Function} scm_vector_p (obj)
742 Return @code{#t} if @var{obj} is a vector, otherwise return
746 @deftypefn {C Function} int scm_is_vector (SCM obj)
747 Return non-zero when @var{obj} is a vector, otherwise return
751 @node Vector Accessors
752 @subsubsection Accessing and Modifying Vector Contents
754 @code{vector-length} and @code{vector-ref} return information about a
755 given vector, respectively its size and the elements that are contained
758 @rnindex vector-length
759 @deffn {Scheme Procedure} vector-length vector
760 @deffnx {C Function} scm_vector_length vector
761 Return the number of elements in @var{vector} as an exact integer.
764 @deftypefn {C Function} size_t scm_c_vector_length (SCM v)
765 Return the number of elements in @var{vector} as a @code{size_t}.
769 @deffn {Scheme Procedure} vector-ref vector k
770 @deffnx {C Function} scm_vector_ref vector k
771 Return the contents of position @var{k} of @var{vector}.
772 @var{k} must be a valid index of @var{vector}.
774 (vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
775 (vector-ref '#(1 1 2 3 5 8 13 21)
776 (let ((i (round (* 2 (acos -1)))))
783 @deftypefn {C Function} SCM scm_c_vector_ref (SCM v, size_t k)
784 Return the contents of position @var{k} (a @code{size_t}) of
788 A vector created by one of the dynamic vector constructor procedures
789 (@pxref{Vector Creation}) can be modified using the following
792 @emph{NOTE:} According to R5RS, it is an error to use any of these
793 procedures on a literally read vector, because such vectors should be
794 considered as constants. Currently, however, Guile does not detect this
798 @deffn {Scheme Procedure} vector-set! vector k obj
799 @deffnx {C Function} scm_vector_set_x vector k obj
800 Store @var{obj} in position @var{k} of @var{vector}.
801 @var{k} must be a valid index of @var{vector}.
802 The value returned by @samp{vector-set!} is unspecified.
804 (let ((vec (vector 0 '(2 2 2 2) "Anna")))
805 (vector-set! vec 1 '("Sue" "Sue"))
806 vec) @result{} #(0 ("Sue" "Sue") "Anna")
810 @deftypefn {C Function} void scm_c_vector_set_x (SCM v, size_t k, SCM obj)
811 Store @var{obj} in position @var{k} (a @code{size_t}) of @var{v}.
814 @rnindex vector-fill!
815 @deffn {Scheme Procedure} vector-fill! v fill
816 @deffnx {C Function} scm_vector_fill_x (v, fill)
817 Store @var{fill} in every position of @var{vector}. The value
818 returned by @code{vector-fill!} is unspecified.
821 @deffn {Scheme Procedure} vector-copy vec
822 @deffnx {C Function} scm_vector_copy (vec)
823 Return a copy of @var{vec}.
826 @deffn {Scheme Procedure} vector-move-left! vec1 start1 end1 vec2 start2
827 @deffnx {C Function} scm_vector_move_left_x (vec1, start1, end1, vec2, start2)
828 Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
829 to @var{vec2} starting at position @var{start2}. @var{start1} and
830 @var{start2} are inclusive indices; @var{end1} is exclusive.
832 @code{vector-move-left!} copies elements in leftmost order.
833 Therefore, in the case where @var{vec1} and @var{vec2} refer to the
834 same vector, @code{vector-move-left!} is usually appropriate when
835 @var{start1} is greater than @var{start2}.
838 @deffn {Scheme Procedure} vector-move-right! vec1 start1 end1 vec2 start2
839 @deffnx {C Function} scm_vector_move_right_x (vec1, start1, end1, vec2, start2)
840 Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
841 to @var{vec2} starting at position @var{start2}. @var{start1} and
842 @var{start2} are inclusive indices; @var{end1} is exclusive.
844 @code{vector-move-right!} copies elements in rightmost order.
845 Therefore, in the case where @var{vec1} and @var{vec2} refer to the
846 same vector, @code{vector-move-right!} is usually appropriate when
847 @var{start1} is less than @var{start2}.
850 @node Vector Accessing from C
851 @subsubsection Vector Accessing from C
853 A vector can be read and modified from C with the functions
854 @code{scm_c_vector_ref} and @code{scm_c_vector_set_x}, for example. In
855 addition to these functions, there are two more ways to access vectors
856 from C that might be more efficient in certain situations: you can
857 restrict yourself to @dfn{simple vectors} and then use the very fast
858 @emph{simple vector macros}; or you can use the very general framework
859 for accessing all kinds of arrays (@pxref{Accessing Arrays from C}),
860 which is more verbose, but can deal efficiently with all kinds of
861 vectors (and arrays). For vectors, you can use the
862 @code{scm_vector_elements} and @code{scm_vector_writable_elements}
863 functions as shortcuts.
865 @deftypefn {C Function} int scm_is_simple_vector (SCM obj)
866 Return non-zero if @var{obj} is a simple vector, else return zero. A
867 simple vector is a vector that can be used with the @code{SCM_SIMPLE_*}
870 The following functions are guaranteed to return simple vectors:
871 @code{scm_make_vector}, @code{scm_c_make_vector}, @code{scm_vector},
872 @code{scm_list_to_vector}.
875 @deftypefn {C Macro} size_t SCM_SIMPLE_VECTOR_LENGTH (SCM vec)
876 Evaluates to the length of the simple vector @var{vec}. No type
880 @deftypefn {C Macro} SCM SCM_SIMPLE_VECTOR_REF (SCM vec, size_t idx)
881 Evaluates to the element at position @var{idx} in the simple vector
882 @var{vec}. No type or range checking is done.
885 @deftypefn {C Macro} void SCM_SIMPLE_VECTOR_SET_X (SCM vec, size_t idx, SCM val)
886 Sets the element at position @var{idx} in the simple vector
887 @var{vec} to @var{val}. No type or range checking is done.
890 @deftypefn {C Function} {const SCM *} scm_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
891 Acquire a handle for the vector @var{vec} and return a pointer to the
892 elements of it. This pointer can only be used to read the elements of
893 @var{vec}. When @var{vec} is not a vector, an error is signaled. The
894 handle mustr eventually be released with
895 @code{scm_array_handle_release}.
897 The variables pointed to by @var{lenp} and @var{incp} are filled with
898 the number of elements of the vector and the increment between elements,
899 respectively. Note that the increment can well be negative.
901 The following example shows the typical way to use this function. It
902 creates a list of all elements of @code{vec} (in reverse order).
905 scm_t_array_handle handle;
911 elt = scm_vector_elements (vec, &handle, &len, &inc);
913 for (i = 0; i < len; i++, elt += inc)
914 list = scm_cons (*elt, list);
915 scm_array_handle_release (&handle);
920 @deftypefn {C Function} {SCM *} scm_vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
921 Like @code{scm_vector_elements} but the pointer can be used to modify
924 The following example shows the typical way to use this function. It
925 fills a vector with @code{#t}.
928 scm_t_array_handle handle;
933 elt = scm_vector_writable_elements (vec, &handle, &len, &inc);
934 for (i = 0; i < len; i++, elt += inc)
936 scm_array_handle_release (&handle);
941 @node Uniform Numeric Vectors
942 @subsection Uniform Numeric Vectors
944 A uniform numeric vector is a vector whose elements are all of a single
945 numeric type. Guile offers uniform numeric vectors for signed and
946 unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
947 floating point values, and complex floating-point numbers of these two
950 Strings could be regarded as uniform vectors of characters,
951 @xref{Strings}. Likewise, bit vectors could be regarded as uniform
952 vectors of bits, @xref{Bit Vectors}. Both are sufficiently different
953 from uniform numeric vectors that the procedures described here do not
954 apply to these two data types. However, both strings and bit vectors
955 are generalized vectors, @xref{Generalized Vectors}, and arrays,
958 Uniform numeric vectors are the special case of one dimensional uniform
961 Uniform numeric vectors can be useful since they consume less memory
962 than the non-uniform, general vectors. Also, since the types they can
963 store correspond directly to C types, it is easier to work with them
964 efficiently on a low level. Consider image processing as an example,
965 where you want to apply a filter to some image. While you could store
966 the pixels of an image in a general vector and write a general
967 convolution function, things are much more efficient with uniform
968 vectors: the convolution function knows that all pixels are unsigned
969 8-bit values (say), and can use a very tight inner loop.
971 That is, when it is written in C. Functions for efficiently working
972 with uniform numeric vectors from C are listed at the end of this
975 Procedures similar to the vector procedures (@pxref{Vectors}) are
976 provided for handling these uniform vectors, but they are distinct
977 datatypes and the two cannot be inter-mixed. If you want to work
978 primarily with uniform numeric vectors, but want to offer support for
979 general vectors as a convenience, you can use one of the
980 @code{scm_any_to_*} functions. They will coerce lists and vectors to
981 the given type of uniform vector. Alternatively, you can write two
982 versions of your code: one that is fast and works only with uniform
983 numeric vectors, and one that works with any kind of vector but is
986 One set of the procedures listed below is a generic one: it works with
987 all types of uniform numeric vectors. In addition to that, there is a
988 set of procedures for each type that only works with that type. Unless
989 you really need to the generality of the first set, it is best to use
990 the more specific functions. They might not be that much faster, but
991 their use can serve as a kind of declaration and makes it easier to
994 The generic set of procedures uses @code{uniform} in its names, the
995 specific ones use the tag from the following table.
999 unsigned 8-bit integers
1002 signed 8-bit integers
1005 unsigned 16-bit integers
1008 signed 16-bit integers
1011 unsigned 32-bit integers
1014 signed 32-bit integers
1017 unsigned 64-bit integers
1020 signed 64-bit integers
1023 the C type @code{float}
1026 the C type @code{double}
1029 complex numbers in rectangular form with the real and imaginary part
1030 being a @code{float}
1033 complex numbers in rectangular form with the real and imaginary part
1034 being a @code{double}
1038 The external representation (ie.@: read syntax) for these vectors is
1039 similar to normal Scheme vectors, but with an additional tag from the
1040 tabel above indiciating the vector's type. For example,
1047 Note that the read syntax for floating-point here conflicts with
1048 @code{#f} for false. In Standard Scheme one can write @code{(1 #f3)}
1049 for a three element list @code{(1 #f 3)}, but for Guile @code{(1 #f3)}
1050 is invalid. @code{(1 #f 3)} is almost certainly what one should write
1051 anyway to make the intention clear, so this is rarely a problem.
1053 @deffn {Scheme Procedure} uniform-vector? obj
1054 @deffnx {Scheme Procedure} u8vector? obj
1055 @deffnx {Scheme Procedure} s8vector? obj
1056 @deffnx {Scheme Procedure} u16vector? obj
1057 @deffnx {Scheme Procedure} s16vector? obj
1058 @deffnx {Scheme Procedure} u32vector? obj
1059 @deffnx {Scheme Procedure} s32vector? obj
1060 @deffnx {Scheme Procedure} u64vector? obj
1061 @deffnx {Scheme Procedure} s64vector? obj
1062 @deffnx {Scheme Procedure} f32vector? obj
1063 @deffnx {Scheme Procedure} f64vector? obj
1064 @deffnx {Scheme Procedure} c32vector? obj
1065 @deffnx {Scheme Procedure} c64vector? obj
1066 @deffnx {C Function} scm_uniform_vector_p (obj)
1067 @deffnx {C Function} scm_u8vector_p (obj)
1068 @deffnx {C Function} scm_s8vector_p (obj)
1069 @deffnx {C Function} scm_u16vector_p (obj)
1070 @deffnx {C Function} scm_s16vector_p (obj)
1071 @deffnx {C Function} scm_u32vector_p (obj)
1072 @deffnx {C Function} scm_s32vector_p (obj)
1073 @deffnx {C Function} scm_u64vector_p (obj)
1074 @deffnx {C Function} scm_s64vector_p (obj)
1075 @deffnx {C Function} scm_f32vector_p (obj)
1076 @deffnx {C Function} scm_f64vector_p (obj)
1077 @deffnx {C Function} scm_c32vector_p (obj)
1078 @deffnx {C Function} scm_c64vector_p (obj)
1079 Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
1083 @deffn {Scheme Procedure} make-u8vector n [value]
1084 @deffnx {Scheme Procedure} make-s8vector n [value]
1085 @deffnx {Scheme Procedure} make-u16vector n [value]
1086 @deffnx {Scheme Procedure} make-s16vector n [value]
1087 @deffnx {Scheme Procedure} make-u32vector n [value]
1088 @deffnx {Scheme Procedure} make-s32vector n [value]
1089 @deffnx {Scheme Procedure} make-u64vector n [value]
1090 @deffnx {Scheme Procedure} make-s64vector n [value]
1091 @deffnx {Scheme Procedure} make-f32vector n [value]
1092 @deffnx {Scheme Procedure} make-f64vector n [value]
1093 @deffnx {Scheme Procedure} make-c32vector n [value]
1094 @deffnx {Scheme Procedure} make-c64vector n [value]
1095 @deffnx {C Function} scm_make_u8vector n [value]
1096 @deffnx {C Function} scm_make_s8vector n [value]
1097 @deffnx {C Function} scm_make_u16vector n [value]
1098 @deffnx {C Function} scm_make_s16vector n [value]
1099 @deffnx {C Function} scm_make_u32vector n [value]
1100 @deffnx {C Function} scm_make_s32vector n [value]
1101 @deffnx {C Function} scm_make_u64vector n [value]
1102 @deffnx {C Function} scm_make_s64vector n [value]
1103 @deffnx {C Function} scm_make_f32vector n [value]
1104 @deffnx {C Function} scm_make_f64vector n [value]
1105 @deffnx {C Function} scm_make_c32vector n [value]
1106 @deffnx {C Function} scm_make_c64vector n [value]
1107 Return a newly allocated homogeneous numeric vector holding @var{n}
1108 elements of the indicated type. If @var{value} is given, the vector
1109 is initialized with that value, otherwise the contents are
1113 @deffn {Scheme Procedure} u8vector value @dots{}
1114 @deffnx {Scheme Procedure} s8vector value @dots{}
1115 @deffnx {Scheme Procedure} u16vector value @dots{}
1116 @deffnx {Scheme Procedure} s16vector value @dots{}
1117 @deffnx {Scheme Procedure} u32vector value @dots{}
1118 @deffnx {Scheme Procedure} s32vector value @dots{}
1119 @deffnx {Scheme Procedure} u64vector value @dots{}
1120 @deffnx {Scheme Procedure} s64vector value @dots{}
1121 @deffnx {Scheme Procedure} f32vector value @dots{}
1122 @deffnx {Scheme Procedure} f64vector value @dots{}
1123 @deffnx {Scheme Procedure} c32vector value @dots{}
1124 @deffnx {Scheme Procedure} c64vector value @dots{}
1125 @deffnx {C Function} scm_u8vector (values)
1126 @deffnx {C Function} scm_s8vector (values)
1127 @deffnx {C Function} scm_u16vector (values)
1128 @deffnx {C Function} scm_s16vector (values)
1129 @deffnx {C Function} scm_u32vector (values)
1130 @deffnx {C Function} scm_s32vector (values)
1131 @deffnx {C Function} scm_u64vector (values)
1132 @deffnx {C Function} scm_s64vector (values)
1133 @deffnx {C Function} scm_f32vector (values)
1134 @deffnx {C Function} scm_f64vector (values)
1135 @deffnx {C Function} scm_c32vector (values)
1136 @deffnx {C Function} scm_c64vector (values)
1137 Return a newly allocated homogeneous numeric vector of the indicated
1138 type, holding the given parameter @var{value}s. The vector length is
1139 the number of parameters given.
1142 @deffn {Scheme Procedure} uniform-vector-length vec
1143 @deffnx {Scheme Procedure} u8vector-length vec
1144 @deffnx {Scheme Procedure} s8vector-length vec
1145 @deffnx {Scheme Procedure} u16vector-length vec
1146 @deffnx {Scheme Procedure} s16vector-length vec
1147 @deffnx {Scheme Procedure} u32vector-length vec
1148 @deffnx {Scheme Procedure} s32vector-length vec
1149 @deffnx {Scheme Procedure} u64vector-length vec
1150 @deffnx {Scheme Procedure} s64vector-length vec
1151 @deffnx {Scheme Procedure} f32vector-length vec
1152 @deffnx {Scheme Procedure} f64vector-length vec
1153 @deffnx {Scheme Procedure} c32vector-length vec
1154 @deffnx {Scheme Procedure} c64vector-length vec
1155 @deffnx {C Function} scm_uniform_vector_length (vec)
1156 @deffnx {C Function} scm_u8vector_length (vec)
1157 @deffnx {C Function} scm_s8vector_length (vec)
1158 @deffnx {C Function} scm_u16vector_length (vec)
1159 @deffnx {C Function} scm_s16vector_length (vec)
1160 @deffnx {C Function} scm_u32vector_length (vec)
1161 @deffnx {C Function} scm_s32vector_length (vec)
1162 @deffnx {C Function} scm_u64vector_length (vec)
1163 @deffnx {C Function} scm_s64vector_length (vec)
1164 @deffnx {C Function} scm_f32vector_length (vec)
1165 @deffnx {C Function} scm_f64vector_length (vec)
1166 @deffnx {C Function} scm_c32vector_length (vec)
1167 @deffnx {C Function} scm_c64vector_length (vec)
1168 Return the number of elements in @var{vec}.
1171 @deffn {Scheme Procedure} uniform-vector-ref vec i
1172 @deffnx {Scheme Procedure} u8vector-ref vec i
1173 @deffnx {Scheme Procedure} s8vector-ref vec i
1174 @deffnx {Scheme Procedure} u16vector-ref vec i
1175 @deffnx {Scheme Procedure} s16vector-ref vec i
1176 @deffnx {Scheme Procedure} u32vector-ref vec i
1177 @deffnx {Scheme Procedure} s32vector-ref vec i
1178 @deffnx {Scheme Procedure} u64vector-ref vec i
1179 @deffnx {Scheme Procedure} s64vector-ref vec i
1180 @deffnx {Scheme Procedure} f32vector-ref vec i
1181 @deffnx {Scheme Procedure} f64vector-ref vec i
1182 @deffnx {Scheme Procedure} c32vector-ref vec i
1183 @deffnx {Scheme Procedure} c64vector-ref vec i
1184 @deffnx {C Function} scm_uniform_vector_ref (vec i)
1185 @deffnx {C Function} scm_u8vector_ref (vec i)
1186 @deffnx {C Function} scm_s8vector_ref (vec i)
1187 @deffnx {C Function} scm_u16vector_ref (vec i)
1188 @deffnx {C Function} scm_s16vector_ref (vec i)
1189 @deffnx {C Function} scm_u32vector_ref (vec i)
1190 @deffnx {C Function} scm_s32vector_ref (vec i)
1191 @deffnx {C Function} scm_u64vector_ref (vec i)
1192 @deffnx {C Function} scm_s64vector_ref (vec i)
1193 @deffnx {C Function} scm_f32vector_ref (vec i)
1194 @deffnx {C Function} scm_f64vector_ref (vec i)
1195 @deffnx {C Function} scm_c32vector_ref (vec i)
1196 @deffnx {C Function} scm_c64vector_ref (vec i)
1197 Return the element at index @var{i} in @var{vec}. The first element
1198 in @var{vec} is index 0.
1201 @deffn {Scheme Procedure} uniform-vector-set! vec i value
1202 @deffnx {Scheme Procedure} u8vector-set! vec i value
1203 @deffnx {Scheme Procedure} s8vector-set! vec i value
1204 @deffnx {Scheme Procedure} u16vector-set! vec i value
1205 @deffnx {Scheme Procedure} s16vector-set! vec i value
1206 @deffnx {Scheme Procedure} u32vector-set! vec i value
1207 @deffnx {Scheme Procedure} s32vector-set! vec i value
1208 @deffnx {Scheme Procedure} u64vector-set! vec i value
1209 @deffnx {Scheme Procedure} s64vector-set! vec i value
1210 @deffnx {Scheme Procedure} f32vector-set! vec i value
1211 @deffnx {Scheme Procedure} f64vector-set! vec i value
1212 @deffnx {Scheme Procedure} c32vector-set! vec i value
1213 @deffnx {Scheme Procedure} c64vector-set! vec i value
1214 @deffnx {C Function} scm_uniform_vector_set_x (vec i value)
1215 @deffnx {C Function} scm_u8vector_set_x (vec i value)
1216 @deffnx {C Function} scm_s8vector_set_x (vec i value)
1217 @deffnx {C Function} scm_u16vector_set_x (vec i value)
1218 @deffnx {C Function} scm_s16vector_set_x (vec i value)
1219 @deffnx {C Function} scm_u32vector_set_x (vec i value)
1220 @deffnx {C Function} scm_s32vector_set_x (vec i value)
1221 @deffnx {C Function} scm_u64vector_set_x (vec i value)
1222 @deffnx {C Function} scm_s64vector_set_x (vec i value)
1223 @deffnx {C Function} scm_f32vector_set_x (vec i value)
1224 @deffnx {C Function} scm_f64vector_set_x (vec i value)
1225 @deffnx {C Function} scm_c32vector_set_x (vec i value)
1226 @deffnx {C Function} scm_c64vector_set_x (vec i value)
1227 Set the element at index @var{i} in @var{vec} to @var{value}. The
1228 first element in @var{vec} is index 0. The return value is
1232 @deffn {Scheme Procedure} uniform-vector->list vec
1233 @deffnx {Scheme Procedure} u8vector->list vec
1234 @deffnx {Scheme Procedure} s8vector->list vec
1235 @deffnx {Scheme Procedure} u16vector->list vec
1236 @deffnx {Scheme Procedure} s16vector->list vec
1237 @deffnx {Scheme Procedure} u32vector->list vec
1238 @deffnx {Scheme Procedure} s32vector->list vec
1239 @deffnx {Scheme Procedure} u64vector->list vec
1240 @deffnx {Scheme Procedure} s64vector->list vec
1241 @deffnx {Scheme Procedure} f32vector->list vec
1242 @deffnx {Scheme Procedure} f64vector->list vec
1243 @deffnx {Scheme Procedure} c32vector->list vec
1244 @deffnx {Scheme Procedure} c64vector->list vec
1245 @deffnx {C Function} scm_uniform_vector_to_list (vec)
1246 @deffnx {C Function} scm_u8vector_to_list (vec)
1247 @deffnx {C Function} scm_s8vector_to_list (vec)
1248 @deffnx {C Function} scm_u16vector_to_list (vec)
1249 @deffnx {C Function} scm_s16vector_to_list (vec)
1250 @deffnx {C Function} scm_u32vector_to_list (vec)
1251 @deffnx {C Function} scm_s32vector_to_list (vec)
1252 @deffnx {C Function} scm_u64vector_to_list (vec)
1253 @deffnx {C Function} scm_s64vector_to_list (vec)
1254 @deffnx {C Function} scm_f32vector_to_list (vec)
1255 @deffnx {C Function} scm_f64vector_to_list (vec)
1256 @deffnx {C Function} scm_c32vector_to_list (vec)
1257 @deffnx {C Function} scm_c64vector_to_list (vec)
1258 Return a newly allocated list holding all elements of @var{vec}.
1261 @deffn {Scheme Procedure} list->u8vector lst
1262 @deffnx {Scheme Procedure} list->s8vector lst
1263 @deffnx {Scheme Procedure} list->u16vector lst
1264 @deffnx {Scheme Procedure} list->s16vector lst
1265 @deffnx {Scheme Procedure} list->u32vector lst
1266 @deffnx {Scheme Procedure} list->s32vector lst
1267 @deffnx {Scheme Procedure} list->u64vector lst
1268 @deffnx {Scheme Procedure} list->s64vector lst
1269 @deffnx {Scheme Procedure} list->f32vector lst
1270 @deffnx {Scheme Procedure} list->f64vector lst
1271 @deffnx {Scheme Procedure} list->c32vector lst
1272 @deffnx {Scheme Procedure} list->c64vector lst
1273 @deffnx {C Function} scm_list_to_u8vector (lst)
1274 @deffnx {C Function} scm_list_to_s8vector (lst)
1275 @deffnx {C Function} scm_list_to_u16vector (lst)
1276 @deffnx {C Function} scm_list_to_s16vector (lst)
1277 @deffnx {C Function} scm_list_to_u32vector (lst)
1278 @deffnx {C Function} scm_list_to_s32vector (lst)
1279 @deffnx {C Function} scm_list_to_u64vector (lst)
1280 @deffnx {C Function} scm_list_to_s64vector (lst)
1281 @deffnx {C Function} scm_list_to_f32vector (lst)
1282 @deffnx {C Function} scm_list_to_f64vector (lst)
1283 @deffnx {C Function} scm_list_to_c32vector (lst)
1284 @deffnx {C Function} scm_list_to_c64vector (lst)
1285 Return a newly allocated homogeneous numeric vector of the indicated type,
1286 initialized with the elements of the list @var{lst}.
1289 @deffn {Scheme Procedure} any->u8vector obj
1290 @deffnx {Scheme Procedure} any->s8vector obj
1291 @deffnx {Scheme Procedure} any->u16vector obj
1292 @deffnx {Scheme Procedure} any->s16vector obj
1293 @deffnx {Scheme Procedure} any->u32vector obj
1294 @deffnx {Scheme Procedure} any->s32vector obj
1295 @deffnx {Scheme Procedure} any->u64vector obj
1296 @deffnx {Scheme Procedure} any->s64vector obj
1297 @deffnx {Scheme Procedure} any->f32vector obj
1298 @deffnx {Scheme Procedure} any->f64vector obj
1299 @deffnx {Scheme Procedure} any->c32vector obj
1300 @deffnx {Scheme Procedure} any->c64vector obj
1301 @deffnx {C Function} scm_any_to_u8vector (obj)
1302 @deffnx {C Function} scm_any_to_s8vector (obj)
1303 @deffnx {C Function} scm_any_to_u16vector (obj)
1304 @deffnx {C Function} scm_any_to_s16vector (obj)
1305 @deffnx {C Function} scm_any_to_u32vector (obj)
1306 @deffnx {C Function} scm_any_to_s32vector (obj)
1307 @deffnx {C Function} scm_any_to_u64vector (obj)
1308 @deffnx {C Function} scm_any_to_s64vector (obj)
1309 @deffnx {C Function} scm_any_to_f32vector (obj)
1310 @deffnx {C Function} scm_any_to_f64vector (obj)
1311 @deffnx {C Function} scm_any_to_c32vector (obj)
1312 @deffnx {C Function} scm_any_to_c64vector (obj)
1313 Return a (maybe newly allocated) uniform numeric vector of the indicated
1314 type, initialized with the elements of @var{obj}, which must be a list,
1315 a vector, or a uniform vector. When @var{obj} is already a suitable
1316 uniform numeric vector, it is returned unchanged.
1319 @deftypefn {C Function} int scm_is_uniform_vector (SCM uvec)
1320 Return non-zero when @var{uvec} is a uniform numeric vector, zero
1324 @deftypefn {C Function} SCM scm_take_u8vector (const scm_t_uint8 *data, size_t len)
1325 @deftypefnx {C Function} SCM scm_take_s8vector (const scm_t_int8 *data, size_t len)
1326 @deftypefnx {C Function} SCM scm_take_u16vector (const scm_t_uint16 *data, size_t len)
1327 @deftypefnx {C Function} SCM scm_take_s168vector (const scm_t_int16 *data, size_t len)
1328 @deftypefnx {C Function} SCM scm_take_u32vector (const scm_t_uint32 *data, size_t len)
1329 @deftypefnx {C Function} SCM scm_take_s328vector (const scm_t_int32 *data, size_t len)
1330 @deftypefnx {C Function} SCM scm_take_u64vector (const scm_t_uint64 *data, size_t len)
1331 @deftypefnx {C Function} SCM scm_take_s64vector (const scm_t_int64 *data, size_t len)
1332 @deftypefnx {C Function} SCM scm_take_f32vector (const float *data, size_t len)
1333 @deftypefnx {C Function} SCM scm_take_f64vector (const double *data, size_t len)
1334 @deftypefnx {C Function} SCM scm_take_c32vector (const float *data, size_t len)
1335 @deftypefnx {C Function} SCM scm_take_c64vector (const double *data, size_t len)
1336 Return a new uniform numeric vector of the indicated type and length
1337 that uses the memory pointed to by @var{data} to store its elements.
1338 This memory will eventually be freed with @code{free}. The argument
1339 @var{len} specifies the number of elements in @var{data}, not its size
1342 The @code{c32} and @code{c64} variants take a pointer to a C array of
1343 @code{float}s or @code{double}s. The real parts of the complex numbers
1344 are at even indices in that array, the corresponding imaginary parts are
1345 at the following odd index.
1348 @deftypefn {C Function} size_t scm_c_uniform_vector_length (SCM uvec)
1349 Return the number of elements of @var{uvec} as a @code{size_t}.
1352 @deftypefn {C Function} {const void *} scm_uniform_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1353 @deftypefnx {C Function} {const scm_t_uint8 *} scm_u8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1354 @deftypefnx {C Function} {const scm_t_int8 *} scm_s8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1355 @deftypefnx {C Function} {const scm_t_uint16 *} scm_u16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1356 @deftypefnx {C Function} {const scm_t_int16 *} scm_s16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1357 @deftypefnx {C Function} {const scm_t_uint32 *} scm_u32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1358 @deftypefnx {C Function} {const scm_t_int32 *} scm_s32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1359 @deftypefnx {C Function} {const scm_t_uint64 *} scm_u64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1360 @deftypefnx {C Function} {const scm_t_int64 *} scm_s64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1361 @deftypefnx {C Function} {const float *} scm_f23vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1362 @deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1363 @deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1364 @deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1365 Like @code{scm_vector_elements} (which see), but returns a pointer to
1366 the elements of a uniform numeric vector of the indicated kind.
1369 @deftypefn {C Function} {void *} scm_uniform_vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1370 @deftypefnx {C Function} {scm_t_uint8 *} scm_u8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1371 @deftypefnx {C Function} {scm_t_int8 *} scm_s8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1372 @deftypefnx {C Function} {scm_t_uint16 *} scm_u16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1373 @deftypefnx {C Function} {scm_t_int16 *} scm_s16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1374 @deftypefnx {C Function} {scm_t_uint32 *} scm_u32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1375 @deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1376 @deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1377 @deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1378 @deftypefnx {C Function} {float *} scm_f23vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1379 @deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1380 @deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1381 @deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1382 Like @code{scm_vector_writable_elements} (which see), but returns a
1383 pointer to the elements of a uniform numeric vector of the indicated kind.
1386 @deffn {Scheme Procedure} uniform-vector-read! uvec [port_or_fd [start [end]]]
1387 @deffnx {C Function} scm_uniform_vector_read_x (uvec, port_or_fd, start, end)
1388 Fill the elements of @var{uvec} by reading
1389 raw bytes from @var{port-or-fdes}, using host byte order.
1391 The optional arguments @var{start} (inclusive) and @var{end}
1392 (exclusive) allow a specified region to be read,
1393 leaving the remainder of the vector unchanged.
1395 When @var{port-or-fdes} is a port, all specified elements
1396 of @var{uvec} are attempted to be read, potentially blocking
1397 while waiting formore input or end-of-file.
1398 When @var{port-or-fd} is an integer, a single call to
1401 An error is signalled when the last element has only
1402 been partially filled before reaching end-of-file or in
1403 the single call to read(2).
1405 @code{uniform-vector-read!} returns the number of elements
1408 @var{port-or-fdes} may be omitted, in which case it defaults
1409 to the value returned by @code{(current-input-port)}.
1412 @deffn {Scheme Procedure} uniform-vector-write uvec [port_or_fd [start [end]]]
1413 @deffnx {C Function} scm_uniform_vector_write (uvec, port_or_fd, start, end)
1414 Write the elements of @var{uvec} as raw bytes to
1415 @var{port-or-fdes}, in the host byte order.
1417 The optional arguments @var{start} (inclusive)
1418 and @var{end} (exclusive) allow
1419 a specified region to be written.
1421 When @var{port-or-fdes} is a port, all specified elements
1422 of @var{uvec} are attempted to be written, potentially blocking
1423 while waiting for more room.
1424 When @var{port-or-fd} is an integer, a single call to
1427 An error is signalled when the last element has only
1428 been partially written in the single call to write(2).
1430 The number of objects actually written is returned.
1431 @var{port-or-fdes} may be
1432 omitted, in which case it defaults to the value returned by
1433 @code{(current-output-port)}.
1438 @subsection Bit Vectors
1441 Bit vectors are zero-origin, one-dimensional arrays of booleans. They
1442 are displayed as a sequence of @code{0}s and @code{1}s prefixed by
1446 (make-bitvector 8 #f) @result{}
1450 Bit vectors are are also generalized vectors, @xref{Generalized
1451 Vectors}, and can thus be used with the array procedures, @xref{Arrays}.
1452 Bit vectors are the special case of one dimensional bit arrays.
1454 @deffn {Scheme Procedure} bitvector? obj
1455 @deffnx {C Function} scm_bitvector_p (obj)
1456 Return @code{#t} when @var{obj} is a bitvector, else
1460 @deftypefn {C Function} int scm_is_bitvector (SCM obj)
1461 Return @code{1} when @var{obj} is a bitvector, else return @code{0}.
1464 @deffn {Scheme Procedure} make-bitvector len [fill]
1465 @deffnx {C Function} scm_make_bitvector (len, fill)
1466 Create a new bitvector of length @var{len} and
1467 optionally initialize all elements to @var{fill}.
1470 @deftypefn {C Function} SCM scm_c_make_bitvector (size_t len, SCM fill)
1471 Like @code{scm_make_bitvector}, but the length is given as a
1475 @deffn {Scheme Procedure} bitvector . bits
1476 @deffnx {C Function} scm_bitvector (bits)
1477 Create a new bitvector with the arguments as elements.
1480 @deffn {Scheme Procedure} bitvector-length vec
1481 @deffnx {C Function} scm_bitvector_length (vec)
1482 Return the length of the bitvector @var{vec}.
1485 @deftypefn {C Function} size_t scm_c_bitvector_length (SCM vec)
1486 Like @code{scm_bitvector_length}, but the length is returned as a
1490 @deffn {Scheme Procedure} bitvector-ref vec idx
1491 @deffnx {C Function} scm_bitvector_ref (vec, idx)
1492 Return the element at index @var{idx} of the bitvector
1496 @deftypefn {C Function} SCM scm_c_bitvector_ref (SCM obj, size_t idx)
1497 Return the element at index @var{idx} of the bitvector
1501 @deffn {Scheme Procedure} bitvector-set! vec idx val
1502 @deffnx {C Function} scm_bitvector_set_x (vec, idx, val)
1503 Set the element at index @var{idx} of the bitvector
1504 @var{vec} when @var{val} is true, else clear it.
1507 @deftypefn {C Function} SCM scm_c_bitvector_set_x (SCM obj, size_t idx, SCM val)
1508 Set the element at index @var{idx} of the bitvector
1509 @var{vec} when @var{val} is true, else clear it.
1512 @deffn {Scheme Procedure} bitvector-fill! vec val
1513 @deffnx {C Function} scm_bitvector_fill_x (vec, val)
1514 Set all elements of the bitvector
1515 @var{vec} when @var{val} is true, else clear them.
1518 @deffn {Scheme Procedure} list->bitvector list
1519 @deffnx {C Function} scm_list_to_bitvector (list)
1520 Return a new bitvector initialized with the elements
1524 @deffn {Scheme Procedure} bitvector->list vec
1525 @deffnx {C Function} scm_bitvector_to_list (vec)
1526 Return a new list initialized with the elements
1527 of the bitvector @var{vec}.
1530 @deffn {Scheme Procedure} bit-count bool bitvector
1531 @deffnx {C Function} scm_bit_count (bool, bitvector)
1532 Return a count of how many entries in @var{bitvector} are equal to
1533 @var{bool}. For example,
1536 (bit-count #f #*000111000) @result{} 6
1540 @deffn {Scheme Procedure} bit-position bool bitvector start
1541 @deffnx {C Function} scm_bit_position (bool, bitvector, start)
1542 Return the index of the first occurrance of @var{bool} in
1543 @var{bitvector}, starting from @var{start}. If there is no @var{bool}
1544 entry between @var{start} and the end of @var{bitvector}, then return
1545 @code{#f}. For example,
1548 (bit-position #t #*000101 0) @result{} 3
1549 (bit-position #f #*0001111 3) @result{} #f
1553 @deffn {Scheme Procedure} bit-invert! bitvector
1554 @deffnx {C Function} scm_bit_invert_x (bitvector)
1555 Modify @var{bitvector} by replacing each element with its negation.
1558 @deffn {Scheme Procedure} bit-set*! bitvector uvec bool
1559 @deffnx {C Function} scm_bit_set_star_x (bitvector, uvec, bool)
1560 Set entries of @var{bitvector} to @var{bool}, with @var{uvec}
1561 selecting the entries to change. The return value is unspecified.
1563 If @var{uvec} is a bit vector, then those entries where it has
1564 @code{#t} are the ones in @var{bitvector} which are set to @var{bool}.
1565 @var{uvec} and @var{bitvector} must be the same length. When
1566 @var{bool} is @code{#t} it's like @var{uvec} is OR'ed into
1567 @var{bitvector}. Or when @var{bool} is @code{#f} it can be seen as an
1571 (define bv #*01000010)
1572 (bit-set*! bv #*10010001 #t)
1574 @result{} #*11010011
1577 If @var{uvec} is a uniform vector of unsigned long integers, then
1578 they're indexes into @var{bitvector} which are set to @var{bool}.
1581 (define bv #*01000010)
1582 (bit-set*! bv #u(5 2 7) #t)
1584 @result{} #*01100111
1588 @deffn {Scheme Procedure} bit-count* bitvector uvec bool
1589 @deffnx {C Function} scm_bit_count_star (bitvector, uvec, bool)
1590 Return a count of how many entries in @var{bitvector} are equal to
1591 @var{bool}, with @var{uvec} selecting the entries to consider.
1593 @var{uvec} is interpreted in the same way as for @code{bit-set*!}
1594 above. Namely, if @var{uvec} is a bit vector then entries which have
1595 @code{#t} there are considered in @var{bitvector}. Or if @var{uvec}
1596 is a uniform vector of unsigned long integers then it's the indexes in
1597 @var{bitvector} to consider.
1602 (bit-count* #*01110111 #*11001101 #t) @result{} 3
1603 (bit-count* #*01110111 #u(7 0 4) #f) @result{} 2
1607 @deftypefn {C Function} {const scm_t_uint32 *} scm_bitvector_elements (SCM vec, scm_t_array_handle *handle, size_t *offp, size_t *lenp, ssize_t *incp)
1608 Like @code{scm_vector_elements} (which see), but for bitvectors. The
1609 variable pointed to by @var{offp} is set to the value returned by
1610 @code{scm_array_handle_bit_elements_offset}. See
1611 @code{scm_array_handle_bit_elements} for how to use the returned pointer
1615 @deftypefn {C Function} {scm_t_uint32 *} scm_bitvector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *offp, size_t *lenp, ssize_t *incp)
1616 Like @code{scm_bitvector_elements}, but the pointer is good for reading
1620 @node Generalized Vectors
1621 @subsection Generalized Vectors
1623 Guile has a number of data types that are generally vector-like:
1624 strings, uniform numeric vectors, bitvectors, and of course ordinary
1625 vectors of arbitrary Scheme values. These types are disjoint: a
1626 Scheme value belongs to at most one of the four types listed above.
1628 If you want to gloss over this distinction and want to treat all four
1629 types with common code, you can use the procedures in this section.
1630 They work with the @emph{generalized vector} type, which is the union
1631 of the four vector-like types.
1633 @deffn {Scheme Procedure} generalized-vector? obj
1634 @deffnx {C Function} scm_generalized_vector_p (obj)
1635 Return @code{#t} if @var{obj} is a vector, string,
1636 bitvector, or uniform numeric vector.
1639 @deffn {Scheme Procedure} generalized-vector-length v
1640 @deffnx {C Function} scm_generalized_vector_length (v)
1641 Return the length of the generalized vector @var{v}.
1644 @deffn {Scheme Procedure} generalized-vector-ref v idx
1645 @deffnx {C Function} scm_generalized_vector_ref (v, idx)
1646 Return the element at index @var{idx} of the
1647 generalized vector @var{v}.
1650 @deffn {Scheme Procedure} generalized-vector-set! v idx val
1651 @deffnx {C Function} scm_generalized_vector_set_x (v, idx, val)
1652 Set the element at index @var{idx} of the
1653 generalized vector @var{v} to @var{val}.
1656 @deffn {Scheme Procedure} generalized-vector->list v
1657 @deffnx {C Function} scm_generalized_vector_to_list (v)
1658 Return a new list whose elements are the elements of the
1659 generalized vector @var{v}.
1662 @deftypefn {C Function} int scm_is_generalized_vector (SCM obj)
1663 Return @code{1} if @var{obj} is a vector, string,
1664 bitvector, or uniform numeric vector; else return @code{0}.
1667 @deftypefn {C Function} size_t scm_c_generalized_vector_length (SCM v)
1668 Return the length of the generalized vector @var{v}.
1671 @deftypefn {C Function} SCM scm_c_generalized_vector_ref (SCM v, size_t idx)
1672 Return the element at index @var{idx} of the generalized vector @var{v}.
1675 @deftypefn {C Function} void scm_c_generalized_vector_set_x (SCM v, size_t idx, SCM val)
1676 Set the element at index @var{idx} of the generalized vector @var{v}
1680 @deftypefn {C Function} void scm_generalized_vector_get_handle (SCM v, scm_t_array_handle *handle)
1681 Like @code{scm_array_get_handle} but an error is signalled when @var{v}
1682 is not of rank one. You can use @code{scm_array_handle_ref} and
1683 @code{scm_array_handle_set} to read and write the elements of @var{v},
1684 or you can use functions like @code{scm_array_handle_<foo>_elements} to
1685 deal with specific types of vectors.
1692 @dfn{Arrays} are a collection of cells organized into an arbitrary
1693 number of dimensions. Each cell can be accessed in constant time by
1694 supplying an index for each dimension.
1696 In the current implementation, an array uses a generalized vector for
1697 the actual storage of its elements. Any kind of generalized vector
1698 will do, so you can have arrays of uniform numeric values, arrays of
1699 characters, arrays of bits, and of course, arrays of arbitrary Scheme
1700 values. For example, arrays with an underlying @code{c64vector} might
1701 be nice for digital signal processing, while arrays made from a
1702 @code{u8vector} might be used to hold gray-scale images.
1704 The number of dimensions of an array is called its @dfn{rank}. Thus,
1705 a matrix is an array of rank 2, while a vector has rank 1. When
1706 accessing an array element, you have to specify one exact integer for
1707 each dimension. These integers are called the @dfn{indices} of the
1708 element. An array specifies the allowed range of indices for each
1709 dimension via an inclusive lower and upper bound. These bounds can
1710 well be negative, but the upper bound must be greater than or equal to
1711 the lower bound minus one. When all lower bounds of an array are
1712 zero, it is called a @dfn{zero-origin} array.
1714 Arrays can be of rank 0, which could be interpreted as a scalar.
1715 Thus, a zero-rank array can store exactly one object and the list of
1716 indices of this element is the empty list.
1718 Arrays contain zero elements when one of their dimensions has a zero
1719 length. These empty arrays maintain information about their shape: a
1720 matrix with zero columns and 3 rows is different from a matrix with 3
1721 columns and zero rows, which again is different from a vector of
1724 Generalized vectors, such as strings, uniform numeric vectors, bit
1725 vectors and ordinary vectors, are the special case of one dimensional
1730 * Array Procedures::
1732 * Accessing Arrays from C::
1736 @subsubsection Array Syntax
1738 An array is displayed as @code{#} followed by its rank, followed by a
1739 tag that describes the underlying vector, optionally followed by
1740 information about its shape, and finally followed by the cells,
1741 organized into dimensions using parentheses.
1743 In more words, the array tag is of the form
1746 #<rank><vectag><@@lower><:len><@@lower><:len>...
1749 where @code{<rank>} is a positive integer in decimal giving the rank of
1750 the array. It is omitted when the rank is 1 and the array is non-shared
1751 and has zero-origin (see below). For shared arrays and for a non-zero
1752 origin, the rank is always printed even when it is 1 to dinstinguish
1753 them from ordinary vectors.
1755 The @code{<vectag>} part is the tag for a uniform numeric vector, like
1756 @code{u8}, @code{s16}, etc, @code{b} for bitvectors, or @code{a} for
1757 strings. It is empty for ordinary vectors.
1759 The @code{<@@lower>} part is a @samp{@@} character followed by a signed
1760 integer in decimal giving the lower bound of a dimension. There is one
1761 @code{<@@lower>} for each dimension. When all lower bounds are zero,
1762 all @code{<@@lower>} parts are omitted.
1764 The @code{<:len>} part is a @samp{:} character followed by an unsigned
1765 integer in decimal giving the length of a dimension. Like for the lower
1766 bounds, there is one @code{<:len>} for each dimension, and the
1767 @code{<:len>} part always follows the @code{<@@lower>} part for a
1768 dimension. Lengths are only then printed when they can't be deduced
1769 from the nested lists of elements of the array literal, which can happen
1770 when at least one length is zero.
1772 As a special case, an array of rank 0 is printed as
1773 @code{#0<vectag>(<scalar>)}, where @code{<scalar>} is the result of
1774 printing the single element of the array.
1780 is an ordinary array of rank 1 with lower bound 0 in dimension 0.
1781 (I.e., a regular vector.)
1784 is an ordinary array of rank 1 with lower bound 2 in dimension 0.
1786 @item #2((1 2 3) (4 5 6))
1787 is a non-uniform array of rank 2; a 3@cross{}3 matrix with index ranges 0..2
1791 is a uniform u8 array of rank 1.
1793 @item #2u32@@2@@3((1 2) (2 3))
1794 is a uniform u8 array of rank 2 with index ranges 2..3 and 3..4.
1797 is a two-dimensional array with index ranges 0..-1 and 0..-1, i.e. both
1798 dimensions have length zero.
1801 is a two-dimensional array with index ranges 0..-1 and 0..1, i.e. the
1802 first dimension has length zero, but the second has length 2.
1805 is a rank-zero array with contents 12.
1809 @node Array Procedures
1810 @subsubsection Array Procedures
1812 When an array is created, the range of each dimension must be
1813 specified, e.g., to create a 2@cross{}3 array with a zero-based index:
1816 (make-array 'ho 2 3) @result{} #2((ho ho ho) (ho ho ho))
1819 The range of each dimension can also be given explicitly, e.g., another
1820 way to create the same array:
1823 (make-array 'ho '(0 1) '(0 2)) @result{} #2((ho ho ho) (ho ho ho))
1826 The following procedures can be used with arrays (or vectors). An
1827 argument shown as @var{idx}@dots{} means one parameter for each
1828 dimension in the array. A @var{idxlist} argument means a list of such
1829 values, one for each dimension.
1832 @deffn {Scheme Procedure} array? obj
1833 @deffnx {C Function} scm_array_p (obj, unused)
1834 Return @code{#t} if the @var{obj} is an array, and @code{#f} if
1837 The second argument to scm_array_p is there for historical reasons,
1838 but it is not used. You should always pass @code{SCM_UNDEFINED} as
1842 @deffn {Scheme Procedure} typed-array? obj type
1843 @deffnx {C Function} scm_typed_array_p (obj, type)
1844 Return @code{#t} if the @var{obj} is an array of type @var{type}, and
1848 @deftypefn {C Function} int scm_is_array (SCM obj)
1849 Return @code{1} if the @var{obj} is an array and @code{0} if not.
1852 @deftypefn {C Function} int scm_is_typed_array (SCM obj, SCM type)
1853 Return @code{0} if the @var{obj} is an array of type @var{type}, and
1857 @deffn {Scheme Procedure} make-array fill bound @dots{}
1858 @deffnx {C Function} scm_make_array (fill, bounds)
1859 Equivalent to @code{(make-typed-array #t @var{fill} @var{bound} ...)}.
1862 @deffn {Scheme Procedure} make-typed-array type fill bound @dots{}
1863 @deffnx {C Function} scm_make_typed_array (type, fill, bounds)
1864 Create and return an array that has as many dimensions as there are
1865 @var{bound}s and (maybe) fill it with @var{fill}.
1867 The underlaying storage vector is created according to @var{type},
1868 which must be a symbol whose name is the `vectag' of the array as
1869 explained above, or @code{#t} for ordinary, non-specialized arrays.
1871 For example, using the symbol @code{f64} for @var{type} will create an
1872 array that uses a @code{f64vector} for storing its elements, and
1873 @code{a} will use a string.
1875 When @var{fill} is not the special @emph{unspecified} value, the new
1876 array is filled with @var{fill}. Otherwise, the initial contents of
1877 the array is unspecified. The special @emph{unspecified} value is
1878 stored in the variable @code{*unspecified*} so that for example
1879 @code{(make-typed-array 'u32 *unspecified* 4)} creates a uninitialized
1880 @code{u32} vector of length 4.
1882 Each @var{bound} may be a positive non-zero integer @var{N}, in which
1883 case the index for that dimension can range from 0 through @var{N-1}; or
1884 an explicit index range specifier in the form @code{(LOWER UPPER)},
1885 where both @var{lower} and @var{upper} are integers, possibly less than
1886 zero, and possibly the same number (however, @var{lower} cannot be
1887 greater than @var{upper}).
1890 @deffn {Scheme Procedure} list->array dimspec list
1891 Equivalent to @code{(list->typed-array #t @var{dimspec}
1895 @deffn {Scheme Procedure} list->typed-array type dimspec list
1896 @deffnx {C Function} scm_list_to_typed_array (type, dimspec, list)
1897 Return an array of the type indicated by @var{type} with elements the
1898 same as those of @var{list}.
1900 The argument @var{dimspec} determines the number of dimensions of the
1901 array and their lower bounds. When @var{dimspec} is an exact integer,
1902 it gives the number of dimensions directly and all lower bounds are
1903 zero. When it is a list of exact integers, then each element is the
1904 lower index bound of a dimension, and there will be as many dimensions
1905 as elements in the list.
1908 @deffn {Scheme Procedure} array-type array
1909 Return the type of @var{array}. This is the `vectag' used for
1910 printing @var{array} (or @code{#t} for ordinary arrays) and can be
1911 used with @code{make-typed-array} to create an array of the same kind
1915 @deffn {Scheme Procedure} array-ref array idx @dots{}
1916 Return the element at @code{(idx @dots{})} in @var{array}.
1919 (define a (make-array 999 '(1 2) '(3 4)))
1920 (array-ref a 2 4) @result{} 999
1924 @deffn {Scheme Procedure} array-in-bounds? array idx @dots{}
1925 @deffnx {C Function} scm_array_in_bounds_p (array, idxlist)
1926 Return @code{#t} if the given index would be acceptable to
1930 (define a (make-array #f '(1 2) '(3 4)))
1931 (array-in-bounds? a 2 3) @result{} #f
1932 (array-in-bounds? a 0 0) @result{} #f
1936 @deffn {Scheme Procedure} array-set! array obj idx @dots{}
1937 @deffnx {C Function} scm_array_set_x (array, obj, idxlist)
1938 Set the element at @code{(idx @dots{})} in @var{array} to @var{obj}.
1939 The return value is unspecified.
1942 (define a (make-array #f '(0 1) '(0 1)))
1943 (array-set! a #t 1 1)
1944 a @result{} #2((#f #f) (#f #t))
1948 @deffn {Scheme Procedure} enclose-array array dim1 @dots{}
1949 @deffnx {C Function} scm_enclose_array (array, dimlist)
1950 @var{dim1}, @var{dim2} @dots{} should be nonnegative integers less than
1951 the rank of @var{array}. @code{enclose-array} returns an array
1952 resembling an array of shared arrays. The dimensions of each shared
1953 array are the same as the @var{dim}th dimensions of the original array,
1954 the dimensions of the outer array are the same as those of the original
1955 array that did not match a @var{dim}.
1957 An enclosed array is not a general Scheme array. Its elements may not
1958 be set using @code{array-set!}. Two references to the same element of
1959 an enclosed array will be @code{equal?} but will not in general be
1960 @code{eq?}. The value returned by @code{array-prototype} when given an
1961 enclosed array is unspecified.
1966 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1)
1968 #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
1970 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0)
1972 #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
1976 @deffn {Scheme Procedure} array-shape array
1977 @deffnx {Scheme Procedure} array-dimensions array
1978 @deffnx {C Function} scm_array_dimensions (array)
1979 Return a list of the bounds for each dimenson of @var{array}.
1981 @code{array-shape} gives @code{(@var{lower} @var{upper})} for each
1982 dimension. @code{array-dimensions} instead returns just
1983 @math{@var{upper}+1} for dimensions with a 0 lower bound. Both are
1984 suitable as input to @code{make-array}.
1989 (define a (make-array 'foo '(-1 3) 5))
1990 (array-shape a) @result{} ((-1 3) (0 4))
1991 (array-dimensions a) @result{} ((-1 3) 5)
1995 @deffn {Scheme Procedure} array-rank obj
1996 @deffnx {C Function} scm_array_rank (obj)
1997 Return the rank of @var{array}.
2000 @deftypefn {C Function} size_t scm_c_array_rank (SCM array)
2001 Return the rank of @var{array} as a @code{size_t}.
2004 @deffn {Scheme Procedure} array->list array
2005 @deffnx {C Function} scm_array_to_list (array)
2006 Return a list consisting of all the elements, in order, of
2010 @c FIXME: Describe how the order affects the copying (it matters for
2011 @c shared arrays with the same underlying root vector, presumably).
2013 @deffn {Scheme Procedure} array-copy! src dst
2014 @deffnx {Scheme Procedure} array-copy-in-order! src dst
2015 @deffnx {C Function} scm_array_copy_x (src, dst)
2016 Copy every element from vector or array @var{src} to the corresponding
2017 element of @var{dst}. @var{dst} must have the same rank as @var{src},
2018 and be at least as large in each dimension. The return value is
2022 @deffn {Scheme Procedure} array-fill! array fill
2023 @deffnx {C Function} scm_array_fill_x (array, fill)
2024 Store @var{fill} in every element of @var{array}. The value returned
2028 @c begin (texi-doc-string "guile" "array-equal?")
2029 @deffn {Scheme Procedure} array-equal? array1 array2 @dots{}
2030 Return @code{#t} if all arguments are arrays with the same shape, the
2031 same type, and have corresponding elements which are either
2032 @code{equal?} or @code{array-equal?}. This function differs from
2033 @code{equal?} in that a one dimensional shared array may be
2034 @var{array-equal?} but not @var{equal?} to a vector or uniform vector.
2037 @c FIXME: array-map! accepts no source arrays at all, and in that
2038 @c case makes calls "(proc)". Is that meant to be a documented
2041 @c FIXME: array-for-each doesn't say what happens if the sources have
2042 @c different index ranges. The code currently iterates over the
2043 @c indices of the first and expects the others to cover those. That
2044 @c at least vaguely matches array-map!, but is is meant to be a
2045 @c documented feature?
2047 @deffn {Scheme Procedure} array-map! dst proc src1 @dots{} srcN
2048 @deffnx {Scheme Procedure} array-map-in-order! dst proc src1 @dots{} srcN
2049 @deffnx {C Function} scm_array_map_x (dst, proc, srclist)
2050 Set each element of the @var{dst} array to values obtained from calls
2051 to @var{proc}. The value returned is unspecified.
2053 Each call is @code{(@var{proc} @var{elem1} @dots{} @var{elemN})},
2054 where each @var{elem} is from the corresponding @var{src} array, at
2055 the @var{dst} index. @code{array-map-in-order!} makes the calls in
2056 row-major order, @code{array-map!} makes them in an unspecified order.
2058 The @var{src} arrays must have the same number of dimensions as
2059 @var{dst}, and must have a range for each dimension which covers the
2060 range in @var{dst}. This ensures all @var{dst} indices are valid in
2064 @deffn {Scheme Procedure} array-for-each proc src1 @dots{} srcN
2065 @deffnx {C Function} scm_array_for_each (proc, src1, srclist)
2066 Apply @var{proc} to each tuple of elements of @var{src1} @dots{}
2067 @var{srcN}, in row-major order. The value returned is unspecified.
2070 @deffn {Scheme Procedure} array-index-map! dst proc
2071 @deffnx {C Function} scm_array_index_map_x (dst, proc)
2072 Set each element of the @var{dst} array to values returned by calls to
2073 @var{proc}. The value returned is unspecified.
2075 Each call is @code{(@var{proc} @var{i1} @dots{} @var{iN})}, where
2076 @var{i1}@dots{}@var{iN} is the destination index, one parameter for
2077 each dimension. The order in which the calls are made is unspecified.
2079 For example, to create a @m{4\times4, 4x4} matrix representing a
2083 \advance\leftskip by 2\lispnarrowing {
2101 (define a (make-array #f 4 4))
2102 (array-index-map! a (lambda (i j)
2103 (modulo (+ i j) 4)))
2107 @deffn {Scheme Procedure} uniform-array-read! ra [port_or_fd [start [end]]]
2108 @deffnx {C Function} scm_uniform_array_read_x (ra, port_or_fd, start, end)
2109 Attempt to read all elements of @var{ura}, in lexicographic order, as
2110 binary objects from @var{port-or-fdes}.
2111 If an end of file is encountered,
2112 the objects up to that point are put into @var{ura}
2113 (starting at the beginning) and the remainder of the array is
2116 The optional arguments @var{start} and @var{end} allow
2117 a specified region of a vector (or linearized array) to be read,
2118 leaving the remainder of the vector unchanged.
2120 @code{uniform-array-read!} returns the number of objects read.
2121 @var{port-or-fdes} may be omitted, in which case it defaults to the value
2122 returned by @code{(current-input-port)}.
2125 @deffn {Scheme Procedure} uniform-array-write v [port_or_fd [start [end]]]
2126 @deffnx {C Function} scm_uniform_array_write (v, port_or_fd, start, end)
2127 Writes all elements of @var{ura} as binary objects to
2130 The optional arguments @var{start}
2132 a specified region of a vector (or linearized array) to be written.
2134 The number of objects actually written is returned.
2135 @var{port-or-fdes} may be
2136 omitted, in which case it defaults to the value returned by
2137 @code{(current-output-port)}.
2141 @subsubsection Shared Arrays
2143 @deffn {Scheme Procedure} make-shared-array oldarray mapfunc bound @dots{}
2144 @deffnx {C Function} scm_make_shared_array (oldarray, mapfunc, boundlist)
2145 Return a new array which shares the storage of @var{oldarray}.
2146 Changes made through either affect the same underlying storage. The
2147 @var{bound@dots{}} arguments are the shape of the new array, the same
2148 as @code{make-array} (@pxref{Array Procedures}).
2150 @var{mapfunc} translates coordinates from the new array to the
2151 @var{oldarray}. It's called as @code{(@var{mapfunc} newidx1 @dots{})}
2152 with one parameter for each dimension of the new array, and should
2153 return a list of indices for @var{oldarray}, one for each dimension of
2156 @var{mapfunc} must be affine linear, meaning that each @var{oldarray}
2157 index must be formed by adding integer multiples (possibly negative)
2158 of some or all of @var{newidx1} etc, plus a possible integer offset.
2159 The multiples and offset must be the same in each call.
2162 One good use for a shared array is to restrict the range of some
2163 dimensions, so as to apply say @code{array-for-each} or
2164 @code{array-fill!} to only part of an array. The plain @code{list}
2165 function can be used for @var{mapfunc} in this case, making no changes
2166 to the index values. For example,
2169 (make-shared-array #2((a b c) (d e f) (g h i)) list 3 2)
2170 @result{} #2((a b) (d e) (g h))
2173 The new array can have fewer dimensions than @var{oldarray}, for
2174 example to take a column from an array.
2177 (make-shared-array #2((a b c) (d e f) (g h i))
2178 (lambda (i) (list i 2))
2183 A diagonal can be taken by using the single new array index for both
2184 row and column in the old array. For example,
2187 (make-shared-array #2((a b c) (d e f) (g h i))
2188 (lambda (i) (list i i))
2193 Dimensions can be increased by for instance considering portions of a
2194 one dimensional array as rows in a two dimensional array.
2195 (@code{array-contents} below can do the opposite, flattening an
2199 (make-shared-array #1(a b c d e f g h i j k l)
2200 (lambda (i j) (list (+ (* i 3) j)))
2202 @result{} #2((a b c) (d e f) (g h i) (j k l))
2205 By negating an index the order that elements appear can be reversed.
2206 The following just reverses the column order,
2209 (make-shared-array #2((a b c) (d e f) (g h i))
2210 (lambda (i j) (list i (- 2 j)))
2212 @result{} #2((c b a) (f e d) (i h g))
2215 A fixed offset on indexes allows for instance a change from a 0 based
2219 (define x #2((a b c) (d e f) (g h i)))
2220 (define y (make-shared-array x
2221 (lambda (i j) (list (1- i) (1- j)))
2223 (array-ref x 0 0) @result{} a
2224 (array-ref y 1 1) @result{} a
2227 A multiple on an index allows every Nth element of an array to be
2228 taken. The following is every third element,
2231 (make-shared-array #1(a b c d e f g h i j k l)
2232 (lambda (i) (* i 3))
2234 @result{} #1(a d g j)
2237 The above examples can be combined to make weird and wonderful
2238 selections from an array, but it's important to note that because
2239 @var{mapfunc} must be affine linear, arbitrary permutations are not
2242 In the current implementation, @var{mapfunc} is not called for every
2243 access to the new array but only on some sample points to establish a
2244 base and stride for new array indices in @var{oldarray} data. A few
2245 sample points are enough because @var{mapfunc} is linear.
2248 @deffn {Scheme Procedure} shared-array-increments array
2249 @deffnx {C Function} scm_shared_array_increments (array)
2250 For each dimension, return the distance between elements in the root vector.
2253 @deffn {Scheme Procedure} shared-array-offset array
2254 @deffnx {C Function} scm_shared_array_offset (array)
2255 Return the root vector index of the first element in the array.
2258 @deffn {Scheme Procedure} shared-array-root array
2259 @deffnx {C Function} scm_shared_array_root (array)
2260 Return the root vector of a shared array.
2263 @deffn {Scheme Procedure} array-contents array [strict]
2264 @deffnx {C Function} scm_array_contents (array, strict)
2265 If @var{array} may be @dfn{unrolled} into a one dimensional shared array
2266 without changing their order (last subscript changing fastest), then
2267 @code{array-contents} returns that shared array, otherwise it returns
2268 @code{#f}. All arrays made by @code{make-array} and
2269 @code{make-typed-array} may be unrolled, some arrays made by
2270 @code{make-shared-array} may not be.
2272 If the optional argument @var{strict} is provided, a shared array will
2273 be returned only if its elements are stored internally contiguous in
2277 @deffn {Scheme Procedure} transpose-array array dim1 @dots{}
2278 @deffnx {C Function} scm_transpose_array (array, dimlist)
2279 Return an array sharing contents with @var{array}, but with
2280 dimensions arranged in a different order. There must be one
2281 @var{dim} argument for each dimension of @var{array}.
2282 @var{dim1}, @var{dim2}, @dots{} should be integers between 0
2283 and the rank of the array to be returned. Each integer in that
2284 range must appear at least once in the argument list.
2286 The values of @var{dim1}, @var{dim2}, @dots{} correspond to
2287 dimensions in the array to be returned, and their positions in the
2288 argument list to dimensions of @var{array}. Several @var{dim}s
2289 may have the same value, in which case the returned array will
2290 have smaller rank than @var{array}.
2293 (transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
2294 (transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
2295 (transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
2296 #2((a 4) (b 5) (c 6))
2300 @node Accessing Arrays from C
2301 @subsubsection Accessing Arrays from C
2303 Arrays, especially uniform numeric arrays, are useful to efficiently
2304 represent large amounts of rectangularily organized information, such as
2305 matrices, images, or generally blobs of binary data. It is desirable to
2306 access these blobs in a C like manner so that they can be handed to
2307 external C code such as linear algebra libraries or image processing
2310 While pointers to the elements of an array are in use, the array itself
2311 must be protected so that the pointer remains valid. Such a protected
2312 array is said to be @dfn{reserved}. A reserved array can be read but
2313 modifications to it that would cause the pointer to its elements to
2314 become invalid are prevented. When you attempt such a modification, an
2317 (This is similar to locking the array while it is in use, but without
2318 the danger of a deadlock. In a multi-threaded program, you will need
2319 additional synchronization to avoid modifying reserved arrays.)
2321 You must take care to always unreserve an array after reserving it, also
2322 in the presence of non-local exits. To simplify this, reserving and
2323 unreserving work like a frame (@pxref{Frames}): a call to
2324 @code{scm_array_get_handle} can be thought of as beginning a frame and
2325 @code{scm_array_handle_release} as ending it. When a non-local exit
2326 happens between these two calls, the array is implicitely unreserved.
2328 That is, you need to properly pair reserving and unreserving in your
2329 code, but you don't need to worry about non-local exits.
2331 These calls and other pairs of calls that establish dynamic contexts
2332 need to be properly nested. If you begin a frame prior to reserving an
2333 array, you need to unreserve the array before ending the frame.
2334 Likewise, when reserving two or more arrays in a certain order, you need
2335 to unreserve them in the opposite order.
2337 Once you have reserved an array and have retrieved the pointer to its
2338 elements, you must figure out the layout of the elements in memory.
2339 Guile allows slices to be taken out of arrays without actually making a
2340 copy, such as making an alias for the diagonal of a matrix that can be
2341 treated as a vector. Arrays that result from such an operation are not
2342 stored contiguously in memory and when working with their elements
2343 directly, you need to take this into account.
2345 The layout of array elements in memory can be defined via a
2346 @emph{mapping function} that computes a scalar position from a vector of
2347 indices. The scalar position then is the offset of the element with the
2348 given indices from the start of the storage block of the array.
2350 In Guile, this mapping function is restricted to be @dfn{affine}: all
2351 mapping function of Guile arrays can be written as @code{p = b +
2352 c[0]*i[0] + c[1]*i[1] + ... + c[n-1]*i[n-1]} where @code{i[k]} is the
2353 @nicode{k}th index and @code{n} is the rank of the array. For example,
2354 a matrix of size 3x3 would have @code{b == 0}, @code{c[0] == 3} and
2355 @code{c[1] == 1}. When you transpose this matrix (with
2356 @code{transpose-array}, say), you will get an array whose mapping
2357 function has @code{b == 0}, @code{c[0] == 1} and @code{c[1] == 3}.
2359 The function @code{scm_array_handle_dims} gives you (indirect) access to
2360 the coefficients @code{c[k]}.
2363 Note that there are no functions for accessing the elements of a
2364 character array yet. Once the string implementation of Guile has been
2365 changed to use Unicode, we will provide them.
2367 @deftp {C Type} scm_t_array_handle
2368 This is a structure type that holds all information necessary to manage
2369 the reservation of arrays as explained above. Structures of this type
2370 must be allocated on the stack and must only be accessed by the
2371 functions listed below.
2374 @deftypefn {C Function} void scm_array_get_handle (SCM array, scm_t_array_handle *handle)
2375 Reserve @var{array}, which must be an array, and prepare @var{handle} to
2376 be used with the functions below. You must eventually call
2377 @code{scm_array_handle_release} on @var{handle}, and do this in a
2378 properly nested fashion, as explained above. The structure pointed to
2379 by @var{handle} does not need to be initialized before calling this
2383 @deftypefn {C Function} void scm_array_handle_release (scm_t_array_handle *handle)
2384 End the array reservation represented by @var{handle}. After a call to
2385 this function, @var{handle} might be used for another reservation.
2388 @deftypefn {C Function} size_t scm_array_handle_rank (scm_t_array_handle *handle)
2389 Return the rank of the array represented by @var{handle}.
2392 @deftp {C Type} scm_t_array_dim
2393 This structure type holds information about the layout of one dimension
2394 of an array. It includes the following fields:
2399 The lower and upper bounds (both inclusive) of the permissible index
2400 range for the given dimension. Both values can be negative, but
2401 @var{lbnd} is always less than or equal to @var{ubnd}.
2404 The distance from one element of this dimension to the next. Note, too,
2405 that this can be negative.
2409 @deftypefn {C Function} {const scm_t_array_dim *} scm_array_handle_dims (scm_t_array_handle *handle)
2410 Return a pointer to a C vector of information about the dimensions of
2411 the array represented by @var{handle}. This pointer is valid as long as
2412 the array remains reserved. As explained above, the
2413 @code{scm_t_array_dim} structures returned by this function can be used
2414 calculate the position of an element in the storage block of the array
2417 This position can then be used as an index into the C array pointer
2418 returned by the various @code{scm_array_handle_<foo>_elements}
2419 functions, or with @code{scm_array_handle_ref} and
2420 @code{scm_array_handle_set}.
2422 Here is how one can compute the position @var{pos} of an element given
2423 its indices in the vector @var{indices}:
2426 ssize_t indices[RANK];
2427 scm_t_array_dim *dims;
2432 for (i = 0; i < RANK; i++)
2434 if (indices[i] < dims[i].lbnd || indices[i] > dims[i].ubnd)
2436 pos += (indices[i] - dims[i].lbnd) * dims[i].inc;
2441 @deftypefn {C Function} ssize_t scm_array_handle_pos (scm_t_array_handle *handle, SCM indices)
2442 Compute the position corresponding to @var{indices}, a list of
2443 indices. The position is computed as described above for
2444 @code{scm_array_handle_dims}. The number of the indices and their
2445 range is checked and an approrpiate error is signalled for invalid
2449 @deftypefn {C Function} SCM scm_array_handle_ref (scm_t_array_handle *handle, ssize_t pos)
2450 Return the element at position @var{pos} in the storage block of the
2451 array represented by @var{handle}. Any kind of array is acceptable. No
2452 range checking is done on @var{pos}.
2455 @deftypefn {C Function} void scm_array_handle_set (scm_t_array_handle *handle, ssize_t pos, SCM val)
2456 Set the element at position @var{pos} in the storage block of the array
2457 represented by @var{handle} to @var{val}. Any kind of array is
2458 acceptable. No range checking is done on @var{pos}. An error is
2459 signalled when the array can not store @var{val}.
2462 @deftypefn {C Function} {const SCM *} scm_array_handle_elements (scm_t_array_handle *handle)
2463 Return a pointer to the elements of a ordinary array of general Scheme
2464 values (i.e., a non-uniform array) for reading. This pointer is valid
2465 as long as the array remains reserved.
2468 @deftypefn {C Function} {SCM *} scm_array_handle_writable_elements (scm_t_array_handle *handle)
2469 Like @code{scm_array_handle_elements}, but the pointer is good for
2470 reading and writing.
2473 @deftypefn {C Function} {const void *} scm_array_handle_uniform_elements (scm_t_array_handle *handle)
2474 Return a pointer to the elements of a uniform numeric array for reading.
2475 This pointer is valid as long as the array remains reserved. The size
2476 of each element is given by @code{scm_array_handle_uniform_element_size}.
2479 @deftypefn {C Function} {void *} scm_array_handle_uniform_writable_elements (scm_t_array_handle *handle)
2480 Like @code{scm_array_handle_uniform_elements}, but the pointer is good
2481 reading and writing.
2484 @deftypefn {C Function} size_t scm_array_handle_uniform_element_size (scm_t_array_handle *handle)
2485 Return the size of one element of the uniform numeric array represented
2489 @deftypefn {C Function} {const scm_t_uint8 *} scm_array_handle_u8_elements (scm_t_array_handle *handle)
2490 @deftypefnx {C Function} {const scm_t_int8 *} scm_array_handle_s8_elements (scm_t_array_handle *handle)
2491 @deftypefnx {C Function} {const scm_t_uint16 *} scm_array_handle_u16_elements (scm_t_array_handle *handle)
2492 @deftypefnx {C Function} {const scm_t_int16 *} scm_array_handle_s16_elements (scm_t_array_handle *handle)
2493 @deftypefnx {C Function} {const scm_t_uint32 *} scm_array_handle_u32_elements (scm_t_array_handle *handle)
2494 @deftypefnx {C Function} {const scm_t_int32 *} scm_array_handle_s32_elements (scm_t_array_handle *handle)
2495 @deftypefnx {C Function} {const scm_t_uint64 *} scm_array_handle_u64_elements (scm_t_array_handle *handle)
2496 @deftypefnx {C Function} {const scm_t_int64 *} scm_array_handle_s64_elements (scm_t_array_handle *handle)
2497 @deftypefnx {C Function} {const float *} scm_array_handle_f32_elements (scm_t_array_handle *handle)
2498 @deftypefnx {C Function} {const double *} scm_array_handle_f64_elements (scm_t_array_handle *handle)
2499 @deftypefnx {C Function} {const float *} scm_array_handle_c32_elements (scm_t_array_handle *handle)
2500 @deftypefnx {C Function} {const double *} scm_array_handle_c64_elements (scm_t_array_handle *handle)
2501 Return a pointer to the elements of a uniform numeric array of the
2502 indicated kind for reading. This pointer is valid as long as the array
2505 The pointers for @code{c32} and @code{c64} uniform numeric arrays point
2506 to pairs of floating point numbers. The even index holds the real part,
2507 the odd index the imaginary part of the complex number.
2510 @deftypefn {C Function} {scm_t_uint8 *} scm_array_handle_u8_writable_elements (scm_t_array_handle *handle)
2511 @deftypefnx {C Function} {scm_t_int8 *} scm_array_handle_s8_writable_elements (scm_t_array_handle *handle)
2512 @deftypefnx {C Function} {scm_t_uint16 *} scm_array_handle_u16_writable_elements (scm_t_array_handle *handle)
2513 @deftypefnx {C Function} {scm_t_int16 *} scm_array_handle_s16_writable_elements (scm_t_array_handle *handle)
2514 @deftypefnx {C Function} {scm_t_uint32 *} scm_array_handle_u32_writable_elements (scm_t_array_handle *handle)
2515 @deftypefnx {C Function} {scm_t_int32 *} scm_array_handle_s32_writable_elements (scm_t_array_handle *handle)
2516 @deftypefnx {C Function} {scm_t_uint64 *} scm_array_handle_u64_writable_elements (scm_t_array_handle *handle)
2517 @deftypefnx {C Function} {scm_t_int64 *} scm_array_handle_s64_writable_elements (scm_t_array_handle *handle)
2518 @deftypefnx {C Function} {float *} scm_array_handle_f32_writable_elements (scm_t_array_handle *handle)
2519 @deftypefnx {C Function} {double *} scm_array_handle_f64_writable_elements (scm_t_array_handle *handle)
2520 @deftypefnx {C Function} {float *} scm_array_handle_c32_writable_elements (scm_t_array_handle *handle)
2521 @deftypefnx {C Function} {double *} scm_array_handle_c64_writable_elements (scm_t_array_handle *handle)
2522 Like @code{scm_array_handle_<kind>_elements}, but the pointer is good
2523 for reading and writing.
2526 @deftypefn {C Function} {const scm_t_uint32 *} scm_array_handle_bit_elements (scm_t_array_handle *handle)
2527 Return a pointer to the words that store the bits of the represented
2528 array, which must be a bit array.
2530 Unlike other arrays, bit arrays have an additional offset that must be
2531 figured into index calculations. That offset is returned by
2532 @code{scm_array_handle_bit_elements_offset}.
2534 To find a certain bit you first need to calculate its position as
2535 explained above for @code{scm_array_handle_dims} and then add the
2536 offset. This gives the absolute position of the bit, which is always a
2537 non-negative integer.
2539 Each word of the bit array storage block contains exactly 32 bits, with
2540 the least significant bit in that word having the lowest absolute
2541 position number. The next word contains the next 32 bits.
2543 Thus, the following code can be used to access a bit whose position
2544 according to @code{scm_array_handle_dims} is given in @var{pos}:
2548 scm_t_array_handle handle;
2552 size_t word_pos, mask;
2554 scm_array_get_handle (&bit_array, &handle);
2555 bits = scm_array_handle_bit_elements (&handle);
2558 abs_pos = pos + scm_array_handle_bit_elements_offset (&handle);
2559 word_pos = abs_pos / 32;
2560 mask = 1L << (abs_pos % 32);
2562 if (bits[word_pos] & mask)
2565 scm_array_handle_release (&handle);
2570 @deftypefn {C Function} {scm_t_uint32 *} scm_array_handle_bit_writable_elements (scm_t_array_handle *handle)
2571 Like @code{scm_array_handle_bit_elements} but the pointer is good for
2572 reading and writing. You must take care not to modify bits outside of
2573 the allowed index range of the array, even for contiguous arrays.
2579 A @dfn{record type} is a first class object representing a user-defined
2580 data type. A @dfn{record} is an instance of a record type.
2582 @deffn {Scheme Procedure} record? obj
2583 Return @code{#t} if @var{obj} is a record of any type and @code{#f}
2586 Note that @code{record?} may be true of any Scheme value; there is no
2587 promise that records are disjoint with other Scheme types.
2590 @deffn {Scheme Procedure} make-record-type type-name field-names
2591 Return a @dfn{record-type descriptor}, a value representing a new data
2592 type disjoint from all others. The @var{type-name} argument must be a
2593 string, but is only used for debugging purposes (such as the printed
2594 representation of a record of the new type). The @var{field-names}
2595 argument is a list of symbols naming the @dfn{fields} of a record of the
2596 new type. It is an error if the list contains any duplicates. It is
2597 unspecified how record-type descriptors are represented.
2600 @deffn {Scheme Procedure} record-constructor rtd [field-names]
2601 Return a procedure for constructing new members of the type represented
2602 by @var{rtd}. The returned procedure accepts exactly as many arguments
2603 as there are symbols in the given list, @var{field-names}; these are
2604 used, in order, as the initial values of those fields in a new record,
2605 which is returned by the constructor procedure. The values of any
2606 fields not named in that list are unspecified. The @var{field-names}
2607 argument defaults to the list of field names in the call to
2608 @code{make-record-type} that created the type represented by @var{rtd};
2609 if the @var{field-names} argument is provided, it is an error if it
2610 contains any duplicates or any symbols not in the default list.
2613 @deffn {Scheme Procedure} record-predicate rtd
2614 Return a procedure for testing membership in the type represented by
2615 @var{rtd}. The returned procedure accepts exactly one argument and
2616 returns a true value if the argument is a member of the indicated record
2617 type; it returns a false value otherwise.
2620 @deffn {Scheme Procedure} record-accessor rtd field-name
2621 Return a procedure for reading the value of a particular field of a
2622 member of the type represented by @var{rtd}. The returned procedure
2623 accepts exactly one argument which must be a record of the appropriate
2624 type; it returns the current value of the field named by the symbol
2625 @var{field-name} in that record. The symbol @var{field-name} must be a
2626 member of the list of field-names in the call to @code{make-record-type}
2627 that created the type represented by @var{rtd}.
2630 @deffn {Scheme Procedure} record-modifier rtd field-name
2631 Return a procedure for writing the value of a particular field of a
2632 member of the type represented by @var{rtd}. The returned procedure
2633 accepts exactly two arguments: first, a record of the appropriate type,
2634 and second, an arbitrary Scheme value; it modifies the field named by
2635 the symbol @var{field-name} in that record to contain the given value.
2636 The returned value of the modifier procedure is unspecified. The symbol
2637 @var{field-name} must be a member of the list of field-names in the call
2638 to @code{make-record-type} that created the type represented by
2642 @deffn {Scheme Procedure} record-type-descriptor record
2643 Return a record-type descriptor representing the type of the given
2644 record. That is, for example, if the returned descriptor were passed to
2645 @code{record-predicate}, the resulting predicate would return a true
2646 value when passed the given record. Note that it is not necessarily the
2647 case that the returned descriptor is the one that was passed to
2648 @code{record-constructor} in the call that created the constructor
2649 procedure that created the given record.
2652 @deffn {Scheme Procedure} record-type-name rtd
2653 Return the type-name associated with the type represented by rtd. The
2654 returned value is @code{eqv?} to the @var{type-name} argument given in
2655 the call to @code{make-record-type} that created the type represented by
2659 @deffn {Scheme Procedure} record-type-fields rtd
2660 Return a list of the symbols naming the fields in members of the type
2661 represented by @var{rtd}. The returned value is @code{equal?} to the
2662 field-names argument given in the call to @code{make-record-type} that
2663 created the type represented by @var{rtd}.
2668 @subsection Structures
2671 [FIXME: this is pasted in from Tom Lord's original guile.texi and should
2674 A @dfn{structure type} is a first class user-defined data type. A
2675 @dfn{structure} is an instance of a structure type. A structure type is
2678 Structures are less abstract and more general than traditional records.
2679 In fact, in Guile Scheme, records are implemented using structures.
2682 * Structure Concepts:: The structure of Structures
2683 * Structure Layout:: Defining the layout of structure types
2684 * Structure Basics:: make-, -ref and -set! procedures for structs
2685 * Vtables:: Accessing type-specific data
2688 @node Structure Concepts
2689 @subsubsection Structure Concepts
2691 A structure object consists of a handle, structure data, and a vtable.
2692 The handle is a Scheme value which points to both the vtable and the
2693 structure's data. Structure data is a dynamically allocated region of
2694 memory, private to the structure, divided up into typed fields. A
2695 vtable is another structure used to hold type-specific data. Multiple
2696 structures can share a common vtable.
2698 Three concepts are key to understanding structures.
2701 @item @dfn{layout specifications}
2703 Layout specifications determine how memory allocated to structures is
2704 divided up into fields. Programmers must write a layout specification
2705 whenever a new type of structure is defined.
2707 @item @dfn{structural accessors}
2709 Structure access is by field number. There is only one set of
2710 accessors common to all structure objects.
2714 Vtables, themselves structures, are first class representations of
2715 disjoint sub-types of structures in general. In most cases, when a
2716 new structure is created, programmers must specify a vtable for the
2717 new structure. Each vtable has a field describing the layout of its
2718 instances. Vtables can have additional, user-defined fields as well.
2723 @node Structure Layout
2724 @subsubsection Structure Layout
2726 When a structure is created, a region of memory is allocated to hold its
2727 state. The @dfn{layout} of the structure's type determines how that
2728 memory is divided into fields.
2730 Each field has a specified type. There are only three types allowed, each
2731 corresponding to a one letter code. The allowed types are:
2734 @item 'u' -- unprotected
2736 The field holds binary data that is not GC protected.
2738 @item 'p' -- protected
2740 The field holds a Scheme value and is GC protected.
2744 The field holds a Scheme value and is GC protected. When a structure is
2745 created with this type of field, the field is initialized to refer to
2746 the structure's own handle. This kind of field is mainly useful when
2747 mixing Scheme and C code in which the C code may need to compute a
2748 structure's handle given only the address of its malloc'd data.
2752 Each field also has an associated access protection. There are only
2753 three kinds of protection, each corresponding to a one letter code.
2754 The allowed protections are:
2757 @item 'w' -- writable
2759 The field can be read and written.
2761 @item 'r' -- readable
2763 The field can be read, but not written.
2767 The field can be neither read nor written. This kind
2768 of protection is for fields useful only to built-in routines.
2771 A layout specification is described by stringing together pairs
2772 of letters: one to specify a field type and one to specify a field
2773 protection. For example, a traditional cons pair type object could
2777 ; cons pairs have two writable fields of Scheme data
2781 A pair object in which the first field is held constant could be:
2787 Binary fields, (fields of type "u"), hold one @dfn{word} each. The
2788 size of a word is a machine dependent value defined to be equal to the
2789 value of the C expression: @code{sizeof (long)}.
2791 The last field of a structure layout may specify a tail array.
2792 A tail array is indicated by capitalizing the field's protection
2793 code ('W', 'R' or 'O'). A tail-array field is replaced by
2794 a read-only binary data field containing an array size. The array
2795 size is determined at the time the structure is created. It is followed
2796 by a corresponding number of fields of the type specified for the
2797 tail array. For example, a conventional Scheme vector can be
2801 ; A vector is an arbitrary number of writable fields holding Scheme
2806 In the above example, field 0 contains the size of the vector and
2807 fields beginning at 1 contain the vector elements.
2809 A kind of tagged vector (a constant tag followed by conventional
2810 vector elements) might be:
2817 Structure layouts are represented by specially interned symbols whose
2818 name is a string of type and protection codes. To create a new
2819 structure layout, use this procedure:
2821 @deffn {Scheme Procedure} make-struct-layout fields
2822 @deffnx {C Function} scm_make_struct_layout (fields)
2823 Return a new structure layout object.
2825 @var{fields} must be a string made up of pairs of characters
2826 strung together. The first character of each pair describes a field
2827 type, the second a field protection. Allowed types are 'p' for
2828 GC-protected Scheme data, 'u' for unprotected binary data, and 's' for
2829 a field that points to the structure itself. Allowed protections
2830 are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque
2831 fields. The last field protection specification may be capitalized to
2832 indicate that the field is a tail-array.
2837 @node Structure Basics
2838 @subsubsection Structure Basics
2840 This section describes the basic procedures for creating and accessing
2843 @deffn {Scheme Procedure} make-struct vtable tail_array_size . init
2844 @deffnx {C Function} scm_make_struct (vtable, tail_array_size, init)
2845 Create a new structure.
2847 @var{type} must be a vtable structure (@pxref{Vtables}).
2849 @var{tail-elts} must be a non-negative integer. If the layout
2850 specification indicated by @var{type} includes a tail-array,
2851 this is the number of elements allocated to that array.
2853 The @var{init1}, @dots{} are optional arguments describing how
2854 successive fields of the structure should be initialized. Only fields
2855 with protection 'r' or 'w' can be initialized, except for fields of
2856 type 's', which are automatically initialized to point to the new
2857 structure itself; fields with protection 'o' can not be initialized by
2860 If fewer optional arguments than initializable fields are supplied,
2861 fields of type 'p' get default value #f while fields of type 'u' are
2864 Structs are currently the basic representation for record-like data
2865 structures in Guile. The plan is to eventually replace them with a
2866 new representation which will at the same time be easier to use and
2869 For more information, see the documentation for @code{make-vtable-vtable}.
2872 @deffn {Scheme Procedure} struct? x
2873 @deffnx {C Function} scm_struct_p (x)
2874 Return @code{#t} iff @var{x} is a structure object, else
2879 @deffn {Scheme Procedure} struct-ref handle pos
2880 @deffnx {Scheme Procedure} struct-set! struct n value
2881 @deffnx {C Function} scm_struct_ref (handle, pos)
2882 @deffnx {C Function} scm_struct_set_x (struct, n, value)
2883 Access (or modify) the @var{n}th field of @var{struct}.
2885 If the field is of type 'p', then it can be set to an arbitrary value.
2887 If the field is of type 'u', then it can only be set to a non-negative
2888 integer value small enough to fit in one machine word.
2894 @subsubsection Vtables
2896 Vtables are structures that are used to represent structure types. Each
2897 vtable contains a layout specification in field
2898 @code{vtable-index-layout} -- instances of the type are laid out
2899 according to that specification. Vtables contain additional fields
2900 which are used only internally to libguile. The variable
2901 @code{vtable-offset-user} is bound to a field number. Vtable fields
2902 at that position or greater are user definable.
2904 @deffn {Scheme Procedure} struct-vtable handle
2905 @deffnx {C Function} scm_struct_vtable (handle)
2906 Return the vtable structure that describes the type of @var{struct}.
2909 @deffn {Scheme Procedure} struct-vtable? x
2910 @deffnx {C Function} scm_struct_vtable_p (x)
2911 Return @code{#t} iff @var{x} is a vtable structure.
2914 If you have a vtable structure, @code{V}, you can create an instance of
2915 the type it describes by using @code{(make-struct V ...)}. But where
2916 does @code{V} itself come from? One possibility is that @code{V} is an
2917 instance of a user-defined vtable type, @code{V'}, so that @code{V} is
2918 created by using @code{(make-struct V' ...)}. Another possibility is
2919 that @code{V} is an instance of the type it itself describes. Vtable
2920 structures of the second sort are created by this procedure:
2922 @deffn {Scheme Procedure} make-vtable-vtable user_fields tail_array_size . init
2923 @deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_array_size, init)
2924 Return a new, self-describing vtable structure.
2926 @var{user-fields} is a string describing user defined fields of the
2927 vtable beginning at index @code{vtable-offset-user}
2928 (see @code{make-struct-layout}).
2930 @var{tail-size} specifies the size of the tail-array (if any) of
2933 @var{init1}, @dots{} are the optional initializers for the fields of
2936 Vtables have one initializable system field---the struct printer.
2937 This field comes before the user fields in the initializers passed
2938 to @code{make-vtable-vtable} and @code{make-struct}, and thus works as
2939 a third optional argument to @code{make-vtable-vtable} and a fourth to
2940 @code{make-struct} when creating vtables:
2942 If the value is a procedure, it will be called instead of the standard
2943 printer whenever a struct described by this vtable is printed.
2944 The procedure will be called with arguments STRUCT and PORT.
2946 The structure of a struct is described by a vtable, so the vtable is
2947 in essence the type of the struct. The vtable is itself a struct with
2948 a vtable. This could go on forever if it weren't for the
2949 vtable-vtables which are self-describing vtables, and thus terminate
2952 There are several potential ways of using structs, but the standard
2953 one is to use three kinds of structs, together building up a type
2954 sub-system: one vtable-vtable working as the root and one or several
2955 "types", each with a set of "instances". (The vtable-vtable should be
2956 compared to the class <class> which is the class of itself.)
2959 (define ball-root (make-vtable-vtable "pr" 0))
2961 (define (make-ball-type ball-color)
2962 (make-struct ball-root 0
2963 (make-struct-layout "pw")
2965 (format port "#<a ~A ball owned by ~A>"
2969 (define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
2970 (define (owner ball) (struct-ref ball 0))
2972 (define red (make-ball-type 'red))
2973 (define green (make-ball-type 'green))
2975 (define (make-ball type owner) (make-struct type 0 owner))
2977 (define ball (make-ball green 'Nisse))
2978 ball @result{} #<a green ball owned by Nisse>
2982 @deffn {Scheme Procedure} struct-vtable-name vtable
2983 @deffnx {C Function} scm_struct_vtable_name (vtable)
2984 Return the name of the vtable @var{vtable}.
2987 @deffn {Scheme Procedure} set-struct-vtable-name! vtable name
2988 @deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name)
2989 Set the name of the vtable @var{vtable} to @var{name}.
2992 @deffn {Scheme Procedure} struct-vtable-tag handle
2993 @deffnx {C Function} scm_struct_vtable_tag (handle)
2994 Return the vtable tag of the structure @var{handle}.
2998 @node Dictionary Types
2999 @subsection Dictionary Types
3001 A @dfn{dictionary} object is a data structure used to index
3002 information in a user-defined way. In standard Scheme, the main
3003 aggregate data types are lists and vectors. Lists are not really
3004 indexed at all, and vectors are indexed only by number
3005 (e.g. @code{(vector-ref foo 5)}). Often you will find it useful
3006 to index your data on some other type; for example, in a library
3007 catalog you might want to look up a book by the name of its
3008 author. Dictionaries are used to help you organize information in
3011 An @dfn{association list} (or @dfn{alist} for short) is a list of
3012 key-value pairs. Each pair represents a single quantity or
3013 object; the @code{car} of the pair is a key which is used to
3014 identify the object, and the @code{cdr} is the object's value.
3016 A @dfn{hash table} also permits you to index objects with
3017 arbitrary keys, but in a way that makes looking up any one object
3018 extremely fast. A well-designed hash system makes hash table
3019 lookups almost as fast as conventional array or vector references.
3021 Alists are popular among Lisp programmers because they use only
3022 the language's primitive operations (lists, @dfn{car}, @dfn{cdr}
3023 and the equality primitives). No changes to the language core are
3024 necessary. Therefore, with Scheme's built-in list manipulation
3025 facilities, it is very convenient to handle data stored in an
3026 association list. Also, alists are highly portable and can be
3027 easily implemented on even the most minimal Lisp systems.
3029 However, alists are inefficient, especially for storing large
3030 quantities of data. Because we want Guile to be useful for large
3031 software systems as well as small ones, Guile provides a rich set
3032 of tools for using either association lists or hash tables.
3034 @node Association Lists
3035 @subsection Association Lists
3036 @tpindex Association Lists
3038 @cindex association List
3042 An association list is a conventional data structure that is often used
3043 to implement simple key-value databases. It consists of a list of
3044 entries in which each entry is a pair. The @dfn{key} of each entry is
3045 the @code{car} of the pair and the @dfn{value} of each entry is the
3049 ASSOCIATION LIST ::= '( (KEY1 . VALUE1)
3057 Association lists are also known, for short, as @dfn{alists}.
3059 The structure of an association list is just one example of the infinite
3060 number of possible structures that can be built using pairs and lists.
3061 As such, the keys and values in an association list can be manipulated
3062 using the general list structure procedures @code{cons}, @code{car},
3063 @code{cdr}, @code{set-car!}, @code{set-cdr!} and so on. However,
3064 because association lists are so useful, Guile also provides specific
3065 procedures for manipulating them.
3068 * Alist Key Equality::
3069 * Adding or Setting Alist Entries::
3070 * Retrieving Alist Entries::
3071 * Removing Alist Entries::
3072 * Sloppy Alist Functions::
3076 @node Alist Key Equality
3077 @subsubsection Alist Key Equality
3079 All of Guile's dedicated association list procedures, apart from
3080 @code{acons}, come in three flavours, depending on the level of equality
3081 that is required to decide whether an existing key in the association
3082 list is the same as the key that the procedure call uses to identify the
3087 Procedures with @dfn{assq} in their name use @code{eq?} to determine key
3091 Procedures with @dfn{assv} in their name use @code{eqv?} to determine
3095 Procedures with @dfn{assoc} in their name use @code{equal?} to
3096 determine key equality.
3099 @code{acons} is an exception because it is used to build association
3100 lists which do not require their entries' keys to be unique.
3102 @node Adding or Setting Alist Entries
3103 @subsubsection Adding or Setting Alist Entries
3105 @code{acons} adds a new entry to an association list and returns the
3106 combined association list. The combined alist is formed by consing the
3107 new entry onto the head of the alist specified in the @code{acons}
3108 procedure call. So the specified alist is not modified, but its
3109 contents become shared with the tail of the combined alist that
3110 @code{acons} returns.
3112 In the most common usage of @code{acons}, a variable holding the
3113 original association list is updated with the combined alist:
3116 (set! address-list (acons name address address-list))
3119 In such cases, it doesn't matter that the old and new values of
3120 @code{address-list} share some of their contents, since the old value is
3121 usually no longer independently accessible.
3123 Note that @code{acons} adds the specified new entry regardless of
3124 whether the alist may already contain entries with keys that are, in
3125 some sense, the same as that of the new entry. Thus @code{acons} is
3126 ideal for building alists where there is no concept of key uniqueness.
3129 (set! task-list (acons 3 "pay gas bill" '()))
3132 ((3 . "pay gas bill"))
3134 (set! task-list (acons 3 "tidy bedroom" task-list))
3137 ((3 . "tidy bedroom") (3 . "pay gas bill"))
3140 @code{assq-set!}, @code{assv-set!} and @code{assoc-set!} are used to add
3141 or replace an entry in an association list where there @emph{is} a
3142 concept of key uniqueness. If the specified association list already
3143 contains an entry whose key is the same as that specified in the
3144 procedure call, the existing entry is replaced by the new one.
3145 Otherwise, the new entry is consed onto the head of the old association
3146 list to create the combined alist. In all cases, these procedures
3147 return the combined alist.
3149 @code{assq-set!} and friends @emph{may} destructively modify the
3150 structure of the old association list in such a way that an existing
3151 variable is correctly updated without having to @code{set!} it to the
3157 (("mary" . "34 Elm Road") ("james" . "16 Bow Street"))
3159 (assoc-set! address-list "james" "1a London Road")
3161 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
3165 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
3171 (assoc-set! address-list "bob" "11 Newington Avenue")
3173 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
3174 ("james" . "1a London Road"))
3178 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
3181 The only safe way to update an association list variable when adding or
3182 replacing an entry like this is to @code{set!} the variable to the
3187 (assoc-set! address-list "bob" "11 Newington Avenue"))
3190 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
3191 ("james" . "1a London Road"))
3194 Because of this slight inconvenience, you may find it more convenient to
3195 use hash tables to store dictionary data. If your application will not
3196 be modifying the contents of an alist very often, this may not make much
3199 If you need to keep the old value of an association list in a form
3200 independent from the list that results from modification by
3201 @code{acons}, @code{assq-set!}, @code{assv-set!} or @code{assoc-set!},
3202 use @code{list-copy} to copy the old association list before modifying
3205 @deffn {Scheme Procedure} acons key value alist
3206 @deffnx {C Function} scm_acons (key, value, alist)
3207 Add a new key-value pair to @var{alist}. A new pair is
3208 created whose car is @var{key} and whose cdr is @var{value}, and the
3209 pair is consed onto @var{alist}, and the new list is returned. This
3210 function is @emph{not} destructive; @var{alist} is not modified.
3213 @deffn {Scheme Procedure} assq-set! alist key val
3214 @deffnx {Scheme Procedure} assv-set! alist key value
3215 @deffnx {Scheme Procedure} assoc-set! alist key value
3216 @deffnx {C Function} scm_assq_set_x (alist, key, val)
3217 @deffnx {C Function} scm_assv_set_x (alist, key, val)
3218 @deffnx {C Function} scm_assoc_set_x (alist, key, val)
3219 Reassociate @var{key} in @var{alist} with @var{value}: find any existing
3220 @var{alist} entry for @var{key} and associate it with the new
3221 @var{value}. If @var{alist} does not contain an entry for @var{key},
3222 add a new one. Return the (possibly new) alist.
3224 These functions do not attempt to verify the structure of @var{alist},
3225 and so may cause unusual results if passed an object that is not an
3229 @node Retrieving Alist Entries
3230 @subsubsection Retrieving Alist Entries
3235 @code{assq}, @code{assv} and @code{assoc} take an alist and a key as
3236 arguments and return the entry for that key if an entry exists, or
3237 @code{#f} if there is no entry for that key. Note that, in the cases
3238 where an entry exists, these procedures return the complete entry, that
3239 is @code{(KEY . VALUE)}, not just the value.
3241 @deffn {Scheme Procedure} assq key alist
3242 @deffnx {Scheme Procedure} assv key alist
3243 @deffnx {Scheme Procedure} assoc key alist
3244 @deffnx {C Function} scm_assq (key, alist)
3245 @deffnx {C Function} scm_assv (key, alist)
3246 @deffnx {C Function} scm_assoc (key, alist)
3247 Fetch the entry in @var{alist} that is associated with @var{key}. To
3248 decide whether the argument @var{key} matches a particular entry in
3249 @var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}
3250 uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}
3251 cannot be found in @var{alist} (according to whichever equality
3252 predicate is in use), then return @code{#f}. These functions
3253 return the entire alist entry found (i.e. both the key and the value).
3256 @code{assq-ref}, @code{assv-ref} and @code{assoc-ref}, on the other
3257 hand, take an alist and a key and return @emph{just the value} for that
3258 key, if an entry exists. If there is no entry for the specified key,
3259 these procedures return @code{#f}.
3261 This creates an ambiguity: if the return value is @code{#f}, it means
3262 either that there is no entry with the specified key, or that there
3263 @emph{is} an entry for the specified key, with value @code{#f}.
3264 Consequently, @code{assq-ref} and friends should only be used where it
3265 is known that an entry exists, or where the ambiguity doesn't matter
3266 for some other reason.
3268 @deffn {Scheme Procedure} assq-ref alist key
3269 @deffnx {Scheme Procedure} assv-ref alist key
3270 @deffnx {Scheme Procedure} assoc-ref alist key
3271 @deffnx {C Function} scm_assq_ref (alist, key)
3272 @deffnx {C Function} scm_assv_ref (alist, key)
3273 @deffnx {C Function} scm_assoc_ref (alist, key)
3274 Like @code{assq}, @code{assv} and @code{assoc}, except that only the
3275 value associated with @var{key} in @var{alist} is returned. These
3276 functions are equivalent to
3279 (let ((ent (@var{associator} @var{key} @var{alist})))
3280 (and ent (cdr ent)))
3283 where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}.
3286 @node Removing Alist Entries
3287 @subsubsection Removing Alist Entries
3289 To remove the element from an association list whose key matches a
3290 specified key, use @code{assq-remove!}, @code{assv-remove!} or
3291 @code{assoc-remove!} (depending, as usual, on the level of equality
3292 required between the key that you specify and the keys in the
3295 As with @code{assq-set!} and friends, the specified alist may or may not
3296 be modified destructively, and the only safe way to update a variable
3297 containing the alist is to @code{set!} it to the value that
3298 @code{assq-remove!} and friends return.
3303 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
3304 ("james" . "1a London Road"))
3306 (set! address-list (assoc-remove! address-list "mary"))
3309 (("bob" . "11 Newington Avenue") ("james" . "1a London Road"))
3312 Note that, when @code{assq/v/oc-remove!} is used to modify an
3313 association list that has been constructed only using the corresponding
3314 @code{assq/v/oc-set!}, there can be at most one matching entry in the
3315 alist, so the question of multiple entries being removed in one go does
3316 not arise. If @code{assq/v/oc-remove!} is applied to an association
3317 list that has been constructed using @code{acons}, or an
3318 @code{assq/v/oc-set!} with a different level of equality, or any mixture
3319 of these, it removes only the first matching entry from the alist, even
3320 if the alist might contain further matching entries. For example:
3323 (define address-list '())
3324 (set! address-list (assq-set! address-list "mary" "11 Elm Street"))
3325 (set! address-list (assq-set! address-list "mary" "57 Pine Drive"))
3328 (("mary" . "57 Pine Drive") ("mary" . "11 Elm Street"))
3330 (set! address-list (assoc-remove! address-list "mary"))
3333 (("mary" . "11 Elm Street"))
3336 In this example, the two instances of the string "mary" are not the same
3337 when compared using @code{eq?}, so the two @code{assq-set!} calls add
3338 two distinct entries to @code{address-list}. When compared using
3339 @code{equal?}, both "mary"s in @code{address-list} are the same as the
3340 "mary" in the @code{assoc-remove!} call, but @code{assoc-remove!} stops
3341 after removing the first matching entry that it finds, and so one of the
3342 "mary" entries is left in place.
3344 @deffn {Scheme Procedure} assq-remove! alist key
3345 @deffnx {Scheme Procedure} assv-remove! alist key
3346 @deffnx {Scheme Procedure} assoc-remove! alist key
3347 @deffnx {C Function} scm_assq_remove_x (alist, key)
3348 @deffnx {C Function} scm_assv_remove_x (alist, key)
3349 @deffnx {C Function} scm_assoc_remove_x (alist, key)
3350 Delete the first entry in @var{alist} associated with @var{key}, and return
3351 the resulting alist.
3354 @node Sloppy Alist Functions
3355 @subsubsection Sloppy Alist Functions
3357 @code{sloppy-assq}, @code{sloppy-assv} and @code{sloppy-assoc} behave
3358 like the corresponding non-@code{sloppy-} procedures, except that they
3359 return @code{#f} when the specified association list is not well-formed,
3360 where the non-@code{sloppy-} versions would signal an error.
3362 Specifically, there are two conditions for which the non-@code{sloppy-}
3363 procedures signal an error, which the @code{sloppy-} procedures handle
3364 instead by returning @code{#f}. Firstly, if the specified alist as a
3365 whole is not a proper list:
3368 (assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
3370 ERROR: In procedure assoc in expression (assoc "mary" (quote #)):
3371 ERROR: Wrong type argument in position 2 (expecting association list): ((1 . 2) ("key" . "door") . "open sesame")
3373 (sloppy-assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
3379 Secondly, if one of the entries in the specified alist is not a pair:
3382 (assoc 2 '((1 . 1) 2 (3 . 9)))
3384 ERROR: In procedure assoc in expression (assoc 2 (quote #)):
3385 ERROR: Wrong type argument in position 2 (expecting association list): ((1 . 1) 2 (3 . 9))
3387 (sloppy-assoc 2 '((1 . 1) 2 (3 . 9)))
3392 Unless you are explicitly working with badly formed association lists,
3393 it is much safer to use the non-@code{sloppy-} procedures, because they
3394 help to highlight coding and data errors that the @code{sloppy-}
3395 versions would silently cover up.
3397 @deffn {Scheme Procedure} sloppy-assq key alist
3398 @deffnx {C Function} scm_sloppy_assq (key, alist)
3399 Behaves like @code{assq} but does not do any error checking.
3400 Recommended only for use in Guile internals.
3403 @deffn {Scheme Procedure} sloppy-assv key alist
3404 @deffnx {C Function} scm_sloppy_assv (key, alist)
3405 Behaves like @code{assv} but does not do any error checking.
3406 Recommended only for use in Guile internals.
3409 @deffn {Scheme Procedure} sloppy-assoc key alist
3410 @deffnx {C Function} scm_sloppy_assoc (key, alist)
3411 Behaves like @code{assoc} but does not do any error checking.
3412 Recommended only for use in Guile internals.
3416 @subsubsection Alist Example
3418 Here is a longer example of how alists may be used in practice.
3421 (define capitals '(("New York" . "Albany")
3422 ("Oregon" . "Salem")
3423 ("Florida" . "Miami")))
3425 ;; What's the capital of Oregon?
3426 (assoc "Oregon" capitals) @result{} ("Oregon" . "Salem")
3427 (assoc-ref capitals "Oregon") @result{} "Salem"
3429 ;; We left out South Dakota.
3431 (assoc-set! capitals "South Dakota" "Pierre"))
3433 @result{} (("South Dakota" . "Pierre")
3434 ("New York" . "Albany")
3435 ("Oregon" . "Salem")
3436 ("Florida" . "Miami"))
3438 ;; And we got Florida wrong.
3440 (assoc-set! capitals "Florida" "Tallahassee"))
3442 @result{} (("South Dakota" . "Pierre")
3443 ("New York" . "Albany")
3444 ("Oregon" . "Salem")
3445 ("Florida" . "Tallahassee"))
3447 ;; After Oregon secedes, we can remove it.
3449 (assoc-remove! capitals "Oregon"))
3451 @result{} (("South Dakota" . "Pierre")
3452 ("New York" . "Albany")
3453 ("Florida" . "Tallahassee"))
3457 @subsection Hash Tables
3458 @tpindex Hash Tables
3460 Hash tables are dictionaries which offer similar functionality as
3461 association lists: They provide a mapping from keys to values. The
3462 difference is that association lists need time linear in the size of
3463 elements when searching for entries, whereas hash tables can normally
3464 search in constant time. The drawback is that hash tables require a
3465 little bit more memory, and that you can not use the normal list
3466 procedures (@pxref{Lists}) for working with them.
3468 Guile provides two types of hashtables. One is an abstract data type
3469 that can only be manipulated with the functions in this section. The
3470 other type is concrete: it uses a normal vector with alists as
3471 elements. The advantage of the abstract hash tables is that they will
3472 be automatically resized when they become too full or too empty.
3475 * Hash Table Examples:: Demonstration of hash table usage.
3476 * Hash Table Reference:: Hash table procedure descriptions.
3480 @node Hash Table Examples
3481 @subsubsection Hash Table Examples
3483 For demonstration purposes, this section gives a few usage examples of
3484 some hash table procedures, together with some explanation what they do.
3486 First we start by creating a new hash table with 31 slots, and
3487 populate it with two key/value pairs.
3490 (define h (make-hash-table 31))
3492 ;; This is an opaque object
3497 ;; We can also use a vector of alists.
3498 (define h (make-vector 7 '()))
3502 #(() () () () () () ())
3504 ;; Inserting into a hash table can be done with hashq-set!
3505 (hashq-set! h 'foo "bar")
3509 (hashq-set! h 'braz "zonk")
3513 ;; Or with hash-create-handle!
3514 (hashq-create-handle! h 'frob #f)
3518 ;; The vector now contains three elements in the alists and the frob
3519 ;; entry is at index (hashq 'frob).
3522 #(() () () () ((frob . #f) (braz . "zonk")) () ((foo . "bar")))
3530 You can get the value for a given key with the procedure
3531 @code{hashq-ref}, but the problem with this procedure is that you
3532 cannot reliably determine whether a key does exists in the table. The
3533 reason is that the procedure returns @code{#f} if the key is not in
3534 the table, but it will return the same value if the key is in the
3535 table and just happens to have the value @code{#f}, as you can see in
3536 the following examples.
3547 (hashq-ref h 'not-there)
3552 Better is to use the procedure @code{hashq-get-handle}, which makes a
3553 distinction between the two cases. Just like @code{assq}, this
3554 procedure returns a key/value-pair on success, and @code{#f} if the
3558 (hashq-get-handle h 'foo)
3562 (hashq-get-handle h 'not-there)
3567 There is no procedure for calculating the number of key/value-pairs in
3568 a hash table, but @code{hash-fold} can be used for doing exactly that.
3571 (hash-fold (lambda (key value seed) (+ 1 seed)) 0 h)
3576 @node Hash Table Reference
3577 @subsubsection Hash Table Reference
3579 @c FIXME: Describe in broad terms what happens for resizing, and what
3580 @c the initial size means for this.
3582 Like the association list functions, the hash table functions come in
3583 several varieties, according to the equality test used for the keys.
3584 Plain @code{hash-} functions use @code{equal?}, @code{hashq-}
3585 functions use @code{eq?}, @code{hashv-} functions use @code{eqv?}, and
3586 the @code{hashx-} functions use an application supplied test.
3588 A single @code{make-hash-table} creates a hash table suitable for use
3589 with any set of functions, but it's imperative that just one set is
3590 then used consistently, or results will be unpredictable.
3592 Hash tables are implemented as a vector indexed by a hash value formed
3593 from the key, with an association list of key/value pairs for each
3594 bucket in case distinct keys hash together. Direct access to the
3595 pairs in those lists is provided by the @code{-handle-} functions.
3596 The abstract kind of hash tables hide the vector in an opaque object
3597 that represents the hash table, while for the concrete kind the vector
3598 @emph{is} the hashtable.
3600 When the number of table entries in an abstract hash table goes above
3601 a threshold, the vector is made larger and the entries are rehashed,
3602 to prevent the bucket lists from becoming too long and slowing down
3603 accesses. When the number of entries goes below a threshold, the
3604 vector is shrunk to save space.
3606 A abstract hash table is created with @code{make-hash-table}. To
3607 create a vector that is suitable as a hash table, use
3608 @code{(make-vector @var{size} '())}, for example.
3610 For the @code{hashx-} ``extended'' routines, an application supplies a
3611 @var{hash} function producing an integer index like @code{hashq} etc
3612 below, and an @var{assoc} alist search function like @code{assq} etc
3613 (@pxref{Retrieving Alist Entries}). Here's an example of such
3614 functions implementing case-insensitive hashing of string keys,
3617 (use-modules (srfi srfi-1)
3620 (define (my-hash str size)
3621 (remainder (string-hash-ci str) size))
3622 (define (my-assoc str alist)
3623 (find (lambda (pair) (string-ci=? str (car pair))) alist))
3625 (define my-table (make-hash-table))
3626 (hashx-set! my-hash my-assoc my-table "foo" 123)
3628 (hashx-ref my-hash my-assoc my-table "FOO")
3632 In a @code{hashx-} @var{hash} function the aim is to spread keys
3633 across the vector, so bucket lists don't become long. But the actual
3634 values are arbitrary as long as they're in the range 0 to
3635 @math{@var{size}-1}. Helpful functions for forming a hash value, in
3636 addition to @code{hashq} etc below, include @code{symbol-hash}
3637 (@pxref{Symbol Keys}), @code{string-hash} and @code{string-hash-ci}
3638 (@pxref{String Comparison}), and @code{char-set-hash}
3639 (@pxref{Character Set Predicates/Comparison}).
3642 @deffn {Scheme Procedure} make-hash-table [size]
3643 Create a new abstract hash table object, with an optional minimum
3646 When @var{size} is given, the table vector will still grow and shrink
3647 automatically, as described above, but with @var{size} as a minimum.
3648 If an application knows roughly how many entries the table will hold
3649 then it can use @var{size} to avoid rehashing when initial entries are
3653 @deffn {Scheme Procedure} hash-table? obj
3654 @deffnx {C Function} scm_hash_table_p (obj)
3655 Return @code{#t} if @var{obj} is a abstract hash table object.
3658 @deffn {Scheme Procedure} hash-clear! table
3659 @deffnx {C Function} scm_hash_clear_x (table)
3660 Remove all items from @var{table} (without triggering a resize).
3663 @deffn {Scheme Procedure} hash-ref table key [dflt]
3664 @deffnx {Scheme Procedure} hashq-ref table key [dflt]
3665 @deffnx {Scheme Procedure} hashv-ref table key [dflt]
3666 @deffnx {Scheme Procedure} hashx-ref hash assoc table key [dflt]
3667 @deffnx {C Function} scm_hash_ref (table, key, dflt)
3668 @deffnx {C Function} scm_hashq_ref (table, key, dflt)
3669 @deffnx {C Function} scm_hashv_ref (table, key, dflt)
3670 @deffnx {C Function} scm_hashx_ref (hash, assoc, table, key, dflt)
3671 Lookup @var{key} in the given hash @var{table}, and return the
3672 associated value. If @var{key} is not found, return @var{dflt}, or
3673 @code{#f} if @var{dflt} is not given.
3676 @deffn {Scheme Procedure} hash-set! table key val
3677 @deffnx {Scheme Procedure} hashq-set! table key val
3678 @deffnx {Scheme Procedure} hashv-set! table key val
3679 @deffnx {Scheme Procedure} hashx-set! hash assoc table key val
3680 @deffnx {C Function} scm_hash_set_x (table, key, val)
3681 @deffnx {C Function} scm_hashq_set_x (table, key, val)
3682 @deffnx {C Function} scm_hashv_set_x (table, key, val)
3683 @deffnx {C Function} scm_hashx_set_x (hash, assoc, table, key, val)
3684 Associate @var{val} with @var{key} in the given hash @var{table}. If
3685 @var{key} is already present then it's associated value is changed.
3686 If it's not present then a new entry is created.
3689 @deffn {Scheme Procedure} hash-remove! table key
3690 @deffnx {Scheme Procedure} hashq-remove! table key
3691 @deffnx {Scheme Procedure} hashv-remove! table key
3692 @deffnx {Scheme Procedure} hashx-remove! hash assoc table key
3693 @deffnx {C Function} scm_hash_remove_x (table, key)
3694 @deffnx {C Function} scm_hashq_remove_x (table, key)
3695 @deffnx {C Function} scm_hashv_remove_x (table, key)
3696 @deffnx {C Function} scm_hashx_remove_x (hash, assoc, table, key)
3697 Remove any association for @var{key} in the given hash @var{table}.
3698 If @var{key} is not in @var{table} then nothing is done.
3701 @deffn {Scheme Procedure} hash key size
3702 @deffnx {Scheme Procedure} hashq key size
3703 @deffnx {Scheme Procedure} hashv key size
3704 @deffnx {C Function} scm_hash (key, size)
3705 @deffnx {C Function} scm_hashq (key, size)
3706 @deffnx {C Function} scm_hashv (key, size)
3707 Return a hash value for @var{key}. This is a number in the range
3708 @math{0} to @math{@var{size}-1}, which is suitable for use in a hash
3709 table of the given @var{size}.
3711 Note that @code{hashq} and @code{hashv} may use internal addresses of
3712 objects, so if an object is garbage collected and re-created it can
3713 have a different hash value, even when the two are notionally
3714 @code{eq?}. For instance with symbols,
3717 (hashq 'something 123) @result{} 19
3719 (hashq 'something 123) @result{} 62
3722 In normal use this is not a problem, since an object entered into a
3723 hash table won't be garbage collected until removed. It's only if
3724 hashing calculations are somehow separated from normal references that
3725 its lifetime needs to be considered.
3728 @deffn {Scheme Procedure} hash-get-handle table key
3729 @deffnx {Scheme Procedure} hashq-get-handle table key
3730 @deffnx {Scheme Procedure} hashv-get-handle table key
3731 @deffnx {Scheme Procedure} hashx-get-handle hash assoc table key
3732 @deffnx {C Function} scm_hash_get_handle (table, key)
3733 @deffnx {C Function} scm_hashq_get_handle (table, key)
3734 @deffnx {C Function} scm_hashv_get_handle (table, key)
3735 @deffnx {C Function} scm_hashx_get_handle (hash, assoc, table, key)
3736 Return the @code{(@var{key} . @var{value})} pair for @var{key} in the
3737 given hash @var{table}, or @code{#f} if @var{key} is not in
3741 @deffn {Scheme Procedure} hash-create-handle! table key init
3742 @deffnx {Scheme Procedure} hashq-create-handle! table key init
3743 @deffnx {Scheme Procedure} hashv-create-handle! table key init
3744 @deffnx {Scheme Procedure} hashx-create-handle! hash assoc table key init
3745 @deffnx {C Function} scm_hash_create_handle_x (table, key, init)
3746 @deffnx {C Function} scm_hashq_create_handle_x (table, key, init)
3747 @deffnx {C Function} scm_hashv_create_handle_x (table, key, init)
3748 @deffnx {C Function} scm_hashx_create_handle_x (hash, assoc, table, key, init)
3749 Return the @code{(@var{key} . @var{value})} pair for @var{key} in the
3750 given hash @var{table}. If @var{key} is not in @var{table} then
3751 create an entry for it with @var{init} as the value, and return that
3755 @deffn {Scheme Procedure} hash-map->list proc table
3756 @deffnx {Scheme Procedure} hash-for-each proc table
3757 @deffnx {C Function} scm_hash_map_to_list (proc, table)
3758 @deffnx {C Function} scm_hash_for_each (proc, table)
3759 Apply @var{proc} to the entries in the given hash @var{table}. Each
3760 call is @code{(@var{proc} @var{key} @var{value})}. @code{hash-map->list}
3761 returns a list of the results from these calls, @code{hash-for-each}
3762 discards the results and returns an unspecified value.
3764 Calls are made over the table entries in an unspecified order, and for
3765 @code{hash-map->list} the order of the values in the returned list is
3766 unspecified. Results will be unpredictable if @var{table} is modified
3769 For example the following returns a new alist comprising all the
3770 entries from @code{mytable}, in no particular order.
3773 (hash-map->list cons mytable)
3777 @deffn {Scheme Procedure} hash-for-each-handle proc table
3778 @deffnx {C Function} scm_hash_for_each_handle (proc, table)
3779 Apply @var{proc} to the entries in the given hash @var{table}. Each
3780 call is @code{(@var{proc} @var{handle})}, where @var{handle} is a
3781 @code{(@var{key} . @var{value})} pair. Return an unspecified value.
3783 @code{hash-for-each-handle} differs from @code{hash-for-each} only in
3784 the argument list of @var{proc}.
3787 @deffn {Scheme Procedure} hash-fold proc init table
3788 @deffnx {C Function} scm_hash_fold (proc, init, table)
3789 Accumulate a result by applying @var{proc} to the elements of the
3790 given hash @var{table}. Each call is @code{(@var{proc} @var{key}
3791 @var{value} @var{prior-result})}, where @var{key} and @var{value} are
3792 from the @var{table} and @var{prior-result} is the return from the
3793 previous @var{proc} call. For the first call, @var{prior-result} is
3794 the given @var{init} value.
3796 Calls are made over the table entries in an unspecified order.
3797 Results will be unpredictable if @var{table} is modified while
3798 @code{hash-fold} is running.
3800 For example, the following returns a count of how many keys in
3801 @code{mytable} are strings.
3804 (hash-fold (lambda (key value prior)
3805 (if (string? key) (1+ prior) prior))
3812 @c TeX-master: "guile.texi"