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 pair, or the car of the cdr of
108 a pair, etc., the procedures called @code{caar}, @code{cadr} and so on
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 @deffn {Scheme Procedure} cddr pair
121 @deffnx {Scheme Procedure} cdar pair
122 @deffnx {Scheme Procedure} cadr pair
123 @deffnx {Scheme Procedure} caar pair
124 @deffnx {Scheme Procedure} cdddr pair
125 @deffnx {Scheme Procedure} cddar pair
126 @deffnx {Scheme Procedure} cdadr pair
127 @deffnx {Scheme Procedure} cdaar pair
128 @deffnx {Scheme Procedure} caddr pair
129 @deffnx {Scheme Procedure} cadar pair
130 @deffnx {Scheme Procedure} caadr pair
131 @deffnx {Scheme Procedure} caaar pair
132 @deffnx {Scheme Procedure} cddddr pair
133 @deffnx {Scheme Procedure} cdddar pair
134 @deffnx {Scheme Procedure} cddadr pair
135 @deffnx {Scheme Procedure} cddaar pair
136 @deffnx {Scheme Procedure} cdaddr pair
137 @deffnx {Scheme Procedure} cdadar pair
138 @deffnx {Scheme Procedure} cdaadr pair
139 @deffnx {Scheme Procedure} cdaaar pair
140 @deffnx {Scheme Procedure} cadddr pair
141 @deffnx {Scheme Procedure} caddar pair
142 @deffnx {Scheme Procedure} cadadr pair
143 @deffnx {Scheme Procedure} cadaar pair
144 @deffnx {Scheme Procedure} caaddr pair
145 @deffnx {Scheme Procedure} caadar pair
146 @deffnx {Scheme Procedure} caaadr pair
147 @deffnx {Scheme Procedure} caaaar pair
148 @deffnx {C Function} scm_cddr (pair)
149 @deffnx {C Function} scm_cdar (pair)
150 @deffnx {C Function} scm_cadr (pair)
151 @deffnx {C Function} scm_caar (pair)
152 @deffnx {C Function} scm_cdddr (pair)
153 @deffnx {C Function} scm_cddar (pair)
154 @deffnx {C Function} scm_cdadr (pair)
155 @deffnx {C Function} scm_cdaar (pair)
156 @deffnx {C Function} scm_caddr (pair)
157 @deffnx {C Function} scm_cadar (pair)
158 @deffnx {C Function} scm_caadr (pair)
159 @deffnx {C Function} scm_caaar (pair)
160 @deffnx {C Function} scm_cddddr (pair)
161 @deffnx {C Function} scm_cdddar (pair)
162 @deffnx {C Function} scm_cddadr (pair)
163 @deffnx {C Function} scm_cddaar (pair)
164 @deffnx {C Function} scm_cdaddr (pair)
165 @deffnx {C Function} scm_cdadar (pair)
166 @deffnx {C Function} scm_cdaadr (pair)
167 @deffnx {C Function} scm_cdaaar (pair)
168 @deffnx {C Function} scm_cadddr (pair)
169 @deffnx {C Function} scm_caddar (pair)
170 @deffnx {C Function} scm_cadadr (pair)
171 @deffnx {C Function} scm_cadaar (pair)
172 @deffnx {C Function} scm_caaddr (pair)
173 @deffnx {C Function} scm_caadar (pair)
174 @deffnx {C Function} scm_caaadr (pair)
175 @deffnx {C Function} scm_caaaar (pair)
176 These procedures are compositions of @code{car} and @code{cdr}, where
177 for example @code{caddr} could be defined by
180 (define caddr (lambda (x) (car (cdr (cdr x)))))
185 @deffn {Scheme Procedure} set-car! pair value
186 @deffnx {C Function} scm_set_car_x (pair, value)
187 Stores @var{value} in the car field of @var{pair}. The value returned
188 by @code{set-car!} is unspecified.
192 @deffn {Scheme Procedure} set-cdr! pair value
193 @deffnx {C Function} scm_set_cdr_x (pair, value)
194 Stores @var{value} in the cdr field of @var{pair}. The value returned
195 by @code{set-cdr!} is unspecified.
203 A very important data type in Scheme---as well as in all other Lisp
204 dialects---is the data type @dfn{list}.@footnote{Strictly speaking,
205 Scheme does not have a real datatype @dfn{list}. Lists are made up of
206 @dfn{chained pairs}, and only exist by definition---a list is a chain
207 of pairs which looks like a list.}
209 This is the short definition of what a list is:
213 Either the empty list @code{()},
216 or a pair which has a list in its cdr.
219 @c FIXME::martin: Describe the pair chaining in more detail.
221 @c FIXME::martin: What is a proper, what an improper list?
222 @c What is a circular list?
224 @c FIXME::martin: Maybe steal some graphics from the Elisp reference
228 * List Syntax:: Writing literal lists.
229 * List Predicates:: Testing lists.
230 * List Constructors:: Creating new lists.
231 * List Selection:: Selecting from lists, getting their length.
232 * Append/Reverse:: Appending and reversing lists.
233 * List Modification:: Modifying existing lists.
234 * List Searching:: Searching for list elements
235 * List Mapping:: Applying procedures to lists.
239 @subsubsection List Read Syntax
241 The syntax for lists is an opening parentheses, then all the elements of
242 the list (separated by whitespace) and finally a closing
243 parentheses.@footnote{Note that there is no separation character between
244 the list elements, like a comma or a semicolon.}.
247 (1 2 3) ; @r{a list of the numbers 1, 2 and 3}
248 ("foo" bar 3.1415) ; @r{a string, a symbol and a real number}
249 () ; @r{the empty list}
252 The last example needs a bit more explanation. A list with no elements,
253 called the @dfn{empty list}, is special in some ways. It is used for
254 terminating lists by storing it into the cdr of the last pair that makes
255 up a list. An example will clear that up:
266 This example also shows that lists have to be quoted (REFFIXME) when
267 written, because they would otherwise be mistakingly taken as procedure
268 applications (@pxref{Simple Invocation}).
271 @node List Predicates
272 @subsubsection List Predicates
274 Often it is useful to test whether a given Scheme object is a list or
275 not. List-processing procedures could use this information to test
276 whether their input is valid, or they could do different things
277 depending on the datatype of their arguments.
280 @deffn {Scheme Procedure} list? x
281 @deffnx {C Function} scm_list_p (x)
282 Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
285 The predicate @code{null?} is often used in list-processing code to
286 tell whether a given list has run out of elements. That is, a loop
287 somehow deals with the elements of a list until the list satisfies
288 @code{null?}. Then, the algorithm terminates.
291 @deffn {Scheme Procedure} null? x
292 @deffnx {C Function} scm_null_p (x)
293 Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
296 @deftypefn {C Function} int scm_is_null (SCM x)
297 Return 1 when @var{x} is the empty list; otherwise return 0.
301 @node List Constructors
302 @subsubsection List Constructors
304 This section describes the procedures for constructing new lists.
305 @code{list} simply returns a list where the elements are the arguments,
306 @code{cons*} is similar, but the last argument is stored in the cdr of
307 the last pair of the list.
309 @c C Function scm_list(rest) used to be documented here, but it's a
310 @c no-op since it does nothing but return the list the caller must
311 @c have already created.
313 @deffn {Scheme Procedure} list elem1 @dots{} elemN
314 @deffnx {C Function} scm_list_1 (elem1)
315 @deffnx {C Function} scm_list_2 (elem1, elem2)
316 @deffnx {C Function} scm_list_3 (elem1, elem2, elem3)
317 @deffnx {C Function} scm_list_4 (elem1, elem2, elem3, elem4)
318 @deffnx {C Function} scm_list_5 (elem1, elem2, elem3, elem4, elem5)
319 @deffnx {C Function} scm_list_n (elem1, @dots{}, elemN, @nicode{SCM_UNDEFINED})
321 Return a new list containing elements @var{elem1} to @var{elemN}.
323 @code{scm_list_n} takes a variable number of arguments, terminated by
324 the special @code{SCM_UNDEFINED}. That final @code{SCM_UNDEFINED} is
325 not included in the list. None of @var{elem1} to @var{elemN} can
326 themselves be @code{SCM_UNDEFINED}, or @code{scm_list_n} will
327 terminate at that point.
330 @c C Function scm_cons_star(arg1,rest) used to be documented here,
331 @c but it's not really a useful interface, since it expects the
332 @c caller to have already consed up all but the first argument
335 @deffn {Scheme Procedure} cons* arg1 arg2 @dots{}
336 Like @code{list}, but the last arg provides the tail of the
337 constructed list, returning @code{(cons @var{arg1} (cons
338 @var{arg2} (cons @dots{} @var{argn})))}. Requires at least one
339 argument. If given one argument, that argument is returned as
340 result. This function is called @code{list*} in some other
341 Schemes and in Common LISP.
344 @deffn {Scheme Procedure} list-copy lst
345 @deffnx {C Function} scm_list_copy (lst)
346 Return a (newly-created) copy of @var{lst}.
349 @deffn {Scheme Procedure} make-list n [init]
350 Create a list containing of @var{n} elements, where each element is
351 initialized to @var{init}. @var{init} defaults to the empty list
352 @code{()} if not given.
355 Note that @code{list-copy} only makes a copy of the pairs which make up
356 the spine of the lists. The list elements are not copied, which means
357 that modifying the elements of the new list also modifies the elements
358 of the old list. On the other hand, applying procedures like
359 @code{set-cdr!} or @code{delv!} to the new list will not alter the old
360 list. If you also need to copy the list elements (making a deep copy),
361 use the procedure @code{copy-tree} (@pxref{Copying}).
364 @subsubsection List Selection
366 These procedures are used to get some information about a list, or to
367 retrieve one or more elements of a list.
370 @deffn {Scheme Procedure} length lst
371 @deffnx {C Function} scm_length (lst)
372 Return the number of elements in list @var{lst}.
375 @deffn {Scheme Procedure} last-pair lst
376 @deffnx {C Function} scm_last_pair (lst)
377 Return the last pair in @var{lst}, signalling an error if
378 @var{lst} is circular.
382 @deffn {Scheme Procedure} list-ref list k
383 @deffnx {C Function} scm_list_ref (list, k)
384 Return the @var{k}th element from @var{list}.
388 @deffn {Scheme Procedure} list-tail lst k
389 @deffnx {Scheme Procedure} list-cdr-ref lst k
390 @deffnx {C Function} scm_list_tail (lst, k)
391 Return the "tail" of @var{lst} beginning with its @var{k}th element.
392 The first element of the list is considered to be element 0.
394 @code{list-tail} and @code{list-cdr-ref} are identical. It may help to
395 think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list,
396 or returning the results of cdring @var{k} times down @var{lst}.
399 @deffn {Scheme Procedure} list-head lst k
400 @deffnx {C Function} scm_list_head (lst, k)
401 Copy the first @var{k} elements from @var{lst} into a new list, and
406 @subsubsection Append and Reverse
408 @code{append} and @code{append!} are used to concatenate two or more
409 lists in order to form a new list. @code{reverse} and @code{reverse!}
410 return lists with the same elements as their arguments, but in reverse
411 order. The procedure variants with an @code{!} directly modify the
412 pairs which form the list, whereas the other procedures create new
413 pairs. This is why you should be careful when using the side-effecting
417 @deffn {Scheme Procedure} append lst1 @dots{} lstN
418 @deffnx {Scheme Procedure} append! lst1 @dots{} lstN
419 @deffnx {C Function} scm_append (lstlst)
420 @deffnx {C Function} scm_append_x (lstlst)
421 Return a list comprising all the elements of lists @var{lst1} to
425 (append '(x) '(y)) @result{} (x y)
426 (append '(a) '(b c d)) @result{} (a b c d)
427 (append '(a (b)) '((c))) @result{} (a (b) (c))
430 The last argument @var{lstN} may actually be any object; an improper
431 list results if the last argument is not a proper list.
434 (append '(a b) '(c . d)) @result{} (a b c . d)
435 (append '() 'a) @result{} a
438 @code{append} doesn't modify the given lists, but the return may share
439 structure with the final @var{lstN}. @code{append!} modifies the
440 given lists to form its return.
442 For @code{scm_append} and @code{scm_append_x}, @var{lstlst} is a list
443 of the list operands @var{lst1} @dots{} @var{lstN}. That @var{lstlst}
444 itself is not modified or used in the return.
448 @deffn {Scheme Procedure} reverse lst
449 @deffnx {Scheme Procedure} reverse! lst [newtail]
450 @deffnx {C Function} scm_reverse (lst)
451 @deffnx {C Function} scm_reverse_x (lst, newtail)
452 Return a list comprising the elements of @var{lst}, in reverse order.
454 @code{reverse} constructs a new list, @code{reverse!} modifies
455 @var{lst} in constructing its return.
457 For @code{reverse!}, the optional @var{newtail} is appended to to the
458 result. @var{newtail} isn't reversed, it simply becomes the list
459 tail. For @code{scm_reverse_x}, the @var{newtail} parameter is
460 mandatory, but can be @code{SCM_EOL} if no further tail is required.
463 @node List Modification
464 @subsubsection List Modification
466 The following procedures modify an existing list, either by changing
467 elements of the list, or by changing the list structure itself.
469 @deffn {Scheme Procedure} list-set! list k val
470 @deffnx {C Function} scm_list_set_x (list, k, val)
471 Set the @var{k}th element of @var{list} to @var{val}.
474 @deffn {Scheme Procedure} list-cdr-set! list k val
475 @deffnx {C Function} scm_list_cdr_set_x (list, k, val)
476 Set the @var{k}th cdr of @var{list} to @var{val}.
479 @deffn {Scheme Procedure} delq item lst
480 @deffnx {C Function} scm_delq (item, lst)
481 Return a newly-created copy of @var{lst} with elements
482 @code{eq?} to @var{item} removed. This procedure mirrors
483 @code{memq}: @code{delq} compares elements of @var{lst} against
484 @var{item} with @code{eq?}.
487 @deffn {Scheme Procedure} delv item lst
488 @deffnx {C Function} scm_delv (item, lst)
489 Return a newly-created copy of @var{lst} with elements
490 @code{eqv?} to @var{item} removed. This procedure mirrors
491 @code{memv}: @code{delv} compares elements of @var{lst} against
492 @var{item} with @code{eqv?}.
495 @deffn {Scheme Procedure} delete item lst
496 @deffnx {C Function} scm_delete (item, lst)
497 Return a newly-created copy of @var{lst} with elements
498 @code{equal?} to @var{item} removed. This procedure mirrors
499 @code{member}: @code{delete} compares elements of @var{lst}
500 against @var{item} with @code{equal?}.
503 @deffn {Scheme Procedure} delq! item lst
504 @deffnx {Scheme Procedure} delv! item lst
505 @deffnx {Scheme Procedure} delete! item lst
506 @deffnx {C Function} scm_delq_x (item, lst)
507 @deffnx {C Function} scm_delv_x (item, lst)
508 @deffnx {C Function} scm_delete_x (item, lst)
509 These procedures are destructive versions of @code{delq}, @code{delv}
510 and @code{delete}: they modify the pointers in the existing @var{lst}
511 rather than creating a new list. Caveat evaluator: Like other
512 destructive list functions, these functions cannot modify the binding of
513 @var{lst}, and so cannot be used to delete the first element of
514 @var{lst} destructively.
517 @deffn {Scheme Procedure} delq1! item lst
518 @deffnx {C Function} scm_delq1_x (item, lst)
519 Like @code{delq!}, but only deletes the first occurrence of
520 @var{item} from @var{lst}. Tests for equality using
521 @code{eq?}. See also @code{delv1!} and @code{delete1!}.
524 @deffn {Scheme Procedure} delv1! item lst
525 @deffnx {C Function} scm_delv1_x (item, lst)
526 Like @code{delv!}, but only deletes the first occurrence of
527 @var{item} from @var{lst}. Tests for equality using
528 @code{eqv?}. See also @code{delq1!} and @code{delete1!}.
531 @deffn {Scheme Procedure} delete1! item lst
532 @deffnx {C Function} scm_delete1_x (item, lst)
533 Like @code{delete!}, but only deletes the first occurrence of
534 @var{item} from @var{lst}. Tests for equality using
535 @code{equal?}. See also @code{delq1!} and @code{delv1!}.
538 @deffn {Scheme Procedure} filter pred lst
539 @deffnx {Scheme Procedure} filter! pred lst
540 Return a list containing all elements from @var{lst} which satisfy the
541 predicate @var{pred}. The elements in the result list have the same
542 order as in @var{lst}. The order in which @var{pred} is applied to
543 the list elements is not specified.
545 @code{filter!} is allowed, but not required to modify the structure of
549 @subsubsection List Searching
551 The following procedures search lists for particular elements. They use
552 different comparison predicates for comparing list elements with the
553 object to be searched. When they fail, they return @code{#f}, otherwise
554 they return the sublist whose car is equal to the search object, where
555 equality depends on the equality predicate used.
558 @deffn {Scheme Procedure} memq x lst
559 @deffnx {C Function} scm_memq (x, lst)
560 Return the first sublist of @var{lst} whose car is @code{eq?}
561 to @var{x} where the sublists of @var{lst} are the non-empty
562 lists returned by @code{(list-tail @var{lst} @var{k})} for
563 @var{k} less than the length of @var{lst}. If @var{x} does not
564 occur in @var{lst}, then @code{#f} (not the empty list) is
569 @deffn {Scheme Procedure} memv x lst
570 @deffnx {C Function} scm_memv (x, lst)
571 Return the first sublist of @var{lst} whose car is @code{eqv?}
572 to @var{x} where the sublists of @var{lst} are the non-empty
573 lists returned by @code{(list-tail @var{lst} @var{k})} for
574 @var{k} less than the length of @var{lst}. If @var{x} does not
575 occur in @var{lst}, then @code{#f} (not the empty list) is
580 @deffn {Scheme Procedure} member x lst
581 @deffnx {C Function} scm_member (x, lst)
582 Return the first sublist of @var{lst} whose car is
583 @code{equal?} to @var{x} where the sublists of @var{lst} are
584 the non-empty lists returned by @code{(list-tail @var{lst}
585 @var{k})} for @var{k} less than the length of @var{lst}. If
586 @var{x} does not occur in @var{lst}, then @code{#f} (not the
587 empty list) is returned.
592 @subsubsection List Mapping
594 List processing is very convenient in Scheme because the process of
595 iterating over the elements of a list can be highly abstracted. The
596 procedures in this section are the most basic iterating procedures for
597 lists. They take a procedure and one or more lists as arguments, and
598 apply the procedure to each element of the list. They differ in their
602 @c begin (texi-doc-string "guile" "map")
603 @deffn {Scheme Procedure} map proc arg1 arg2 @dots{}
604 @deffnx {Scheme Procedure} map-in-order proc arg1 arg2 @dots{}
605 @deffnx {C Function} scm_map (proc, arg1, args)
606 Apply @var{proc} to each element of the list @var{arg1} (if only two
607 arguments are given), or to the corresponding elements of the argument
608 lists (if more than two arguments are given). The result(s) of the
609 procedure applications are saved and returned in a list. For
610 @code{map}, the order of procedure applications is not specified,
611 @code{map-in-order} applies the procedure from left to right to the list
616 @c begin (texi-doc-string "guile" "for-each")
617 @deffn {Scheme Procedure} for-each proc arg1 arg2 @dots{}
618 Like @code{map}, but the procedure is always applied from left to right,
619 and the result(s) of the procedure applications are thrown away. The
620 return value is not specified.
628 Vectors are sequences of Scheme objects. Unlike lists, the length of a
629 vector, once the vector is created, cannot be changed. The advantage of
630 vectors over lists is that the time required to access one element of a vector
631 given its @dfn{position} (synonymous with @dfn{index}), a zero-origin number,
632 is constant, whereas lists have an access time linear to the position of the
633 accessed element in the list.
635 Vectors can contain any kind of Scheme object; it is even possible to
636 have different types of objects in the same vector. For vectors
637 containing vectors, you may wish to use arrays, instead. Note, too,
638 that vectors are the special case of non-uniform, one-dimensional
639 arrays and that most array procedures operate happily on vectors
642 C code must deal with the additional distinction between @dfn{simple}
643 and non-@dfn{simple} vector. A simple vector is one whose elements
644 are stored in contiguous memory locations. Most vectors are simple,
645 but some vectors produced by @code{make-shared-array} are not.
648 * Vector Syntax:: Read syntax for vectors.
649 * Vector Creation:: Dynamic vector creation and validation.
650 * Vector Accessors:: Accessing and modifying vector contents.
655 @subsubsection Read Syntax for Vectors
657 Vectors can literally be entered in source code, just like strings,
658 characters or some of the other data types. The read syntax for vectors
659 is as follows: A sharp sign (@code{#}), followed by an opening
660 parentheses, all elements of the vector in their respective read syntax,
661 and finally a closing parentheses. The following are examples of the
662 read syntax for vectors; where the first vector only contains numbers
663 and the second three different object types: a string, a symbol and a
664 number in hexadecimal notation.
668 #("Hello" foo #xdeadbeef)
671 Like lists, vectors have to be quoted (REFFIXME):
674 '#(a b c) @result{} #(a b c)
677 @node Vector Creation
678 @subsubsection Dynamic Vector Creation and Validation
680 Instead of creating a vector implicitly by using the read syntax just
681 described, you can create a vector dynamically by calling one of the
682 @code{vector} and @code{list->vector} primitives with the list of Scheme
683 values that you want to place into a vector. The size of the vector
684 thus created is determined implicitly by the number of arguments given.
687 @rnindex list->vector
688 @deffn {Scheme Procedure} vector . l
689 @deffnx {Scheme Procedure} list->vector l
690 @deffnx {C Function} scm_vector (l)
691 Return a newly allocated vector composed of the
692 given arguments. Analogous to @code{list}.
695 (vector 'a 'b 'c) @result{} #(a b c)
699 (As an aside, an interesting implementation detail is that the Guile
700 reader reads the @code{#(@dots{})} syntax by reading everything but the
701 initial @code{#} as a @emph{list}, and then passing the list that
702 results to @code{list->vector}. Notice how neatly this fits with the
703 similarity between the read (and print) syntaxes for lists and vectors.)
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} (s @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-move-left! vec1 start1 end1 vec2 start2
822 @deffnx {C Function} scm_vector_move_left_x (vec1, start1, end1, vec2, start2)
823 Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
824 to @var{vec2} starting at position @var{start2}. @var{start1} and
825 @var{start2} are inclusive indices; @var{end1} is exclusive.
827 @code{vector-move-left!} copies elements in leftmost order.
828 Therefore, in the case where @var{vec1} and @var{vec2} refer to the
829 same vector, @code{vector-move-left!} is usually appropriate when
830 @var{start1} is greater than @var{start2}.
833 @deffn {Scheme Procedure} vector-move-right! vec1 start1 end1 vec2 start2
834 @deffnx {C Function} scm_vector_move_right_x (vec1, start1, end1, vec2, start2)
835 Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
836 to @var{vec2} starting at position @var{start2}. @var{start1} and
837 @var{start2} are inclusive indices; @var{end1} is exclusive.
839 @code{vector-move-right!} copies elements in rightmost order.
840 Therefore, in the case where @var{vec1} and @var{vec2} refer to the
841 same vector, @code{vector-move-right!} is usually appropriate when
842 @var{start1} is less than @var{start2}.
845 @deftypefn {C Function} {const SCM *} scm_vector_elements (SCM vec)
846 Return a pointer to the memory that holds the elements of @var{vec}
847 for reading. The vector @var{vec} must be simple.
849 For each call to this function, you must call
850 @code{scm_vector_release_elements} and after that call the pointer to
851 the elements becomes invalid.
854 @deftypefn {C Function} void scm_vector_release_elements (SCM vec)
855 Finish the access to the elements of a simple vector, as exlained above.
858 @deftypefn {C Function} void scm_frame_vector_release_elements (SCM vec)
859 Arrange for @code{scm_vector_release_elements} to be called with @var{vec}
860 when the current frame is unwound, implicitely or explicitely;
864 @deftypefn {C Function} SCM *scm_vector_writable_elements (SCM vec)
865 Return a pointer to the memory that holds the elements of @var{vec}
866 for writing. The vector @var{vec} must be simple.
868 For each call to this function, you must call
869 @code{scm_vector_release_writable_elements} and after that call the
870 pointer to the elements becomes invalid.
873 @deftypefn {C Function} void scm_vector_release_writable_elements (SCM vec)
874 Finish the access to the elements of a vector, as exlained above.
877 @deftypefn {C Function} void scm_frame_vector_release_writable_elements (SCM vec)
878 Arrange for @code{scm_vector_release_writable_elements} to be called
879 with @var{vec} when the current frame is unwound, implicitely or
880 explicitely; @xref{Frames}.
883 @node Uniform Numeric Vectors
884 @subsection Uniform Numeric Vectors
886 A uniform numeric vector is a vector whose elements are all of a single
887 numeric type. Guile offers uniform vectors for signed and unsigned
888 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of floating point
889 values, and complex floating-point numbers of these two sizes.
891 Strings could be regarded as uniform vectors of characters,
892 @xref{Strings}. Likewise, bit vectors could be regarded as uniform
893 vectors of bits, @xref{Bit Vectors}. Both are sufficiently different
894 from numeric vectors that the procedures described here do not apply to
895 these two data types. However, both strings and bit vectors are
896 generalized vectors, @xref{Generalized Vectors}, and arrays,
899 Uniform numeric vectors are the special case of one-dimensional, uniform
900 numeric, zero-origin arrays.
902 Uniform numeric vectors can be useful since they consume less memory
903 than the non-uniform, general vectors. Also, since the types they can
904 store correspond directly to C types, it is easier to work with them
905 efficiently on a low level. Consider image processing as an example,
906 where you want to apply a filter to some image. While you could store
907 the pixels of an image in a general vector and write a general
908 convolution function, things are much more efficient with uniform
909 vectors: the convolution function knows that all pixels are unsigned
910 8-bit values (say), and can use a very tight inner loop.
912 That is, when it is written in C. Functions for efficiently working
913 with uniform numeric vectors from C are listed at the end of this
916 Procedures similar to the vector procedures (@pxref{Vectors}) are
917 provided for handling these uniform vectors, but they are distinct
918 datatypes and the two cannot be inter-mixed. If you want to work
919 primarily with uniform numeric vectors, but want to offer support for
920 general vectors as a convenience, you can use one of the
921 @code{scm_any_to_*} functions. They will coerce lists and vectors to
922 the given type of uniform vector.
924 One set of these procedures is a generic one: it works with all types of
925 uniform vectors. In addition to that, there is a set of procedures for
926 each type that only works with that type. Unless you really need to the
927 generality of the first set, it is best to use the more specific
928 functions. They might not be that much faster, but their use can serve
929 as a kind of declaration and makes it easier to optimize later on.
931 The generic set of procedures uses @code{uniform-vector} in its names,
932 the specific ones use the tag from the following table.
936 unsigned 8-bit integers
939 signed 8-bit integers
942 unsigned 16-bit integers
945 signed 16-bit integers
948 unsigned 32-bit integers
951 signed 32-bit integers
954 unsigned 64-bit integers
957 signed 64-bit integers
960 the C type @code{float}
963 the C type @code{double}
966 complex numbers in rectangular form with the real and imaginary part
970 complex numbers in rectangular form with the real and imaginary part
971 being a @code{double}
975 The external representation (ie.@: read syntax) for these vectors is
976 similar to normal Scheme vectors, but with an additional tag from the
977 tabel above indiciating the vector's type. For example,
984 Note that the read syntax for floating-point here conflicts with
985 @code{#f} for false. In Standard Scheme one can write @code{(1 #f3)}
986 for a three element list @code{(1 #f 3)}, but for Guile @code{(1 #f3)}
987 is invalid. @code{(1 #f 3)} is almost certainly what one should write
988 anyway to make the intention clear, so this is rarely a problem.
990 @deffn {Scheme Procedure} uniform-vector? obj
991 @deffnx {Scheme Procedure} u8vector? obj
992 @deffnx {Scheme Procedure} s8vector? obj
993 @deffnx {Scheme Procedure} u16vector? obj
994 @deffnx {Scheme Procedure} s16vector? obj
995 @deffnx {Scheme Procedure} u32vector? obj
996 @deffnx {Scheme Procedure} s32vector? obj
997 @deffnx {Scheme Procedure} u64vector? obj
998 @deffnx {Scheme Procedure} s64vector? obj
999 @deffnx {Scheme Procedure} f32vector? obj
1000 @deffnx {Scheme Procedure} f64vector? obj
1001 @deffnx {Scheme Procedure} c32vector? obj
1002 @deffnx {Scheme Procedure} c64vector? obj
1003 @deffnx {C Function} scm_uniform_vector_p obj
1004 @deffnx {C Function} scm_u8vector_p obj
1005 @deffnx {C Function} scm_s8vector_p obj
1006 @deffnx {C Function} scm_u16vector_p obj
1007 @deffnx {C Function} scm_s16vector_p obj
1008 @deffnx {C Function} scm_u32vector_p obj
1009 @deffnx {C Function} scm_s32vector_p obj
1010 @deffnx {C Function} scm_u64vector_p obj
1011 @deffnx {C Function} scm_s64vector_p obj
1012 @deffnx {C Function} scm_f32vector_p obj
1013 @deffnx {C Function} scm_f64vector_p obj
1014 @deffnx {C Function} scm_c32vector_p obj
1015 @deffnx {C Function} scm_c64vector_p obj
1016 Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
1020 @deffn {Scheme Procedure} make-u8vector n [value]
1021 @deffnx {Scheme Procedure} make-s8vector n [value]
1022 @deffnx {Scheme Procedure} make-u16vector n [value]
1023 @deffnx {Scheme Procedure} make-s16vector n [value]
1024 @deffnx {Scheme Procedure} make-u32vector n [value]
1025 @deffnx {Scheme Procedure} make-s32vector n [value]
1026 @deffnx {Scheme Procedure} make-u64vector n [value]
1027 @deffnx {Scheme Procedure} make-s64vector n [value]
1028 @deffnx {Scheme Procedure} make-f32vector n [value]
1029 @deffnx {Scheme Procedure} make-f64vector n [value]
1030 @deffnx {Scheme Procedure} make-c32vector n [value]
1031 @deffnx {Scheme Procedure} make-c64vector n [value]
1032 @deffnx {C Function} scm_make_u8vector n [value]
1033 @deffnx {C Function} scm_make_s8vector n [value]
1034 @deffnx {C Function} scm_make_u16vector n [value]
1035 @deffnx {C Function} scm_make_s16vector n [value]
1036 @deffnx {C Function} scm_make_u32vector n [value]
1037 @deffnx {C Function} scm_make_s32vector n [value]
1038 @deffnx {C Function} scm_make_u64vector n [value]
1039 @deffnx {C Function} scm_make_s64vector n [value]
1040 @deffnx {C Function} scm_make_f32vector n [value]
1041 @deffnx {C Function} scm_make_f64vector n [value]
1042 @deffnx {C Function} scm_make_c32vector n [value]
1043 @deffnx {C Function} scm_make_c64vector n [value]
1044 Return a newly allocated homogeneous numeric vector holding @var{n}
1045 elements of the indicated type. If @var{value} is given, the vector
1046 is initialized with that value, otherwise the contents are
1050 @deffn {Scheme Procedure} u8vector value @dots{}
1051 @deffnx {Scheme Procedure} s8vector value @dots{}
1052 @deffnx {Scheme Procedure} u16vector value @dots{}
1053 @deffnx {Scheme Procedure} s16vector value @dots{}
1054 @deffnx {Scheme Procedure} u32vector value @dots{}
1055 @deffnx {Scheme Procedure} s32vector value @dots{}
1056 @deffnx {Scheme Procedure} u64vector value @dots{}
1057 @deffnx {Scheme Procedure} s64vector value @dots{}
1058 @deffnx {Scheme Procedure} f32vector value @dots{}
1059 @deffnx {Scheme Procedure} f64vector value @dots{}
1060 @deffnx {Scheme Procedure} c32vector value @dots{}
1061 @deffnx {Scheme Procedure} c64vector value @dots{}
1062 @deffnx {C Function} scm_u8vector values
1063 @deffnx {C Function} scm_s8vector values
1064 @deffnx {C Function} scm_u16vector values
1065 @deffnx {C Function} scm_s16vector values
1066 @deffnx {C Function} scm_u32vector values
1067 @deffnx {C Function} scm_s32vector values
1068 @deffnx {C Function} scm_u64vector values
1069 @deffnx {C Function} scm_s64vector values
1070 @deffnx {C Function} scm_f32vector values
1071 @deffnx {C Function} scm_f64vector values
1072 @deffnx {C Function} scm_c32vector values
1073 @deffnx {C Function} scm_c64vector values
1074 Return a newly allocated homogeneous numeric vector of the indicated
1075 type, holding the given parameter @var{value}s. The vector length is
1076 the number of parameters given.
1079 @deffn {Scheme Procedure} uniform-vector-length vec
1080 @deffnx {Scheme Procedure} u8vector-length vec
1081 @deffnx {Scheme Procedure} s8vector-length vec
1082 @deffnx {Scheme Procedure} u16vector-length vec
1083 @deffnx {Scheme Procedure} s16vector-length vec
1084 @deffnx {Scheme Procedure} u32vector-length vec
1085 @deffnx {Scheme Procedure} s32vector-length vec
1086 @deffnx {Scheme Procedure} u64vector-length vec
1087 @deffnx {Scheme Procedure} s64vector-length vec
1088 @deffnx {Scheme Procedure} f32vector-length vec
1089 @deffnx {Scheme Procedure} f64vector-length vec
1090 @deffnx {Scheme Procedure} c32vector-length vec
1091 @deffnx {Scheme Procedure} c64vector-length vec
1092 @deffnx {C Function} scm_uniform_vector_length vec
1093 @deffnx {C Function} scm_u8vector_length vec
1094 @deffnx {C Function} scm_s8vector_length vec
1095 @deffnx {C Function} scm_u16vector_length vec
1096 @deffnx {C Function} scm_s16vector_length vec
1097 @deffnx {C Function} scm_u32vector_length vec
1098 @deffnx {C Function} scm_s32vector_length vec
1099 @deffnx {C Function} scm_u64vector_length vec
1100 @deffnx {C Function} scm_s64vector_length vec
1101 @deffnx {C Function} scm_f32vector_length vec
1102 @deffnx {C Function} scm_f64vector_length vec
1103 @deffnx {C Function} scm_c32vector_length vec
1104 @deffnx {C Function} scm_c64vector_length vec
1105 Return the number of elements in @var{vec}.
1108 @deffn {Scheme Procedure} uniform-vector-ref vec i
1109 @deffnx {Scheme Procedure} u8vector-ref vec i
1110 @deffnx {Scheme Procedure} s8vector-ref vec i
1111 @deffnx {Scheme Procedure} u16vector-ref vec i
1112 @deffnx {Scheme Procedure} s16vector-ref vec i
1113 @deffnx {Scheme Procedure} u32vector-ref vec i
1114 @deffnx {Scheme Procedure} s32vector-ref vec i
1115 @deffnx {Scheme Procedure} u64vector-ref vec i
1116 @deffnx {Scheme Procedure} s64vector-ref vec i
1117 @deffnx {Scheme Procedure} f32vector-ref vec i
1118 @deffnx {Scheme Procedure} f64vector-ref vec i
1119 @deffnx {Scheme Procedure} c32vector-ref vec i
1120 @deffnx {Scheme Procedure} c64vector-ref vec i
1121 @deffnx {C Function} scm_uniform_vector_ref vec i
1122 @deffnx {C Function} scm_u8vector_ref vec i
1123 @deffnx {C Function} scm_s8vector_ref vec i
1124 @deffnx {C Function} scm_u16vector_ref vec i
1125 @deffnx {C Function} scm_s16vector_ref vec i
1126 @deffnx {C Function} scm_u32vector_ref vec i
1127 @deffnx {C Function} scm_s32vector_ref vec i
1128 @deffnx {C Function} scm_u64vector_ref vec i
1129 @deffnx {C Function} scm_s64vector_ref vec i
1130 @deffnx {C Function} scm_f32vector_ref vec i
1131 @deffnx {C Function} scm_f64vector_ref vec i
1132 @deffnx {C Function} scm_c32vector_ref vec i
1133 @deffnx {C Function} scm_c64vector_ref vec i
1134 Return the element at index @var{i} in @var{vec}. The first element
1135 in @var{vec} is index 0.
1138 @deffn {Scheme Procedure} uniform-vector-set! vec i value
1139 @deffnx {Scheme Procedure} u8vector-set! vec i value
1140 @deffnx {Scheme Procedure} s8vector-set! vec i value
1141 @deffnx {Scheme Procedure} u16vector-set! vec i value
1142 @deffnx {Scheme Procedure} s16vector-set! vec i value
1143 @deffnx {Scheme Procedure} u32vector-set! vec i value
1144 @deffnx {Scheme Procedure} s32vector-set! vec i value
1145 @deffnx {Scheme Procedure} u64vector-set! vec i value
1146 @deffnx {Scheme Procedure} s64vector-set! vec i value
1147 @deffnx {Scheme Procedure} f32vector-set! vec i value
1148 @deffnx {Scheme Procedure} f64vector-set! vec i value
1149 @deffnx {Scheme Procedure} c32vector-set! vec i value
1150 @deffnx {Scheme Procedure} c64vector-set! vec i value
1151 @deffnx {C Function} scm_uniform_vector_set_x vec i value
1152 @deffnx {C Function} scm_u8vector_set_x vec i value
1153 @deffnx {C Function} scm_s8vector_set_x vec i value
1154 @deffnx {C Function} scm_u16vector_set_x vec i value
1155 @deffnx {C Function} scm_s16vector_set_x vec i value
1156 @deffnx {C Function} scm_u32vector_set_x vec i value
1157 @deffnx {C Function} scm_s32vector_set_x vec i value
1158 @deffnx {C Function} scm_u64vector_set_x vec i value
1159 @deffnx {C Function} scm_s64vector_set_x vec i value
1160 @deffnx {C Function} scm_f32vector_set_x vec i value
1161 @deffnx {C Function} scm_f64vector_set_x vec i value
1162 @deffnx {C Function} scm_c32vector_set_x vec i value
1163 @deffnx {C Function} scm_c64vector_set_x vec i value
1164 Set the element at index @var{i} in @var{vec} to @var{value}. The
1165 first element in @var{vec} is index 0. The return value is
1169 @deffn {Scheme Procedure} uniform-vector->list vec
1170 @deffnx {Scheme Procedure} u8vector->list vec
1171 @deffnx {Scheme Procedure} s8vector->list vec
1172 @deffnx {Scheme Procedure} u16vector->list vec
1173 @deffnx {Scheme Procedure} s16vector->list vec
1174 @deffnx {Scheme Procedure} u32vector->list vec
1175 @deffnx {Scheme Procedure} s32vector->list vec
1176 @deffnx {Scheme Procedure} u64vector->list vec
1177 @deffnx {Scheme Procedure} s64vector->list vec
1178 @deffnx {Scheme Procedure} f32vector->list vec
1179 @deffnx {Scheme Procedure} f64vector->list vec
1180 @deffnx {Scheme Procedure} c32vector->list vec
1181 @deffnx {Scheme Procedure} c64vector->list vec
1182 @deffnx {C Function} scm_uniform_vector_to_list vec
1183 @deffnx {C Function} scm_u8vector_to_list vec
1184 @deffnx {C Function} scm_s8vector_to_list vec
1185 @deffnx {C Function} scm_u16vector_to_list vec
1186 @deffnx {C Function} scm_s16vector_to_list vec
1187 @deffnx {C Function} scm_u32vector_to_list vec
1188 @deffnx {C Function} scm_s32vector_to_list vec
1189 @deffnx {C Function} scm_u64vector_to_list vec
1190 @deffnx {C Function} scm_s64vector_to_list vec
1191 @deffnx {C Function} scm_f32vector_to_list vec
1192 @deffnx {C Function} scm_f64vector_to_list vec
1193 @deffnx {C Function} scm_c32vector_to_list vec
1194 @deffnx {C Function} scm_c64vector_to_list vec
1195 Return a newly allocated list holding all elements of @var{vec}.
1198 @deffn {Scheme Procedure} list->u8vector lst
1199 @deffnx {Scheme Procedure} list->s8vector lst
1200 @deffnx {Scheme Procedure} list->u16vector lst
1201 @deffnx {Scheme Procedure} list->s16vector lst
1202 @deffnx {Scheme Procedure} list->u32vector lst
1203 @deffnx {Scheme Procedure} list->s32vector lst
1204 @deffnx {Scheme Procedure} list->u64vector lst
1205 @deffnx {Scheme Procedure} list->s64vector lst
1206 @deffnx {Scheme Procedure} list->f32vector lst
1207 @deffnx {Scheme Procedure} list->f64vector lst
1208 @deffnx {Scheme Procedure} list->c32vector lst
1209 @deffnx {Scheme Procedure} list->c64vector lst
1210 @deffnx {C Function} scm_list_to_u8vector lst
1211 @deffnx {C Function} scm_list_to_s8vector lst
1212 @deffnx {C Function} scm_list_to_u16vector lst
1213 @deffnx {C Function} scm_list_to_s16vector lst
1214 @deffnx {C Function} scm_list_to_u32vector lst
1215 @deffnx {C Function} scm_list_to_s32vector lst
1216 @deffnx {C Function} scm_list_to_u64vector lst
1217 @deffnx {C Function} scm_list_to_s64vector lst
1218 @deffnx {C Function} scm_list_to_f32vector lst
1219 @deffnx {C Function} scm_list_to_f64vector lst
1220 @deffnx {C Function} scm_list_to_c32vector lst
1221 @deffnx {C Function} scm_list_to_c64vector lst
1222 Return a newly allocated homogeneous numeric vector of the indicated type,
1223 initialized with the elements of the list @var{lst}.
1226 @deffn {Scheme Procedure} any->u8vector obj
1227 @deffnx {Scheme Procedure} any->s8vector obj
1228 @deffnx {Scheme Procedure} any->u16vector obj
1229 @deffnx {Scheme Procedure} any->s16vector obj
1230 @deffnx {Scheme Procedure} any->u32vector obj
1231 @deffnx {Scheme Procedure} any->s32vector obj
1232 @deffnx {Scheme Procedure} any->u64vector obj
1233 @deffnx {Scheme Procedure} any->s64vector obj
1234 @deffnx {Scheme Procedure} any->f32vector obj
1235 @deffnx {Scheme Procedure} any->f64vector obj
1236 @deffnx {Scheme Procedure} any->c32vector obj
1237 @deffnx {Scheme Procedure} any->c64vector obj
1238 @deffnx {C Function} scm_any_to_u8vector obj
1239 @deffnx {C Function} scm_any_to_s8vector obj
1240 @deffnx {C Function} scm_any_to_u16vector obj
1241 @deffnx {C Function} scm_any_to_s16vector obj
1242 @deffnx {C Function} scm_any_to_u32vector obj
1243 @deffnx {C Function} scm_any_to_s32vector obj
1244 @deffnx {C Function} scm_any_to_u64vector obj
1245 @deffnx {C Function} scm_any_to_s64vector obj
1246 @deffnx {C Function} scm_any_to_f32vector obj
1247 @deffnx {C Function} scm_any_to_f64vector obj
1248 @deffnx {C Function} scm_any_to_c32vector obj
1249 @deffnx {C Function} scm_any_to_c64vector obj
1250 Return a newly allocated homogeneous numeric vector of the indicated
1251 type, initialized with the elements of @var{obj}, which must be a list,
1252 a vector, or a uniform vector.
1255 @deftypefn {C Function} int scm_is_uniform_vector (SCM uvec)
1256 Return @code{1} when @var{uvec} is a uniform vector, @code{0} otherwise.
1259 @deftypefn {C Function} SCM scm_take_u8vector (const scm_t_uint8 *data, size_t len)
1260 @deftypefnx {C Function} SCM scm_take_s8vector (const scm_t_int8 *data, size_t len)
1261 @deftypefnx {C Function} SCM scm_take_u16vector (const scm_t_uint16 *data, size_t len)
1262 @deftypefnx {C Function} SCM scm_take_s168vector (const scm_t_int16 *data, size_t len)
1263 @deftypefnx {C Function} SCM scm_take_u32vector (const scm_t_uint32 *data, size_t len)
1264 @deftypefnx {C Function} SCM scm_take_s328vector (const scm_t_int32 *data, size_t len)
1265 @deftypefnx {C Function} SCM scm_take_u64vector (const scm_t_uint64 *data, size_t len)
1266 @deftypefnx {C Function} SCM scm_take_s64vector (const scm_t_int64 *data, size_t len)
1267 @deftypefnx {C Function} SCM scm_take_f32vector (const float *data, size_t len)
1268 @deftypefnx {C Function} SCM scm_take_f64vector (const double *data, size_t len)
1269 @deftypefnx {C Function} SCM scm_take_c32vector (const float *data, size_t len)
1270 @deftypefnx {C Function} SCM scm_take_c64vector (const double *data, size_t len)
1271 Return a new uniform vector of the indicated type and length that uses
1272 the memory pointed to by @var{data} to store its elements. This memory
1273 will eventually be freed with @code{free}. The argument @var{len}
1274 specifies the number of elements in @var{data}, not its size in bytes.
1276 The @code{c32} and @code{c64} variants take a pointer to a C array of
1277 @code{float}s or @code{double}s. The real parts of the complex numbers
1278 are at even indices in that array, the corresponding imaginary parts are
1279 at the following odd index.
1282 @deftypefn {C Function} {const void *} scm_uniform_vector_elements (SCM uvec)
1283 @deftypefnx {C Function} {const scm_t_uint8 *} scm_u8vector_elements (SCM uvec)
1284 @deftypefnx {C Function} {const scm_t_int8 *} scm_s8vector_elements (SCM uvec)
1285 @deftypefnx {C Function} {const scm_t_uint16 *} scm_u16vector_elements (SCM uvec)
1286 @deftypefnx {C Function} {const scm_t_int16 *} scm_s16vector_elements (SCM uvec)
1287 @deftypefnx {C Function} {const scm_t_uint32 *} scm_u32vector_elements (SCM uvec)
1288 @deftypefnx {C Function} {const scm_t_int32 *} scm_s32vector_elements (SCM uvec)
1289 @deftypefnx {C Function} {const scm_t_uint64 *} scm_u64vector_elements (SCM uvec)
1290 @deftypefnx {C Function} {const scm_t_int64 *} scm_s64vector_elements (SCM uvec)
1291 @deftypefnx {C Function} {const float *} scm_f32vector_elements (SCM uvec)
1292 @deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM uvec)
1293 @deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM uvec)
1294 @deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM uvec)
1295 Return a pointer to the elements of a uniform vector for reading. For
1296 each call to one of these functions, you must call
1297 @code{scm_uniform_vector_release_elements} and after that call the pointer to
1298 the elements becomes invalid.
1300 The @code{c32} and @code{c64} variants return pointers to a C array of
1301 @code{float}s or @code{double}s. The real parts of the complex numbers
1302 are at even indices in that array, the corresponding imaginary parts are
1303 at the following odd index.
1306 @deftypefn {C Function} void scm_uniform_vector_release_elements (SCM uvec)
1307 Finish the access to the elements of a uniform vector, as exlained
1311 @deftypefn {C Function} void scm_frame_uniform_vector_release_elements (SCM uvec)
1312 Arrange for @code{scm_uniform_vector_release_elements} to be called with
1313 @var{uvec} when the current frame is unwound, implicitely or
1314 explicitely; @xref{Frames}.
1317 @deftypefn {C Function} {void *} scm_uniform_vector_writable_elements (SCM uvec)
1318 @deftypefnx {C Function} {scm_t_uint8 *} scm_u8vector_writable_elements (SCM uvec)
1319 @deftypefnx {C Function} {scm_t_int8 *} scm_s8vector_writable_elements (SCM uvec)
1320 @deftypefnx {C Function} {scm_t_uint16 *} scm_u16vector_writable_elements (SCM uvec)
1321 @deftypefnx {C Function} {scm_t_int16 *} scm_s16vector_writable_elements (SCM uvec)
1322 @deftypefnx {C Function} {scm_t_uint32 *} scm_u32vector_writable_elements (SCM uvec)
1323 @deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_writable_elements (SCM uvec)
1324 @deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_writable_elements (SCM uvec)
1325 @deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_writable_elements (SCM uvec)
1326 @deftypefnx {C Function} {float *} scm_f32vector_writable_elements (SCM uvec)
1327 @deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM uvec)
1328 @deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM uvec)
1329 @deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM uvec)
1330 Return a pointer to the elements of a uniform vector for writing. For
1331 each call to one of these functions, you must call
1332 @code{scm_uniform_vector_release_writable_elements} and after that
1333 call the pointer to the elements becomes invalid.
1335 The @code{c32} and @code{c64} variants return pointers to a C array of
1336 @code{float}s or @code{double}s. The real parts of the complex numbers
1337 are at even indices in that array, the corresponding imaginary parts are
1338 at the following odd index.
1341 @deftypefn {C Function} void scm_uniform_vector_release_writable_elements (SCM uvec)
1342 Finish the access to the elements of a uniform vector, as exlained
1346 @deftypefn {C Function} void scm_frame_uniform_vector_release_writable_elements (SCM uvec)
1347 Arrange for @code{scm_uniform_vector_release_writable_elements} to be called with
1348 @var{uvec} when the current frame is unwound, implicitely or
1349 explicitely; @xref{Frames}.
1352 @deftypefn {C Function} size_t scm_c_uniform_vector_length (SCM uvec)
1353 Return the number of elements of @var{uvec} as a @code{size_t}.
1356 @deftypefn {C Function} size_t scm_c_uniform_vector_element_size (SCM uvec)
1357 Return the number of bytes of one element of @var{uvec}.
1360 @deftypefn {C Function} size_t scm_c_uniform_vector_size (SCM uvec)
1361 Return the number of bytes used by all elements of @var{uvec}. This is
1362 just @code{scm_c_uniform_vector_length (@var{uvec}) *
1363 scm_c_uniform_vector_element_size (@var{uvec})}.
1368 @subsection Bit Vectors
1371 Bit vectors are zero-origin, one-dimensional arrays of booleans. They
1372 are displayed as a sequence of @code{0}s and @code{1}s prefixed by
1376 (make-bitvector 8 #f) @result{}
1380 Bit vectors are are also generalized vectors, @xref{Generalized
1381 Vectors}, and can thus be used with the array procedures, @xref{Arrays}.
1383 @deffn {Scheme Procedure} bitvector? obj
1384 @deffnx {C Function} scm_bitvector_p (obj)
1385 Return @code{#t} when @var{obj} is a bitvector, else
1389 @deftypefn {C Function} int scm_is_bitvector (SCM obj)
1390 Return @code{1} when @var{obj} is a bitvector, else return @code{0}.
1393 @deffn {Scheme Procedure} make-bitvector len [fill]
1394 @deffnx {C Function} scm_make_bitvector (len, fill)
1395 Create a new bitvector of length @var{len} and
1396 optionally initialize all elements to @var{fill}.
1399 @deftypefn {C Function} SCM scm_c_make_bitvector (size_t len, SCM fill)
1400 Like @code{scm_make_bitvector}, but the length is given as a
1404 @deffn {Scheme Procedure} bitvector . bits
1405 @deffnx {C Function} scm_bitvector (bits)
1406 Create a new bitvector with the arguments as elements.
1409 @deffn {Scheme Procedure} bitvector-length vec
1410 @deffnx {C Function} scm_bitvector_length (vec)
1411 Return the length of the bitvector @var{vec}.
1414 @deftypefn {C Function} size_t scm_c_bitvector_length (SCM vec)
1415 Like @code{scm_bitvector_length}, but the length is returned as a
1419 @deffn {Scheme Procedure} bitvector-ref vec idx
1420 @deffnx {C Function} scm_bitvector_ref (vec, idx)
1421 Return the element at index @var{idx} of the bitvector
1425 @deftypefn {C Function} SCM scm_c_bitvector_ref (SCM obj, size_t idx)
1426 Return the element at index @var{idx} of the bitvector
1430 @deffn {Scheme Procedure} bitvector-set! vec idx val
1431 @deffnx {C Function} scm_bitvector_set_x (vec, idx, val)
1432 Set the element at index @var{idx} of the bitvector
1433 @var{vec} when @var{val} is true, else clear it.
1436 @deftypefn {C Function} SCM scm_c_bitvector_set_x (SCM obj, size_t idx, SCM val)
1437 Set the element at index @var{idx} of the bitvector
1438 @var{vec} when @var{val} is true, else clear it.
1441 @deffn {Scheme Procedure} bitvector-fill! vec val
1442 @deffnx {C Function} scm_bitvector_fill_x (vec, val)
1443 Set all elements of the bitvector
1444 @var{vec} when @var{val} is true, else clear them.
1447 @deffn {Scheme Procedure} list->bitvector list
1448 @deffnx {C Function} scm_list_to_bitvector (list)
1449 Return a new bitvector initialized with the elements
1453 @deffn {Scheme Procedure} bitvector->list vec
1454 @deffnx {C Function} scm_bitvector_to_list (vec)
1455 Return a new list initialized with the elements
1456 of the bitvector @var{vec}.
1459 @deftypefn {C Function} {const scm_t_uint32 *} scm_bitvector_elements (SCM vec)
1460 Return a pointer to the memory that holds the elements of @var{vec}
1461 for reading. Each word pointed to by this pointer has exactly 32
1462 bits, the least significant bit having the lowest index.
1464 There are @code{(scm_c_bitvector_length(@var{vec})+31)/32} words in the
1465 returned memory block. The last word might be only partially used when
1466 the bitvector length is not a multiple of 32. The unused bits must be
1467 ignored during reading.
1469 For each call to this function, you must call
1470 @code{scm_bitvector_release_elements} and after that call the pointer
1471 to the elements becomes invalid.
1474 @deftypefn {C Function} void scm_bitvector_release_elements (SCM vec)
1475 Finish the access to the elements of a bitvector, as exlained above.
1478 @deftypefn {C Function} void scm_frame_bitvector_release_elements (SCM vec)
1479 Arrange for @code{scm_bitvector_release_elements} to be called with @var{vec}
1480 when the current frame is unwound, implicitely or explicitely;
1484 @deftypefn {C Function} scm_t_uint32 *scm_bitvector_writable_elements (SCM vec)
1485 Return a pointer to the memory that holds the elements of @var{vec}
1486 for writing. Each word pointed to by this pointer has exactly 32
1487 bits, the least significant bit having the lowest index.
1489 There are @code{(scm_c_bitvector_length(@var{vec})+31)/32} words in
1490 the returned memory block. The last word might be only partially used
1491 when the bitvector length is not a multiple of 32. The unused bits
1492 can be overwritten freely since they must be ignored during reading.
1494 For each call to this function, you must call
1495 @code{scm_bitvector_release_writable_elements} and after that call the
1496 pointer to the elements becomes invalid.
1499 @deftypefn {C Function} void scm_bitvector_release_writable_elements (SCM vec)
1500 Finish the access to the elements of a bitvector, as exlained above.
1503 @deftypefn {C Function} void scm_frame_bitvector_release_writable_elements (SCM vec)
1504 Arrange for @code{scm_bitvector_release_writable_elements} to be
1505 called with @var{vec} when the current frame is unwound, implicitely
1506 or explicitely; @xref{Frames}.
1509 @deffn {Scheme Procedure} bit-count bool bitvector
1510 @deffnx {C Function} scm_bit_count (bool, bitvector)
1511 Return a count of how many entries in @var{bitvector} are equal to
1512 @var{bool}. For example,
1515 (bit-count #f #*000111000) @result{} 6
1519 @deffn {Scheme Procedure} bit-position bool bitvector start
1520 @deffnx {C Function} scm_bit_position (bool, bitvector, start)
1521 Return the index of the first occurrance of @var{bool} in
1522 @var{bitvector}, starting from @var{start}. If there is no @var{bool}
1523 entry between @var{start} and the end of @var{bitvector}, then return
1524 @code{#f}. For example,
1527 (bit-position #t #*000101 0) @result{} 3
1528 (bit-position #f #*0001111 3) @result{} #f
1532 @deffn {Scheme Procedure} bit-invert! bitvector
1533 @deffnx {C Function} scm_bit_invert_x (bitvector)
1534 Modify @var{bitvector} by replacing each element with its negation.
1537 @deffn {Scheme Procedure} bit-set*! bitvector uvec bool
1538 @deffnx {C Function} scm_bit_set_star_x (bitvector, uvec, bool)
1539 Set entries of @var{bitvector} to @var{bool}, with @var{uvec}
1540 selecting the entries to change. The return value is unspecified.
1542 If @var{uvec} is a bit vector, then those entries where it has
1543 @code{#t} are the ones in @var{bitvector} which are set to @var{bool}.
1544 @var{uvec} and @var{bitvector} must be the same length. When
1545 @var{bool} is @code{#t} it's like @var{uvec} is OR'ed into
1546 @var{bitvector}. Or when @var{bool} is @code{#f} it can be seen as an
1550 (define bv #*01000010)
1551 (bit-set*! bv #*10010001 #t)
1553 @result{} #*11010011
1556 If @var{uvec} is a uniform vector of unsigned long integers, then
1557 they're indexes into @var{bitvector} which are set to @var{bool}.
1560 (define bv #*01000010)
1561 (bit-set*! bv #u(5 2 7) #t)
1563 @result{} #*01100111
1567 @deffn {Scheme Procedure} bit-count* bitvector uvec bool
1568 @deffnx {C Function} scm_bit_count_star (bitvector, uvec, bool)
1569 Return a count of how many entries in @var{bitvector} are equal to
1570 @var{bool}, with @var{uvec} selecting the entries to consider.
1572 @var{uvec} is interpreted in the same way as for @code{bit-set*!}
1573 above. Namely, if @var{uvec} is a bit vector then entries which have
1574 @code{#t} there are considered in @var{bitvector}. Or if @var{uvec}
1575 is a uniform vector of unsigned long integers then it's the indexes in
1576 @var{bitvector} to consider.
1581 (bit-count* #*01110111 #*11001101 #t) @result{} 3
1582 (bit-count* #*01110111 #u(7 0 4) #f) @result{} 2
1587 @node Generalized Vectors
1588 @subsection Generalized Vectors
1590 Guile has a number of data types that are generally vector-like:
1591 strings, uniform numeric vectors, bitvectors, and of course ordinary
1592 vectors of arbitrary Scheme values. These types are disjoint: a
1593 Scheme value belongs to at most one of the four types listed above.
1595 If you want to gloss over this distinction and want to treat all four
1596 types with common code, you can use the procedures in this section.
1597 They work with the @emph{generalized vector} type, which is the union
1598 of the four vector-like types.
1600 Generalized vectors play an important role as the underlying storage
1601 for arrays, @xref{Arrays}.
1603 @deffn {Scheme Procedure} generalized-vector? obj
1604 @deffnx {C Function} scm_generalized_vector_p (obj)
1605 Return @code{#t} if @var{obj} is a vector, string,
1606 bitvector, or uniform numeric vector.
1609 @deffn {Scheme Procedure} generalized-vector-length v
1610 @deffnx {C Function} scm_generalized_vector_length (v)
1611 Return the length of the generalized vector @var{v}.
1614 @deffn {Scheme Procedure} generalized-vector-ref v idx
1615 @deffnx {C Function} scm_generalized_vector_ref (v, idx)
1616 Return the element at index @var{idx} of the
1617 generalized vector @var{v}.
1620 @deffn {Scheme Procedure} generalized-vector-set! v idx val
1621 @deffnx {C Function} scm_generalized_vector_set_x (v, idx, val)
1622 Set the element at index @var{idx} of the
1623 generalized vector @var{v} to @var{val}.
1626 @deffn {Scheme Procedure} generalized-vector->list v
1627 @deffnx {C Function} scm_generalized_vector_to_list (v)
1628 Return a new list whose elements are the elements of the
1629 generalized vector @var{v}.
1632 @deftypefn {C Function} int scm_is_generalized_vector (SCM obj)
1633 Return @code{1} if @var{obj} is a vector, string,
1634 bitvector, or uniform numeric vector; else return @code{0}.
1637 @deftypefn {C Function} size_t scm_c_generalized_vector_length (SCM v)
1638 Return the length of the generalized vector @var{v}.
1641 @deftypefn {C Function} SCM scm_c_generalized_vector_ref (SCM v, size_t idx)
1642 Return the element at index @var{idx} of the generalized vector @var{v}.
1645 @deftypefn {C Function} void scm_c_generalized_vector_set_x (SCM v, size_t idx, SCM val)
1646 Set the element at index @var{idx} of the generalized vector @var{v}
1654 @dfn{Arrays} are a collection of cells organized into an arbitrary
1655 number of dimensions. Each cell can be accessed in constant time by
1656 supplying an index for each dimension.
1658 In the current implementation, an array uses a generalized vector for
1659 the actual storage of its elements. Any kind of generalized vector
1660 will do, so you can have arrays of uniform numeric values, arrays of
1661 characters, arrays of bits, and of course, arrays of arbitrary Scheme
1662 values. For example, arrays with an underlying @code{c64vector} might
1663 be nice for digital signal processing, while arrays made from a
1664 @code{u8vector} might be used to hold gray-scale images.
1666 The number of dimensions of an array is called its @dfn{rank}. Thus,
1667 a matrix is an array of rank 2, while a vector has rank 1. When
1668 accessing an array element, you have to specify one exact integer for
1669 each dimension. These integers are called the @dfn{indices} of the
1670 element. An array specifies the allowed range of indices for each
1671 dimension via a inclusive lower and upper bound. These bounds can
1672 well be negative, but the upper bound must be grater than or equal to
1673 the lower bound. When all lower bounds of an array are zero, it is
1674 called a @dfn{zero-origin} array.
1676 For example, ordinary vectors can be regarded as one-dimensional,
1679 An array is displayed as @code{#} followed by its rank, followed by a
1680 tag that describes the underlying vector, optionally followed by the
1681 lower bounds, and finally followed by the cells, organized into
1682 dimensions using parentheses.
1684 In more words, the array tag is of the form
1687 #<rank><vectag><@@lower><@@lower>...
1690 where @code{<rank>} is a positive integer in decimal giving the rank of
1691 the array. It is omitted when the rank is 1 and the array is non-shared
1692 and has zero-origin (see below). For shared arrays and for a non-zero
1693 origin, the rank is always printed even when it is 1 to dinstinguish
1694 them from ordinary vectors.
1696 The @code{<vectag>} part is the tag for a uniform numeric vector, like
1697 @code{u8}, @code{s16}, etc, @code{b} for bitvectors, or @code{a} for
1698 strings. It is empty for ordinary vectors.
1700 The @code{<@@lower>} part is a @samp{@@} sign followed by an integer in
1701 decimal giving the lower bound of a dimension. There is one
1702 @code{<@@lower>} for each dimension. When all lower bounds are zero,
1703 all @code{<@@lower>} parts are omitted.
1709 is an ordinary array of rank 1 with lower bound 0 in dimension 0.
1710 (I.e., a regular vector.)
1713 is an ordinary array of rank 1 with lower bound 2 in dimension 0.
1715 @item #2((1 2 3) (4 5 6))
1716 is a non-uniform array of rank 2; a 3@cross{}3 matrix with index ranges 0..2
1720 is a uniform u8 array of rank 1.
1722 @item #2u32@@2@@3((1 2) (2 3))
1723 is a uniform u8 array of rank 2 with index ranges 2..3 and 3..4.
1728 When an array is created, the range of each dimension must be
1729 specified, e.g., to create a 2@cross{}3 array with a zero-based index:
1732 (make-array 'ho 2 3) @result{} #2((ho ho ho) (ho ho ho))
1735 The range of each dimension can also be given explicitly, e.g., another
1736 way to create the same array:
1739 (make-array 'ho '(0 1) '(0 2)) @result{} #2((ho ho ho) (ho ho ho))
1742 The following procedures can be used with arrays (or vectors). An
1743 argument shown as @var{idx}@dots{} means one parameter for each
1744 dimension in the array. A @var{idxlist} argument means a list of such
1745 values, one for each dimension.
1748 @deffn {Scheme Procedure} array? obj
1749 @deffnx {C Function} scm_array_p (obj, unused)
1750 Return @code{#t} if the @var{obj} is an array, and @code{#f} if
1753 The second argument to scm_array_p is there for historical reasons,
1754 but it is not used. You should always pass @code{SCM_UNDEFINED} as
1758 @deffn {Scheme Procedure} typed-array? obj type
1759 @deffnx {C Function} scm_typed_array_p (obj, type)
1760 Return @code{#t} if the @var{obj} is an array of type @var{type}, and
1764 @deftypefn {C Function} int scm_is_array (SCM obj)
1765 Return @code{1} if the @var{obj} is an array and @code{0} if not.
1768 @deftypefn {C Function} int scm_is_typed_array (SCM obj, SCM type)
1769 Return @code{0} if the @var{obj} is an array of type @var{type}, and
1773 @deffn {Scheme Procedure} make-array fill bound @dots{}
1774 @deffnx {C Function} scm_make_array (fill, bounds)
1775 Equivalent to @code{(make-typed-array #t @var{fill} @var{bound} ...)}.
1778 @deffn {Scheme Procedure} make-typed-array type fill bound @dots{}
1779 @deffnx {C Function} scm_make_typed_array (type, fill, bounds)
1780 Create and return an array that has as many dimensions as there are
1781 @var{bound}s and (maybe) fill it with @var{fill}.
1783 The underlaying storage vector is created according to @var{type},
1784 which must be a symbol whose name is the `vectag' of the array as
1785 explained above, or @code{#t} for ordinary, non-specialized arrays.
1787 For example, using the symbol @code{f64} for @var{type} will create an
1788 array that uses a @code{f64vector} for storing its elements, and
1789 @code{a} will use a string.
1791 Ordinary arrays (signified by a @var{type} of @code{#t}) are filled
1792 with @var{fill}. Other types of arrays are only then filled with
1793 @var{fill} when @var{fill} is non-@nicode{#f}.
1795 Each @var{bound} may be a positive non-zero integer @var{N}, in which
1796 case the index for that dimension can range from 0 through @var{N-1}; or
1797 an explicit index range specifier in the form @code{(LOWER UPPER)},
1798 where both @var{lower} and @var{upper} are integers, possibly less than
1799 zero, and possibly the same number (however, @var{lower} cannot be
1800 greater than @var{upper}).
1803 @deffn {Scheme Procedure} list->array dimspec list
1804 Equivalent to @code{(list->typed-array #t @var{dimspec}
1808 @deffn {Scheme Procedure} list->typed-array type dimspec list
1809 @deffnx {C Function} scm_list_to_typed_array (type, dimspec, list)
1810 Return an array of the type indicated by @var{type} with elements the
1811 same as those of @var{list}.
1813 The argument @var{dimspec} determines the number of dimensions of the
1814 array and their lower bounds. When @var{dimspec} is an exact integer,
1815 it gives the number of dimensions directly and all lower bounds are
1816 zero. When it is a list of exact integers, then each element is the
1817 lower index bound of a dimension, and there will be as many dimensions
1818 as elements in the list.
1821 @deffn {Scheme Procedure} array-type array
1822 Return the type of @var{array}. This is the `vectag' used for
1823 printing @var{array} (or @code{#t} for ordinary arrays) and can be
1824 used with @code{make-typed-array} to create an array of the same kind
1828 @deffn {Scheme Procedure} array-ref array idx @dots{}
1829 Return the element at @code{(idx @dots{})} in @var{array}.
1832 (define a (make-array 999 '(1 2) '(3 4)))
1833 (array-ref a 2 4) @result{} 999
1837 @deffn {Scheme Procedure} array-in-bounds? array idx @dots{}
1838 @deffnx {C Function} scm_array_in_bounds_p (array, idxlist)
1839 Return @code{#t} if the given index would be acceptable to
1843 (define a (make-array #f '(1 2) '(3 4)))
1844 (array-in-bounds? a 2 3) @result{} #f
1845 (array-in-bounds? a 0 0) @result{} #f
1849 @deffn {Scheme Procedure} array-set! array obj idx @dots{}
1850 @deffnx {C Function} scm_array_set_x (array, obj, idxlist)
1851 Set the element at @code{(idx @dots{})} in @var{array} to @var{obj}.
1852 The return value is unspecified.
1855 (define a (make-array #f '(0 1) '(0 1)))
1856 (array-set! a #t 1 1)
1857 a @result{} #2((#f #f) (#f #t))
1861 @deffn {Scheme Procedure} make-shared-array oldarray mapfunc bound @dots{}
1862 @deffnx {C Function} scm_make_shared_array (oldarray, mapfunc, boundlist)
1863 @code{make-shared-array} can be used to create shared subarrays of other
1864 arrays. The @var{mapper} is a function that translates coordinates in
1865 the new array into coordinates in the old array. A @var{mapper} must be
1866 affine, and its range must stay within the bounds of the old array, but
1867 it can be otherwise arbitrary. A simple example:
1870 (define fred (make-array #f 8 8))
1871 (define freds-diagonal
1872 (make-shared-array fred (lambda (i) (list i i)) 8))
1873 (array-set! freds-diagonal 'foo 3)
1874 (array-ref fred 3 3) @result{} foo
1875 (define freds-center
1876 (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
1877 (array-ref freds-center 0 0) @result{} foo
1881 @deffn {Scheme Procedure} shared-array-increments array
1882 @deffnx {C Function} scm_shared_array_increments (array)
1883 For each dimension, return the distance between elements in the root vector.
1886 @deffn {Scheme Procedure} shared-array-offset array
1887 @deffnx {C Function} scm_shared_array_offset (array)
1888 Return the root vector index of the first element in the array.
1891 @deffn {Scheme Procedure} shared-array-root array
1892 @deffnx {C Function} scm_shared_array_root (array)
1893 Return the root vector of a shared array.
1896 @deffn {Scheme Procedure} transpose-array array dim1 @dots{}
1897 @deffnx {C Function} scm_transpose_array (array, dimlist)
1898 Return an array sharing contents with @var{array}, but with
1899 dimensions arranged in a different order. There must be one
1900 @var{dim} argument for each dimension of @var{array}.
1901 @var{dim1}, @var{dim2}, @dots{} should be integers between 0
1902 and the rank of the array to be returned. Each integer in that
1903 range must appear at least once in the argument list.
1905 The values of @var{dim1}, @var{dim2}, @dots{} correspond to
1906 dimensions in the array to be returned, and their positions in the
1907 argument list to dimensions of @var{array}. Several @var{dim}s
1908 may have the same value, in which case the returned array will
1909 have smaller rank than @var{array}.
1912 (transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
1913 (transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
1914 (transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
1915 #2((a 4) (b 5) (c 6))
1919 @deffn {Scheme Procedure} enclose-array array dim1 @dots{}
1920 @deffnx {C Function} scm_enclose_array (array, dimlist)
1921 @var{dim1}, @var{dim2} @dots{} should be nonnegative integers less than
1922 the rank of @var{array}. @code{enclose-array} returns an array
1923 resembling an array of shared arrays. The dimensions of each shared
1924 array are the same as the @var{dim}th dimensions of the original array,
1925 the dimensions of the outer array are the same as those of the original
1926 array that did not match a @var{dim}.
1928 An enclosed array is not a general Scheme array. Its elements may not
1929 be set using @code{array-set!}. Two references to the same element of
1930 an enclosed array will be @code{equal?} but will not in general be
1931 @code{eq?}. The value returned by @code{array-prototype} when given an
1932 enclosed array is unspecified.
1937 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1)
1939 #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
1941 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0)
1943 #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
1947 @deffn {Scheme Procedure} array-shape array
1948 @deffnx {Scheme Procedure} array-dimensions array
1949 @deffnx {C Function} scm_array_dimensions (array)
1950 Return a list of the bounds for each dimenson of @var{array}.
1952 @code{array-shape} gives @code{(@var{lower} @var{upper})} for each
1953 dimension. @code{array-dimensions} instead returns just
1954 @math{@var{upper}+1} for dimensions with a 0 lower bound. Both are
1955 suitable as input to @code{make-array}.
1960 (define a (make-array 'foo '(-1 3) 5))
1961 (array-shape a) @result{} ((-1 3) (0 4))
1962 (array-dimensions a) @result{} ((-1 3) 5)
1966 @deffn {Scheme Procedure} array-rank obj
1967 @deffnx {C Function} scm_array_rank (obj)
1968 Return the number of dimensions of an array @var{obj}, or if @var{obj}
1969 is not an array then return 0.
1972 @deffn {Scheme Procedure} array->list array
1973 @deffnx {C Function} scm_array_to_list (array)
1974 Return a list consisting of all the elements, in order, of
1978 @c FIXME: Describe how the order affects the copying (it matters for
1979 @c shared arrays with the same underlying root vector, presumably).
1981 @deffn {Scheme Procedure} array-copy! src dst
1982 @deffnx {Scheme Procedure} array-copy-in-order! src dst
1983 @deffnx {C Function} scm_array_copy_x (src, dst)
1984 Copy every element from vector or array @var{src} to the corresponding
1985 element of @var{dst}. @var{dst} must have the same rank as @var{src},
1986 and be at least as large in each dimension. The return value is
1990 @deffn {Scheme Procedure} array-fill! array fill
1991 @deffnx {C Function} scm_array_fill_x (array, fill)
1992 Store @var{fill} in every element of @var{array}. The value returned
1996 @c begin (texi-doc-string "guile" "array-equal?")
1997 @deffn {Scheme Procedure} array-equal? array1 array2 @dots{}
1998 Return @code{#t} if all arguments are arrays with the same shape, the
1999 same type, and have corresponding elements which are either
2000 @code{equal?} or @code{array-equal?}. This function differs from
2001 @code{equal?} in that a one dimensional shared array may be
2002 @var{array-equal?} but not @var{equal?} to a vector or uniform vector.
2005 @deffn {Scheme Procedure} array-contents array [strict]
2006 @deffnx {C Function} scm_array_contents (array, strict)
2007 If @var{array} may be @dfn{unrolled} into a one dimensional shared array
2008 without changing their order (last subscript changing fastest), then
2009 @code{array-contents} returns that shared array, otherwise it returns
2010 @code{#f}. All arrays made by @code{make-array} and
2011 @code{make-generalized-array} may be unrolled, some arrays made by
2012 @code{make-shared-array} may not be.
2014 If the optional argument @var{strict} is provided, a shared array will
2015 be returned only if its elements are stored internally contiguous in
2019 @c FIXME: array-map! accepts no source arrays at all, and in that
2020 @c case makes calls "(proc)". Is that meant to be a documented
2023 @c FIXME: array-for-each doesn't say what happens if the sources have
2024 @c different index ranges. The code currently iterates over the
2025 @c indices of the first and expects the others to cover those. That
2026 @c at least vaguely matches array-map!, but is is meant to be a
2027 @c documented feature?
2029 @deffn {Scheme Procedure} array-map! dst proc src1 @dots{} srcN
2030 @deffnx {Scheme Procedure} array-map-in-order! dst proc src1 @dots{} srcN
2031 @deffnx {C Function} scm_array_map_x (dst, proc, srclist)
2032 Set each element of the @var{dst} array to values obtained from calls
2033 to @var{proc}. The value returned is unspecified.
2035 Each call is @code{(@var{proc} @var{elem1} @dots{} @var{elemN})},
2036 where each @var{elem} is from the corresponding @var{src} array, at
2037 the @var{dst} index. @code{array-map-in-order!} makes the calls in
2038 row-major order, @code{array-map!} makes them in an unspecified order.
2040 The @var{src} arrays must have the same number of dimensions as
2041 @var{dst}, and must have a range for each dimension which covers the
2042 range in @var{dst}. This ensures all @var{dst} indices are valid in
2046 @deffn {Scheme Procedure} array-for-each proc src1 @dots{} srcN
2047 @deffnx {C Function} scm_array_for_each (proc, src1, srclist)
2048 Apply @var{proc} to each tuple of elements of @var{src1} @dots{}
2049 @var{srcN}, in row-major order. The value returned is unspecified.
2052 @deffn {Scheme Procedure} array-index-map! dst proc
2053 @deffnx {C Function} scm_array_index_map_x (dst, proc)
2054 Set each element of the @var{dst} array to values returned by calls to
2055 @var{proc}. The value returned is unspecified.
2057 Each call is @code{(@var{proc} @var{i1} @dots{} @var{iN})}, where
2058 @var{i1}@dots{}@var{iN} is the destination index, one parameter for
2059 each dimension. The order in which the calls are made is unspecified.
2061 For example, to create a @m{4\times4, 4x4} matrix representing a
2065 \advance\leftskip by 2\lispnarrowing {
2083 (define a (make-array #f 4 4))
2084 (array-index-map! a (lambda (i j)
2085 (modulo (+ i j) 4)))
2089 @deffn {Scheme Procedure} uniform-array-read! ra [port_or_fd [start [end]]]
2090 @deffnx {C Function} scm_uniform_array_read_x (ra, port_or_fd, start, end)
2091 Attempt to read all elements of @var{ura}, in lexicographic order, as
2092 binary objects from @var{port-or-fdes}.
2093 If an end of file is encountered,
2094 the objects up to that point are put into @var{ura}
2095 (starting at the beginning) and the remainder of the array is
2098 The optional arguments @var{start} and @var{end} allow
2099 a specified region of a vector (or linearized array) to be read,
2100 leaving the remainder of the vector unchanged.
2102 @code{uniform-array-read!} returns the number of objects read.
2103 @var{port-or-fdes} may be omitted, in which case it defaults to the value
2104 returned by @code{(current-input-port)}.
2107 @deffn {Scheme Procedure} uniform-array-write v [port_or_fd [start [end]]]
2108 @deffnx {C Function} scm_uniform_array_write (v, port_or_fd, start, end)
2109 Writes all elements of @var{ura} as binary objects to
2112 The optional arguments @var{start}
2114 a specified region of a vector (or linearized array) to be written.
2116 The number of objects actually written is returned.
2117 @var{port-or-fdes} may be
2118 omitted, in which case it defaults to the value returned by
2119 @code{(current-output-port)}.
2125 A @dfn{record type} is a first class object representing a user-defined
2126 data type. A @dfn{record} is an instance of a record type.
2128 @deffn {Scheme Procedure} record? obj
2129 Return @code{#t} if @var{obj} is a record of any type and @code{#f}
2132 Note that @code{record?} may be true of any Scheme value; there is no
2133 promise that records are disjoint with other Scheme types.
2136 @deffn {Scheme Procedure} make-record-type type-name field-names
2137 Return a @dfn{record-type descriptor}, a value representing a new data
2138 type disjoint from all others. The @var{type-name} argument must be a
2139 string, but is only used for debugging purposes (such as the printed
2140 representation of a record of the new type). The @var{field-names}
2141 argument is a list of symbols naming the @dfn{fields} of a record of the
2142 new type. It is an error if the list contains any duplicates. It is
2143 unspecified how record-type descriptors are represented.
2146 @deffn {Scheme Procedure} record-constructor rtd [field-names]
2147 Return a procedure for constructing new members of the type represented
2148 by @var{rtd}. The returned procedure accepts exactly as many arguments
2149 as there are symbols in the given list, @var{field-names}; these are
2150 used, in order, as the initial values of those fields in a new record,
2151 which is returned by the constructor procedure. The values of any
2152 fields not named in that list are unspecified. The @var{field-names}
2153 argument defaults to the list of field names in the call to
2154 @code{make-record-type} that created the type represented by @var{rtd};
2155 if the @var{field-names} argument is provided, it is an error if it
2156 contains any duplicates or any symbols not in the default list.
2159 @deffn {Scheme Procedure} record-predicate rtd
2160 Return a procedure for testing membership in the type represented by
2161 @var{rtd}. The returned procedure accepts exactly one argument and
2162 returns a true value if the argument is a member of the indicated record
2163 type; it returns a false value otherwise.
2166 @deffn {Scheme Procedure} record-accessor rtd field-name
2167 Return a procedure for reading the value of a particular field of a
2168 member of the type represented by @var{rtd}. The returned procedure
2169 accepts exactly one argument which must be a record of the appropriate
2170 type; it returns the current value of the field named by the symbol
2171 @var{field-name} in that record. The symbol @var{field-name} must be a
2172 member of the list of field-names in the call to @code{make-record-type}
2173 that created the type represented by @var{rtd}.
2176 @deffn {Scheme Procedure} record-modifier rtd field-name
2177 Return a procedure for writing the value of a particular field of a
2178 member of the type represented by @var{rtd}. The returned procedure
2179 accepts exactly two arguments: first, a record of the appropriate type,
2180 and second, an arbitrary Scheme value; it modifies the field named by
2181 the symbol @var{field-name} in that record to contain the given value.
2182 The returned value of the modifier procedure is unspecified. The symbol
2183 @var{field-name} must be a member of the list of field-names in the call
2184 to @code{make-record-type} that created the type represented by
2188 @deffn {Scheme Procedure} record-type-descriptor record
2189 Return a record-type descriptor representing the type of the given
2190 record. That is, for example, if the returned descriptor were passed to
2191 @code{record-predicate}, the resulting predicate would return a true
2192 value when passed the given record. Note that it is not necessarily the
2193 case that the returned descriptor is the one that was passed to
2194 @code{record-constructor} in the call that created the constructor
2195 procedure that created the given record.
2198 @deffn {Scheme Procedure} record-type-name rtd
2199 Return the type-name associated with the type represented by rtd. The
2200 returned value is @code{eqv?} to the @var{type-name} argument given in
2201 the call to @code{make-record-type} that created the type represented by
2205 @deffn {Scheme Procedure} record-type-fields rtd
2206 Return a list of the symbols naming the fields in members of the type
2207 represented by @var{rtd}. The returned value is @code{equal?} to the
2208 field-names argument given in the call to @code{make-record-type} that
2209 created the type represented by @var{rtd}.
2214 @subsection Structures
2217 [FIXME: this is pasted in from Tom Lord's original guile.texi and should
2220 A @dfn{structure type} is a first class user-defined data type. A
2221 @dfn{structure} is an instance of a structure type. A structure type is
2224 Structures are less abstract and more general than traditional records.
2225 In fact, in Guile Scheme, records are implemented using structures.
2228 * Structure Concepts:: The structure of Structures
2229 * Structure Layout:: Defining the layout of structure types
2230 * Structure Basics:: make-, -ref and -set! procedures for structs
2231 * Vtables:: Accessing type-specific data
2234 @node Structure Concepts
2235 @subsubsection Structure Concepts
2237 A structure object consists of a handle, structure data, and a vtable.
2238 The handle is a Scheme value which points to both the vtable and the
2239 structure's data. Structure data is a dynamically allocated region of
2240 memory, private to the structure, divided up into typed fields. A
2241 vtable is another structure used to hold type-specific data. Multiple
2242 structures can share a common vtable.
2244 Three concepts are key to understanding structures.
2247 @item @dfn{layout specifications}
2249 Layout specifications determine how memory allocated to structures is
2250 divided up into fields. Programmers must write a layout specification
2251 whenever a new type of structure is defined.
2253 @item @dfn{structural accessors}
2255 Structure access is by field number. There is only one set of
2256 accessors common to all structure objects.
2260 Vtables, themselves structures, are first class representations of
2261 disjoint sub-types of structures in general. In most cases, when a
2262 new structure is created, programmers must specify a vtable for the
2263 new structure. Each vtable has a field describing the layout of its
2264 instances. Vtables can have additional, user-defined fields as well.
2269 @node Structure Layout
2270 @subsubsection Structure Layout
2272 When a structure is created, a region of memory is allocated to hold its
2273 state. The @dfn{layout} of the structure's type determines how that
2274 memory is divided into fields.
2276 Each field has a specified type. There are only three types allowed, each
2277 corresponding to a one letter code. The allowed types are:
2280 @item 'u' -- unprotected
2282 The field holds binary data that is not GC protected.
2284 @item 'p' -- protected
2286 The field holds a Scheme value and is GC protected.
2290 The field holds a Scheme value and is GC protected. When a structure is
2291 created with this type of field, the field is initialized to refer to
2292 the structure's own handle. This kind of field is mainly useful when
2293 mixing Scheme and C code in which the C code may need to compute a
2294 structure's handle given only the address of its malloc'd data.
2298 Each field also has an associated access protection. There are only
2299 three kinds of protection, each corresponding to a one letter code.
2300 The allowed protections are:
2303 @item 'w' -- writable
2305 The field can be read and written.
2307 @item 'r' -- readable
2309 The field can be read, but not written.
2313 The field can be neither read nor written. This kind
2314 of protection is for fields useful only to built-in routines.
2317 A layout specification is described by stringing together pairs
2318 of letters: one to specify a field type and one to specify a field
2319 protection. For example, a traditional cons pair type object could
2323 ; cons pairs have two writable fields of Scheme data
2327 A pair object in which the first field is held constant could be:
2333 Binary fields, (fields of type "u"), hold one @dfn{word} each. The
2334 size of a word is a machine dependent value defined to be equal to the
2335 value of the C expression: @code{sizeof (long)}.
2337 The last field of a structure layout may specify a tail array.
2338 A tail array is indicated by capitalizing the field's protection
2339 code ('W', 'R' or 'O'). A tail-array field is replaced by
2340 a read-only binary data field containing an array size. The array
2341 size is determined at the time the structure is created. It is followed
2342 by a corresponding number of fields of the type specified for the
2343 tail array. For example, a conventional Scheme vector can be
2347 ; A vector is an arbitrary number of writable fields holding Scheme
2352 In the above example, field 0 contains the size of the vector and
2353 fields beginning at 1 contain the vector elements.
2355 A kind of tagged vector (a constant tag followed by conventional
2356 vector elements) might be:
2363 Structure layouts are represented by specially interned symbols whose
2364 name is a string of type and protection codes. To create a new
2365 structure layout, use this procedure:
2367 @deffn {Scheme Procedure} make-struct-layout fields
2368 @deffnx {C Function} scm_make_struct_layout (fields)
2369 Return a new structure layout object.
2371 @var{fields} must be a string made up of pairs of characters
2372 strung together. The first character of each pair describes a field
2373 type, the second a field protection. Allowed types are 'p' for
2374 GC-protected Scheme data, 'u' for unprotected binary data, and 's' for
2375 a field that points to the structure itself. Allowed protections
2376 are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque
2377 fields. The last field protection specification may be capitalized to
2378 indicate that the field is a tail-array.
2383 @node Structure Basics
2384 @subsubsection Structure Basics
2386 This section describes the basic procedures for creating and accessing
2389 @deffn {Scheme Procedure} make-struct vtable tail_array_size . init
2390 @deffnx {C Function} scm_make_struct (vtable, tail_array_size, init)
2391 Create a new structure.
2393 @var{type} must be a vtable structure (@pxref{Vtables}).
2395 @var{tail-elts} must be a non-negative integer. If the layout
2396 specification indicated by @var{type} includes a tail-array,
2397 this is the number of elements allocated to that array.
2399 The @var{init1}, @dots{} are optional arguments describing how
2400 successive fields of the structure should be initialized. Only fields
2401 with protection 'r' or 'w' can be initialized, except for fields of
2402 type 's', which are automatically initialized to point to the new
2403 structure itself; fields with protection 'o' can not be initialized by
2406 If fewer optional arguments than initializable fields are supplied,
2407 fields of type 'p' get default value #f while fields of type 'u' are
2410 Structs are currently the basic representation for record-like data
2411 structures in Guile. The plan is to eventually replace them with a
2412 new representation which will at the same time be easier to use and
2415 For more information, see the documentation for @code{make-vtable-vtable}.
2418 @deffn {Scheme Procedure} struct? x
2419 @deffnx {C Function} scm_struct_p (x)
2420 Return @code{#t} iff @var{x} is a structure object, else
2425 @deffn {Scheme Procedure} struct-ref handle pos
2426 @deffnx {Scheme Procedure} struct-set! struct n value
2427 @deffnx {C Function} scm_struct_ref (handle, pos)
2428 @deffnx {C Function} scm_struct_set_x (struct, n, value)
2429 Access (or modify) the @var{n}th field of @var{struct}.
2431 If the field is of type 'p', then it can be set to an arbitrary value.
2433 If the field is of type 'u', then it can only be set to a non-negative
2434 integer value small enough to fit in one machine word.
2440 @subsubsection Vtables
2442 Vtables are structures that are used to represent structure types. Each
2443 vtable contains a layout specification in field
2444 @code{vtable-index-layout} -- instances of the type are laid out
2445 according to that specification. Vtables contain additional fields
2446 which are used only internally to libguile. The variable
2447 @code{vtable-offset-user} is bound to a field number. Vtable fields
2448 at that position or greater are user definable.
2450 @deffn {Scheme Procedure} struct-vtable handle
2451 @deffnx {C Function} scm_struct_vtable (handle)
2452 Return the vtable structure that describes the type of @var{struct}.
2455 @deffn {Scheme Procedure} struct-vtable? x
2456 @deffnx {C Function} scm_struct_vtable_p (x)
2457 Return @code{#t} iff @var{x} is a vtable structure.
2460 If you have a vtable structure, @code{V}, you can create an instance of
2461 the type it describes by using @code{(make-struct V ...)}. But where
2462 does @code{V} itself come from? One possibility is that @code{V} is an
2463 instance of a user-defined vtable type, @code{V'}, so that @code{V} is
2464 created by using @code{(make-struct V' ...)}. Another possibility is
2465 that @code{V} is an instance of the type it itself describes. Vtable
2466 structures of the second sort are created by this procedure:
2468 @deffn {Scheme Procedure} make-vtable-vtable user_fields tail_array_size . init
2469 @deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_array_size, init)
2470 Return a new, self-describing vtable structure.
2472 @var{user-fields} is a string describing user defined fields of the
2473 vtable beginning at index @code{vtable-offset-user}
2474 (see @code{make-struct-layout}).
2476 @var{tail-size} specifies the size of the tail-array (if any) of
2479 @var{init1}, @dots{} are the optional initializers for the fields of
2482 Vtables have one initializable system field---the struct printer.
2483 This field comes before the user fields in the initializers passed
2484 to @code{make-vtable-vtable} and @code{make-struct}, and thus works as
2485 a third optional argument to @code{make-vtable-vtable} and a fourth to
2486 @code{make-struct} when creating vtables:
2488 If the value is a procedure, it will be called instead of the standard
2489 printer whenever a struct described by this vtable is printed.
2490 The procedure will be called with arguments STRUCT and PORT.
2492 The structure of a struct is described by a vtable, so the vtable is
2493 in essence the type of the struct. The vtable is itself a struct with
2494 a vtable. This could go on forever if it weren't for the
2495 vtable-vtables which are self-describing vtables, and thus terminate
2498 There are several potential ways of using structs, but the standard
2499 one is to use three kinds of structs, together building up a type
2500 sub-system: one vtable-vtable working as the root and one or several
2501 "types", each with a set of "instances". (The vtable-vtable should be
2502 compared to the class <class> which is the class of itself.)
2505 (define ball-root (make-vtable-vtable "pr" 0))
2507 (define (make-ball-type ball-color)
2508 (make-struct ball-root 0
2509 (make-struct-layout "pw")
2511 (format port "#<a ~A ball owned by ~A>"
2515 (define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
2516 (define (owner ball) (struct-ref ball 0))
2518 (define red (make-ball-type 'red))
2519 (define green (make-ball-type 'green))
2521 (define (make-ball type owner) (make-struct type 0 owner))
2523 (define ball (make-ball green 'Nisse))
2524 ball @result{} #<a green ball owned by Nisse>
2528 @deffn {Scheme Procedure} struct-vtable-name vtable
2529 @deffnx {C Function} scm_struct_vtable_name (vtable)
2530 Return the name of the vtable @var{vtable}.
2533 @deffn {Scheme Procedure} set-struct-vtable-name! vtable name
2534 @deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name)
2535 Set the name of the vtable @var{vtable} to @var{name}.
2538 @deffn {Scheme Procedure} struct-vtable-tag handle
2539 @deffnx {C Function} scm_struct_vtable_tag (handle)
2540 Return the vtable tag of the structure @var{handle}.
2544 @node Dictionary Types
2545 @subsection Dictionary Types
2547 A @dfn{dictionary} object is a data structure used to index
2548 information in a user-defined way. In standard Scheme, the main
2549 aggregate data types are lists and vectors. Lists are not really
2550 indexed at all, and vectors are indexed only by number
2551 (e.g. @code{(vector-ref foo 5)}). Often you will find it useful
2552 to index your data on some other type; for example, in a library
2553 catalog you might want to look up a book by the name of its
2554 author. Dictionaries are used to help you organize information in
2557 An @dfn{association list} (or @dfn{alist} for short) is a list of
2558 key-value pairs. Each pair represents a single quantity or
2559 object; the @code{car} of the pair is a key which is used to
2560 identify the object, and the @code{cdr} is the object's value.
2562 A @dfn{hash table} also permits you to index objects with
2563 arbitrary keys, but in a way that makes looking up any one object
2564 extremely fast. A well-designed hash system makes hash table
2565 lookups almost as fast as conventional array or vector references.
2567 Alists are popular among Lisp programmers because they use only
2568 the language's primitive operations (lists, @dfn{car}, @dfn{cdr}
2569 and the equality primitives). No changes to the language core are
2570 necessary. Therefore, with Scheme's built-in list manipulation
2571 facilities, it is very convenient to handle data stored in an
2572 association list. Also, alists are highly portable and can be
2573 easily implemented on even the most minimal Lisp systems.
2575 However, alists are inefficient, especially for storing large
2576 quantities of data. Because we want Guile to be useful for large
2577 software systems as well as small ones, Guile provides a rich set
2578 of tools for using either association lists or hash tables.
2580 @node Association Lists
2581 @subsection Association Lists
2582 @tpindex Association Lists
2585 @cindex Association List
2589 An association list is a conventional data structure that is often used
2590 to implement simple key-value databases. It consists of a list of
2591 entries in which each entry is a pair. The @dfn{key} of each entry is
2592 the @code{car} of the pair and the @dfn{value} of each entry is the
2596 ASSOCIATION LIST ::= '( (KEY1 . VALUE1)
2604 Association lists are also known, for short, as @dfn{alists}.
2606 The structure of an association list is just one example of the infinite
2607 number of possible structures that can be built using pairs and lists.
2608 As such, the keys and values in an association list can be manipulated
2609 using the general list structure procedures @code{cons}, @code{car},
2610 @code{cdr}, @code{set-car!}, @code{set-cdr!} and so on. However,
2611 because association lists are so useful, Guile also provides specific
2612 procedures for manipulating them.
2615 * Alist Key Equality::
2616 * Adding or Setting Alist Entries::
2617 * Retrieving Alist Entries::
2618 * Removing Alist Entries::
2619 * Sloppy Alist Functions::
2623 @node Alist Key Equality
2624 @subsubsection Alist Key Equality
2626 All of Guile's dedicated association list procedures, apart from
2627 @code{acons}, come in three flavours, depending on the level of equality
2628 that is required to decide whether an existing key in the association
2629 list is the same as the key that the procedure call uses to identify the
2634 Procedures with @dfn{assq} in their name use @code{eq?} to determine key
2638 Procedures with @dfn{assv} in their name use @code{eqv?} to determine
2642 Procedures with @dfn{assoc} in their name use @code{equal?} to
2643 determine key equality.
2646 @code{acons} is an exception because it is used to build association
2647 lists which do not require their entries' keys to be unique.
2649 @node Adding or Setting Alist Entries
2650 @subsubsection Adding or Setting Alist Entries
2652 @code{acons} adds a new entry to an association list and returns the
2653 combined association list. The combined alist is formed by consing the
2654 new entry onto the head of the alist specified in the @code{acons}
2655 procedure call. So the specified alist is not modified, but its
2656 contents become shared with the tail of the combined alist that
2657 @code{acons} returns.
2659 In the most common usage of @code{acons}, a variable holding the
2660 original association list is updated with the combined alist:
2663 (set! address-list (acons name address address-list))
2666 In such cases, it doesn't matter that the old and new values of
2667 @code{address-list} share some of their contents, since the old value is
2668 usually no longer independently accessible.
2670 Note that @code{acons} adds the specified new entry regardless of
2671 whether the alist may already contain entries with keys that are, in
2672 some sense, the same as that of the new entry. Thus @code{acons} is
2673 ideal for building alists where there is no concept of key uniqueness.
2676 (set! task-list (acons 3 "pay gas bill" '()))
2679 ((3 . "pay gas bill"))
2681 (set! task-list (acons 3 "tidy bedroom" task-list))
2684 ((3 . "tidy bedroom") (3 . "pay gas bill"))
2687 @code{assq-set!}, @code{assv-set!} and @code{assoc-set!} are used to add
2688 or replace an entry in an association list where there @emph{is} a
2689 concept of key uniqueness. If the specified association list already
2690 contains an entry whose key is the same as that specified in the
2691 procedure call, the existing entry is replaced by the new one.
2692 Otherwise, the new entry is consed onto the head of the old association
2693 list to create the combined alist. In all cases, these procedures
2694 return the combined alist.
2696 @code{assq-set!} and friends @emph{may} destructively modify the
2697 structure of the old association list in such a way that an existing
2698 variable is correctly updated without having to @code{set!} it to the
2704 (("mary" . "34 Elm Road") ("james" . "16 Bow Street"))
2706 (assoc-set! address-list "james" "1a London Road")
2708 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
2712 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
2718 (assoc-set! address-list "bob" "11 Newington Avenue")
2720 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
2721 ("james" . "1a London Road"))
2725 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
2728 The only safe way to update an association list variable when adding or
2729 replacing an entry like this is to @code{set!} the variable to the
2734 (assoc-set! address-list "bob" "11 Newington Avenue"))
2737 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
2738 ("james" . "1a London Road"))
2741 Because of this slight inconvenience, you may find it more convenient to
2742 use hash tables to store dictionary data. If your application will not
2743 be modifying the contents of an alist very often, this may not make much
2746 If you need to keep the old value of an association list in a form
2747 independent from the list that results from modification by
2748 @code{acons}, @code{assq-set!}, @code{assv-set!} or @code{assoc-set!},
2749 use @code{list-copy} to copy the old association list before modifying
2752 @deffn {Scheme Procedure} acons key value alist
2753 @deffnx {C Function} scm_acons (key, value, alist)
2754 Add a new key-value pair to @var{alist}. A new pair is
2755 created whose car is @var{key} and whose cdr is @var{value}, and the
2756 pair is consed onto @var{alist}, and the new list is returned. This
2757 function is @emph{not} destructive; @var{alist} is not modified.
2760 @deffn {Scheme Procedure} assq-set! alist key val
2761 @deffnx {Scheme Procedure} assv-set! alist key value
2762 @deffnx {Scheme Procedure} assoc-set! alist key value
2763 @deffnx {C Function} scm_assq_set_x (alist, key, val)
2764 @deffnx {C Function} scm_assv_set_x (alist, key, val)
2765 @deffnx {C Function} scm_assoc_set_x (alist, key, val)
2766 Reassociate @var{key} in @var{alist} with @var{value}: find any existing
2767 @var{alist} entry for @var{key} and associate it with the new
2768 @var{value}. If @var{alist} does not contain an entry for @var{key},
2769 add a new one. Return the (possibly new) alist.
2771 These functions do not attempt to verify the structure of @var{alist},
2772 and so may cause unusual results if passed an object that is not an
2776 @node Retrieving Alist Entries
2777 @subsubsection Retrieving Alist Entries
2782 @code{assq}, @code{assv} and @code{assoc} take an alist and a key as
2783 arguments and return the entry for that key if an entry exists, or
2784 @code{#f} if there is no entry for that key. Note that, in the cases
2785 where an entry exists, these procedures return the complete entry, that
2786 is @code{(KEY . VALUE)}, not just the value.
2788 @deffn {Scheme Procedure} assq key alist
2789 @deffnx {Scheme Procedure} assv key alist
2790 @deffnx {Scheme Procedure} assoc key alist
2791 @deffnx {C Function} scm_assq (key, alist)
2792 @deffnx {C Function} scm_assv (key, alist)
2793 @deffnx {C Function} scm_assoc (key, alist)
2794 Fetch the entry in @var{alist} that is associated with @var{key}. To
2795 decide whether the argument @var{key} matches a particular entry in
2796 @var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}
2797 uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}
2798 cannot be found in @var{alist} (according to whichever equality
2799 predicate is in use), then return @code{#f}. These functions
2800 return the entire alist entry found (i.e. both the key and the value).
2803 @code{assq-ref}, @code{assv-ref} and @code{assoc-ref}, on the other
2804 hand, take an alist and a key and return @emph{just the value} for that
2805 key, if an entry exists. If there is no entry for the specified key,
2806 these procedures return @code{#f}.
2808 This creates an ambiguity: if the return value is @code{#f}, it means
2809 either that there is no entry with the specified key, or that there
2810 @emph{is} an entry for the specified key, with value @code{#f}.
2811 Consequently, @code{assq-ref} and friends should only be used where it
2812 is known that an entry exists, or where the ambiguity doesn't matter
2813 for some other reason.
2815 @deffn {Scheme Procedure} assq-ref alist key
2816 @deffnx {Scheme Procedure} assv-ref alist key
2817 @deffnx {Scheme Procedure} assoc-ref alist key
2818 @deffnx {C Function} scm_assq_ref (alist, key)
2819 @deffnx {C Function} scm_assv_ref (alist, key)
2820 @deffnx {C Function} scm_assoc_ref (alist, key)
2821 Like @code{assq}, @code{assv} and @code{assoc}, except that only the
2822 value associated with @var{key} in @var{alist} is returned. These
2823 functions are equivalent to
2826 (let ((ent (@var{associator} @var{key} @var{alist})))
2827 (and ent (cdr ent)))
2830 where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}.
2833 @node Removing Alist Entries
2834 @subsubsection Removing Alist Entries
2836 To remove the element from an association list whose key matches a
2837 specified key, use @code{assq-remove!}, @code{assv-remove!} or
2838 @code{assoc-remove!} (depending, as usual, on the level of equality
2839 required between the key that you specify and the keys in the
2842 As with @code{assq-set!} and friends, the specified alist may or may not
2843 be modified destructively, and the only safe way to update a variable
2844 containing the alist is to @code{set!} it to the value that
2845 @code{assq-remove!} and friends return.
2850 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
2851 ("james" . "1a London Road"))
2853 (set! address-list (assoc-remove! address-list "mary"))
2856 (("bob" . "11 Newington Avenue") ("james" . "1a London Road"))
2859 Note that, when @code{assq/v/oc-remove!} is used to modify an
2860 association list that has been constructed only using the corresponding
2861 @code{assq/v/oc-set!}, there can be at most one matching entry in the
2862 alist, so the question of multiple entries being removed in one go does
2863 not arise. If @code{assq/v/oc-remove!} is applied to an association
2864 list that has been constructed using @code{acons}, or an
2865 @code{assq/v/oc-set!} with a different level of equality, or any mixture
2866 of these, it removes only the first matching entry from the alist, even
2867 if the alist might contain further matching entries. For example:
2870 (define address-list '())
2871 (set! address-list (assq-set! address-list "mary" "11 Elm Street"))
2872 (set! address-list (assq-set! address-list "mary" "57 Pine Drive"))
2875 (("mary" . "57 Pine Drive") ("mary" . "11 Elm Street"))
2877 (set! address-list (assoc-remove! address-list "mary"))
2880 (("mary" . "11 Elm Street"))
2883 In this example, the two instances of the string "mary" are not the same
2884 when compared using @code{eq?}, so the two @code{assq-set!} calls add
2885 two distinct entries to @code{address-list}. When compared using
2886 @code{equal?}, both "mary"s in @code{address-list} are the same as the
2887 "mary" in the @code{assoc-remove!} call, but @code{assoc-remove!} stops
2888 after removing the first matching entry that it finds, and so one of the
2889 "mary" entries is left in place.
2891 @deffn {Scheme Procedure} assq-remove! alist key
2892 @deffnx {Scheme Procedure} assv-remove! alist key
2893 @deffnx {Scheme Procedure} assoc-remove! alist key
2894 @deffnx {C Function} scm_assq_remove_x (alist, key)
2895 @deffnx {C Function} scm_assv_remove_x (alist, key)
2896 @deffnx {C Function} scm_assoc_remove_x (alist, key)
2897 Delete the first entry in @var{alist} associated with @var{key}, and return
2898 the resulting alist.
2901 @node Sloppy Alist Functions
2902 @subsubsection Sloppy Alist Functions
2904 @code{sloppy-assq}, @code{sloppy-assv} and @code{sloppy-assoc} behave
2905 like the corresponding non-@code{sloppy-} procedures, except that they
2906 return @code{#f} when the specified association list is not well-formed,
2907 where the non-@code{sloppy-} versions would signal an error.
2909 Specifically, there are two conditions for which the non-@code{sloppy-}
2910 procedures signal an error, which the @code{sloppy-} procedures handle
2911 instead by returning @code{#f}. Firstly, if the specified alist as a
2912 whole is not a proper list:
2915 (assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
2917 ERROR: In procedure assoc in expression (assoc "mary" (quote #)):
2918 ERROR: Wrong type argument in position 2 (expecting association list): ((1 . 2) ("key" . "door") . "open sesame")
2920 (sloppy-assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
2926 Secondly, if one of the entries in the specified alist is not a pair:
2929 (assoc 2 '((1 . 1) 2 (3 . 9)))
2931 ERROR: In procedure assoc in expression (assoc 2 (quote #)):
2932 ERROR: Wrong type argument in position 2 (expecting association list): ((1 . 1) 2 (3 . 9))
2934 (sloppy-assoc 2 '((1 . 1) 2 (3 . 9)))
2939 Unless you are explicitly working with badly formed association lists,
2940 it is much safer to use the non-@code{sloppy-} procedures, because they
2941 help to highlight coding and data errors that the @code{sloppy-}
2942 versions would silently cover up.
2944 @deffn {Scheme Procedure} sloppy-assq key alist
2945 @deffnx {C Function} scm_sloppy_assq (key, alist)
2946 Behaves like @code{assq} but does not do any error checking.
2947 Recommended only for use in Guile internals.
2950 @deffn {Scheme Procedure} sloppy-assv key alist
2951 @deffnx {C Function} scm_sloppy_assv (key, alist)
2952 Behaves like @code{assv} but does not do any error checking.
2953 Recommended only for use in Guile internals.
2956 @deffn {Scheme Procedure} sloppy-assoc key alist
2957 @deffnx {C Function} scm_sloppy_assoc (key, alist)
2958 Behaves like @code{assoc} but does not do any error checking.
2959 Recommended only for use in Guile internals.
2963 @subsubsection Alist Example
2965 Here is a longer example of how alists may be used in practice.
2968 (define capitals '(("New York" . "Albany")
2969 ("Oregon" . "Salem")
2970 ("Florida" . "Miami")))
2972 ;; What's the capital of Oregon?
2973 (assoc "Oregon" capitals) @result{} ("Oregon" . "Salem")
2974 (assoc-ref capitals "Oregon") @result{} "Salem"
2976 ;; We left out South Dakota.
2978 (assoc-set! capitals "South Dakota" "Pierre"))
2980 @result{} (("South Dakota" . "Pierre")
2981 ("New York" . "Albany")
2982 ("Oregon" . "Salem")
2983 ("Florida" . "Miami"))
2985 ;; And we got Florida wrong.
2987 (assoc-set! capitals "Florida" "Tallahassee"))
2989 @result{} (("South Dakota" . "Pierre")
2990 ("New York" . "Albany")
2991 ("Oregon" . "Salem")
2992 ("Florida" . "Tallahassee"))
2994 ;; After Oregon secedes, we can remove it.
2996 (assoc-remove! capitals "Oregon"))
2998 @result{} (("South Dakota" . "Pierre")
2999 ("New York" . "Albany")
3000 ("Florida" . "Tallahassee"))
3004 @subsection Hash Tables
3005 @tpindex Hash Tables
3007 @c FIXME::martin: Review me!
3009 Hash tables are dictionaries which offer similar functionality as
3010 association lists: They provide a mapping from keys to values. The
3011 difference is that association lists need time linear in the size of
3012 elements when searching for entries, whereas hash tables can normally
3013 search in constant time. The drawback is that hash tables require a
3014 little bit more memory, and that you can not use the normal list
3015 procedures (@pxref{Lists}) for working with them.
3018 * Hash Table Examples:: Demonstration of hash table usage.
3019 * Hash Table Reference:: Hash table procedure descriptions.
3023 @node Hash Table Examples
3024 @subsubsection Hash Table Examples
3026 @c FIXME::martin: Review me!
3028 For demonstration purposes, this section gives a few usage examples of
3029 some hash table procedures, together with some explanation what they do.
3031 First we start by creating a new hash table with 31 slots, and
3032 populate it with two key/value pairs.
3035 (define h (make-hash-table 31))
3037 (hashq-create-handle! h 'foo "bar")
3041 (hashq-create-handle! h 'braz "zonk")
3045 (hashq-create-handle! h 'frob #f)
3050 You can get the value for a given key with the procedure
3051 @code{hashq-ref}, but the problem with this procedure is that you
3052 cannot reliably determine whether a key does exists in the table. The
3053 reason is that the procedure returns @code{#f} if the key is not in
3054 the table, but it will return the same value if the key is in the
3055 table and just happens to have the value @code{#f}, as you can see in
3056 the following examples.
3067 (hashq-ref h 'not-there)
3072 Better is to use the procedure @code{hashq-get-handle}, which makes a
3073 distinction between the two cases. Just like @code{assq}, this
3074 procedure returns a key/value-pair on success, and @code{#f} if the
3078 (hashq-get-handle h 'foo)
3082 (hashq-get-handle h 'not-there)
3087 There is no procedure for calculating the number of key/value-pairs in
3088 a hash table, but @code{hash-fold} can be used for doing exactly that.
3091 (hash-fold (lambda (key value seed) (+ 1 seed)) 0 h)
3096 @node Hash Table Reference
3097 @subsubsection Hash Table Reference
3099 @c FIXME: Describe in broad terms what happens for resizing, and what
3100 @c the initial size means for this.
3102 Like the association list functions, the hash table functions come in
3103 several varieties, according to the equality test used for the keys.
3104 Plain @code{hash-} functions use @code{equal?}, @code{hashq-}
3105 functions use @code{eq?}, @code{hashv-} functions use @code{eqv?}, and
3106 the @code{hashx-} functions use an application supplied test.
3108 A single @code{make-hash-table} creates a hash table suitable for use
3109 with any set of functions, but it's imperative that just one set is
3110 then used consistently, or results will be unpredictable.
3113 Hash tables are implemented as a vector indexed by a hash value formed
3114 from the key, with an association list of key/value pairs for each
3115 bucket in case distinct keys hash together. Direct access to the
3116 pairs in those lists is provided by the @code{-handle-} functions.
3118 When the number of table entries goes above a threshold the vector is
3119 increased and the entries rehashed, to prevent the bucket lists
3120 becoming too long and slowing down accesses. When the number of
3121 entries goes below a threshold the vector is decreased to save space.
3124 For the @code{hashx-} ``extended'' routines, an application supplies a
3125 @var{hash} function producing an integer index like @code{hashq} etc
3126 below, and an @var{assoc} alist search function like @code{assq} etc
3127 (@pxref{Retrieving Alist Entries}). Here's an example of such
3128 functions implementing case-insensitive hashing of string keys,
3131 (use-modules (srfi srfi-1)
3134 (define (my-hash str size)
3135 (remainder (string-hash-ci str) size))
3136 (define (my-assoc str alist)
3137 (find (lambda (pair) (string-ci=? str (car pair))) alist))
3139 (define my-table (make-hash-table))
3140 (hashx-set! my-hash my-assoc my-table "foo" 123)
3142 (hashx-ref my-hash my-assoc my-table "FOO")
3146 In a @code{hashx-} @var{hash} function the aim is to spread keys
3147 across the vector, so bucket lists don't become long. But the actual
3148 values are arbitrary as long as they're in the range 0 to
3149 @math{@var{size}-1}. Helpful functions for forming a hash value, in
3150 addition to @code{hashq} etc below, include @code{symbol-hash}
3151 (@pxref{Symbol Keys}), @code{string-hash} and @code{string-hash-ci}
3152 (@pxref{String Comparison}), and @code{char-set-hash}
3153 (@pxref{Character Set Predicates/Comparison}).
3155 Note that currently, unfortunately, there's no @code{hashx-remove!}
3156 function, which rather limits the usefulness of the @code{hashx-}
3160 @deffn {Scheme Procedure} make-hash-table [size]
3161 Create a new hash table, with an optional minimum vector @var{size}.
3163 When @var{size} is given, the table vector will still grow and shrink
3164 automatically, as described above, but with @var{size} as a minimum.
3165 If an application knows roughly how many entries the table will hold
3166 then it can use @var{size} to avoid rehashing when initial entries are
3170 @deffn {Scheme Procedure} hash-table? obj
3171 @deffnx {C Function} scm_hash_table_p (obj)
3172 Return @code{#t} if @var{obj} is a hash table.
3175 @deffn {Scheme Procedure} hash-clear! table
3176 @deffnx {C Function} scm_hash_clear_x (table)
3177 Remove all items from TABLE (without triggering a resize).
3180 @deffn {Scheme Procedure} hash-ref table key [dflt]
3181 @deffnx {Scheme Procedure} hashq-ref table key [dflt]
3182 @deffnx {Scheme Procedure} hashv-ref table key [dflt]
3183 @deffnx {Scheme Procedure} hashx-ref hash assoc table key [dflt]
3184 @deffnx {C Function} scm_hash_ref (table, key, dflt)
3185 @deffnx {C Function} scm_hashq_ref (table, key, dflt)
3186 @deffnx {C Function} scm_hashv_ref (table, key, dflt)
3187 @deffnx {C Function} scm_hashx_ref (hash, assoc, table, key, dflt)
3188 Lookup @var{key} in the given hash @var{table}, and return the
3189 associated value. If @var{key} is not found, return @var{dflt}, or
3190 @code{#f} if @var{dflt} is not given.
3193 @deffn {Scheme Procedure} hash-set! table key val
3194 @deffnx {Scheme Procedure} hashq-set! table key val
3195 @deffnx {Scheme Procedure} hashv-set! table key val
3196 @deffnx {Scheme Procedure} hashx-set! hash assoc table key val
3197 @deffnx {C Function} scm_hash_set_x (table, key, val)
3198 @deffnx {C Function} scm_hashq_set_x (table, key, val)
3199 @deffnx {C Function} scm_hashv_set_x (table, key, val)
3200 @deffnx {C Function} scm_hashx_set_x (hash, assoc, table, key, val)
3201 Associate @var{val} with @var{key} in the given hash @var{table}. If
3202 @var{key} is already present then it's associated value is changed.
3203 If it's not present then a new entry is created.
3206 @deffn {Scheme Procedure} hash-remove! table key
3207 @deffnx {Scheme Procedure} hashq-remove! table key
3208 @deffnx {Scheme Procedure} hashv-remove! table key
3209 @deffnx {C Function} scm_hash_remove_x (table, key)
3210 @deffnx {C Function} scm_hashq_remove_x (table, key)
3211 @deffnx {C Function} scm_hashv_remove_x (table, key)
3212 Remove any association for @var{key} in the given hash @var{table}.
3213 If @var{key} is not in @var{table} then nothing is done.
3216 @deffn {Scheme Procedure} hash key size
3217 @deffnx {Scheme Procedure} hashq key size
3218 @deffnx {Scheme Procedure} hashv key size
3219 @deffnx {C Function} scm_hash (key, size)
3220 @deffnx {C Function} scm_hashq (key, size)
3221 @deffnx {C Function} scm_hashv (key, size)
3222 Return a hash value for @var{key}. This is a number in the range
3223 @math{0} to @math{@var{size}-1}, which is suitable for use in a hash
3224 table of the given @var{size}.
3226 Note that @code{hashq} and @code{hashv} may use internal addresses of
3227 objects, so if an object is garbage collected and re-created it can
3228 have a different hash value, even when the two are notionally
3229 @code{eq?}. For instance with symbols,
3232 (hashq 'something 123) @result{} 19
3234 (hashq 'something 123) @result{} 62
3237 In normal use this is not a problem, since an object entered into a
3238 hash table won't be garbage collected until removed. It's only if
3239 hashing calculations are somehow separated from normal references that
3240 its lifetime needs to be considered.
3243 @deffn {Scheme Procedure} hash-get-handle table key
3244 @deffnx {Scheme Procedure} hashq-get-handle table key
3245 @deffnx {Scheme Procedure} hashv-get-handle table key
3246 @deffnx {Scheme Procedure} hashx-get-handle hash assoc table key
3247 @deffnx {C Function} scm_hash_get_handle (table, key)
3248 @deffnx {C Function} scm_hashq_get_handle (table, key)
3249 @deffnx {C Function} scm_hashv_get_handle (table, key)
3250 @deffnx {C Function} scm_hashx_get_handle (hash, assoc, table, key)
3251 Return the @code{(@var{key} . @var{value})} pair for @var{key} in the
3252 given hash @var{table}, or @code{#f} if @var{key} is not in
3256 @deffn {Scheme Procedure} hash-create-handle! table key init
3257 @deffnx {Scheme Procedure} hashq-create-handle! table key init
3258 @deffnx {Scheme Procedure} hashv-create-handle! table key init
3259 @deffnx {Scheme Procedure} hashx-create-handle! hash assoc table key init
3260 @deffnx {C Function} scm_hash_create_handle_x (table, key, init)
3261 @deffnx {C Function} scm_hashq_create_handle_x (table, key, init)
3262 @deffnx {C Function} scm_hashv_create_handle_x (table, key, init)
3263 @deffnx {C Function} scm_hashx_create_handle_x (hash, assoc, table, key, init)
3264 Return the @code{(@var{key} . @var{value})} pair for @var{key} in the
3265 given hash @var{table}. If @var{key} is not in @var{table} then
3266 create an entry for it with @var{init} as the value, and return that
3270 @deffn {Scheme Procedure} hash-map->list proc table
3271 @deffnx {Scheme Procedure} hash-for-each proc table
3272 @deffnx {C Function} scm_hash_map_to_list (proc, table)
3273 @deffnx {C Function} scm_hash_for_each (proc, table)
3274 Apply @var{proc} to the entries in the given hash @var{table}. Each
3275 call is @code{(@var{proc} @var{key} @var{value})}. @code{hash-map->list}
3276 returns a list of the results from these calls, @code{hash-for-each}
3277 discards the results and returns an unspecified value.
3279 Calls are made over the table entries in an unspecified order, and for
3280 @code{hash-map->list} the order of the values in the returned list is
3281 unspecified. Results will be unpredictable if @var{table} is modified
3284 For example the following returns a new alist comprising all the
3285 entries from @code{mytable}, in no particular order.
3288 (hash-map->list cons mytable)
3292 @deffn {Scheme Procedure} hash-for-each-handle proc table
3293 @deffnx {C Function} scm_hash_for_each_handle (proc, table)
3294 Apply @var{proc} to the entries in the given hash @var{table}. Each
3295 call is @code{(@var{proc} @var{handle})}, where @var{handle} is a
3296 @code{(@var{key} . @var{value})} pair. Return an unspecified value.
3298 @code{hash-for-each-handle} differs from @code{hash-for-each} only in
3299 the argument list of @var{proc}.
3302 @deffn {Scheme Procedure} hash-fold proc init table
3303 @deffnx {C Function} scm_hash_fold (proc, init, table)
3304 Accumulate a result by applying @var{proc} to the elements of the
3305 given hash @var{table}. Each call is @code{(@var{proc} @var{key}
3306 @var{value} @var{prior-result})}, where @var{key} and @var{value} are
3307 from the @var{table} and @var{prior-result} is the return from the
3308 previous @var{proc} call. For the first call, @var{prior-result} is
3309 the given @var{init} value.
3311 Calls are made over the table entries in an unspecified order.
3312 Results will be unpredictable if @var{table} is modified while
3313 @code{hash-fold} is running.
3315 For example, the following returns a count of how many keys in
3316 @code{mytable} are strings.
3319 (hash-fold (lambda (key value prior)
3320 (if (string? key) (1+ prior) prior))
3327 @c TeX-master: "guile.texi"