2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
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 @ref{Expression Syntax}. The correct way
67 to try these examples is as follows.
78 A new pair is made by calling the procedure @code{cons} with two
79 arguments. Then the argument values are stored into a newly allocated
80 pair, and the pair is returned. The name @code{cons} stands for
81 "construct". Use the procedure @code{pair?} to test whether a
82 given Scheme object is a pair or not.
85 @deffn {Scheme Procedure} cons x y
86 @deffnx {C Function} scm_cons (x, y)
87 Return a newly allocated pair whose car is @var{x} and whose
88 cdr is @var{y}. The pair is guaranteed to be different (in the
89 sense of @code{eq?}) from every previously existing object.
93 @deffn {Scheme Procedure} pair? x
94 @deffnx {C Function} scm_pair_p (x)
95 Return @code{#t} if @var{x} is a pair; otherwise return
99 @deftypefn {C Function} int scm_is_pair (SCM x)
100 Return 1 when @var{x} is a pair; otherwise return 0.
103 The two parts of a pair are traditionally called @dfn{car} and
104 @dfn{cdr}. They can be retrieved with procedures of the same name
105 (@code{car} and @code{cdr}), and can be modified with the procedures
106 @code{set-car!} and @code{set-cdr!}. Since a very common operation in
107 Scheme programs is to access the car of a car of a pair, or the car of
108 the cdr of a pair, etc., the procedures called @code{caar},
109 @code{cadr} and so on are also predefined.
113 @deffn {Scheme Procedure} car pair
114 @deffnx {Scheme Procedure} cdr pair
115 @deffnx {C Function} scm_car (pair)
116 @deffnx {C Function} scm_cdr (pair)
117 Return the car or the cdr of @var{pair}, respectively.
120 @deftypefn {C Macro} SCM SCM_CAR (SCM pair)
121 @deftypefnx {C Macro} SCM SCM_CDR (SCM pair)
122 These two macros are the fastest way to access the car or cdr of a
123 pair; they can be thought of as compiling into a single memory
126 These macros do no checking at all. The argument @var{pair} must be a
130 @deffn {Scheme Procedure} cddr pair
131 @deffnx {Scheme Procedure} cdar pair
132 @deffnx {Scheme Procedure} cadr pair
133 @deffnx {Scheme Procedure} caar pair
134 @deffnx {Scheme Procedure} cdddr pair
135 @deffnx {Scheme Procedure} cddar pair
136 @deffnx {Scheme Procedure} cdadr pair
137 @deffnx {Scheme Procedure} cdaar pair
138 @deffnx {Scheme Procedure} caddr pair
139 @deffnx {Scheme Procedure} cadar pair
140 @deffnx {Scheme Procedure} caadr pair
141 @deffnx {Scheme Procedure} caaar pair
142 @deffnx {Scheme Procedure} cddddr pair
143 @deffnx {Scheme Procedure} cdddar pair
144 @deffnx {Scheme Procedure} cddadr pair
145 @deffnx {Scheme Procedure} cddaar pair
146 @deffnx {Scheme Procedure} cdaddr pair
147 @deffnx {Scheme Procedure} cdadar pair
148 @deffnx {Scheme Procedure} cdaadr pair
149 @deffnx {Scheme Procedure} cdaaar pair
150 @deffnx {Scheme Procedure} cadddr pair
151 @deffnx {Scheme Procedure} caddar pair
152 @deffnx {Scheme Procedure} cadadr pair
153 @deffnx {Scheme Procedure} cadaar pair
154 @deffnx {Scheme Procedure} caaddr pair
155 @deffnx {Scheme Procedure} caadar pair
156 @deffnx {Scheme Procedure} caaadr pair
157 @deffnx {Scheme Procedure} caaaar pair
158 @deffnx {C Function} scm_cddr (pair)
159 @deffnx {C Function} scm_cdar (pair)
160 @deffnx {C Function} scm_cadr (pair)
161 @deffnx {C Function} scm_caar (pair)
162 @deffnx {C Function} scm_cdddr (pair)
163 @deffnx {C Function} scm_cddar (pair)
164 @deffnx {C Function} scm_cdadr (pair)
165 @deffnx {C Function} scm_cdaar (pair)
166 @deffnx {C Function} scm_caddr (pair)
167 @deffnx {C Function} scm_cadar (pair)
168 @deffnx {C Function} scm_caadr (pair)
169 @deffnx {C Function} scm_caaar (pair)
170 @deffnx {C Function} scm_cddddr (pair)
171 @deffnx {C Function} scm_cdddar (pair)
172 @deffnx {C Function} scm_cddadr (pair)
173 @deffnx {C Function} scm_cddaar (pair)
174 @deffnx {C Function} scm_cdaddr (pair)
175 @deffnx {C Function} scm_cdadar (pair)
176 @deffnx {C Function} scm_cdaadr (pair)
177 @deffnx {C Function} scm_cdaaar (pair)
178 @deffnx {C Function} scm_cadddr (pair)
179 @deffnx {C Function} scm_caddar (pair)
180 @deffnx {C Function} scm_cadadr (pair)
181 @deffnx {C Function} scm_cadaar (pair)
182 @deffnx {C Function} scm_caaddr (pair)
183 @deffnx {C Function} scm_caadar (pair)
184 @deffnx {C Function} scm_caaadr (pair)
185 @deffnx {C Function} scm_caaaar (pair)
186 These procedures are compositions of @code{car} and @code{cdr}, where
187 for example @code{caddr} could be defined by
190 (define caddr (lambda (x) (car (cdr (cdr x)))))
193 @code{cadr}, @code{caddr} and @code{cadddr} pick out the second, third
194 or fourth elements of a list, respectively. SRFI-1 provides the same
195 under the names @code{second}, @code{third} and @code{fourth}
196 (@pxref{SRFI-1 Selectors}).
200 @deffn {Scheme Procedure} set-car! pair value
201 @deffnx {C Function} scm_set_car_x (pair, value)
202 Stores @var{value} in the car field of @var{pair}. The value returned
203 by @code{set-car!} is unspecified.
207 @deffn {Scheme Procedure} set-cdr! pair value
208 @deffnx {C Function} scm_set_cdr_x (pair, value)
209 Stores @var{value} in the cdr field of @var{pair}. The value returned
210 by @code{set-cdr!} is unspecified.
218 A very important data type in Scheme---as well as in all other Lisp
219 dialects---is the data type @dfn{list}.@footnote{Strictly speaking,
220 Scheme does not have a real datatype @dfn{list}. Lists are made up of
221 @dfn{chained pairs}, and only exist by definition---a list is a chain
222 of pairs which looks like a list.}
224 This is the short definition of what a list is:
228 Either the empty list @code{()},
231 or a pair which has a list in its cdr.
234 @c FIXME::martin: Describe the pair chaining in more detail.
236 @c FIXME::martin: What is a proper, what an improper list?
237 @c What is a circular list?
239 @c FIXME::martin: Maybe steal some graphics from the Elisp reference
243 * List Syntax:: Writing literal lists.
244 * List Predicates:: Testing lists.
245 * List Constructors:: Creating new lists.
246 * List Selection:: Selecting from lists, getting their length.
247 * Append/Reverse:: Appending and reversing lists.
248 * List Modification:: Modifying existing lists.
249 * List Searching:: Searching for list elements
250 * List Mapping:: Applying procedures to lists.
254 @subsubsection List Read Syntax
256 The syntax for lists is an opening parentheses, then all the elements of
257 the list (separated by whitespace) and finally a closing
258 parentheses.@footnote{Note that there is no separation character between
259 the list elements, like a comma or a semicolon.}.
262 (1 2 3) ; @r{a list of the numbers 1, 2 and 3}
263 ("foo" bar 3.1415) ; @r{a string, a symbol and a real number}
264 () ; @r{the empty list}
267 The last example needs a bit more explanation. A list with no elements,
268 called the @dfn{empty list}, is special in some ways. It is used for
269 terminating lists by storing it into the cdr of the last pair that makes
270 up a list. An example will clear that up:
281 This example also shows that lists have to be quoted when written
282 (@pxref{Expression Syntax}), because they would otherwise be
283 mistakingly taken as procedure applications (@pxref{Simple
287 @node List Predicates
288 @subsubsection List Predicates
290 Often it is useful to test whether a given Scheme object is a list or
291 not. List-processing procedures could use this information to test
292 whether their input is valid, or they could do different things
293 depending on the datatype of their arguments.
296 @deffn {Scheme Procedure} list? x
297 @deffnx {C Function} scm_list_p (x)
298 Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
301 The predicate @code{null?} is often used in list-processing code to
302 tell whether a given list has run out of elements. That is, a loop
303 somehow deals with the elements of a list until the list satisfies
304 @code{null?}. Then, the algorithm terminates.
307 @deffn {Scheme Procedure} null? x
308 @deffnx {C Function} scm_null_p (x)
309 Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
312 @deftypefn {C Function} int scm_is_null (SCM x)
313 Return 1 when @var{x} is the empty list; otherwise return 0.
317 @node List Constructors
318 @subsubsection List Constructors
320 This section describes the procedures for constructing new lists.
321 @code{list} simply returns a list where the elements are the arguments,
322 @code{cons*} is similar, but the last argument is stored in the cdr of
323 the last pair of the list.
325 @c C Function scm_list(rest) used to be documented here, but it's a
326 @c no-op since it does nothing but return the list the caller must
327 @c have already created.
329 @deffn {Scheme Procedure} list elem1 @dots{} elemN
330 @deffnx {C Function} scm_list_1 (elem1)
331 @deffnx {C Function} scm_list_2 (elem1, elem2)
332 @deffnx {C Function} scm_list_3 (elem1, elem2, elem3)
333 @deffnx {C Function} scm_list_4 (elem1, elem2, elem3, elem4)
334 @deffnx {C Function} scm_list_5 (elem1, elem2, elem3, elem4, elem5)
335 @deffnx {C Function} scm_list_n (elem1, @dots{}, elemN, @nicode{SCM_UNDEFINED})
337 Return a new list containing elements @var{elem1} to @var{elemN}.
339 @code{scm_list_n} takes a variable number of arguments, terminated by
340 the special @code{SCM_UNDEFINED}. That final @code{SCM_UNDEFINED} is
341 not included in the list. None of @var{elem1} to @var{elemN} can
342 themselves be @code{SCM_UNDEFINED}, or @code{scm_list_n} will
343 terminate at that point.
346 @c C Function scm_cons_star(arg1,rest) used to be documented here,
347 @c but it's not really a useful interface, since it expects the
348 @c caller to have already consed up all but the first argument
351 @deffn {Scheme Procedure} cons* arg1 arg2 @dots{}
352 Like @code{list}, but the last arg provides the tail of the
353 constructed list, returning @code{(cons @var{arg1} (cons
354 @var{arg2} (cons @dots{} @var{argn})))}. Requires at least one
355 argument. If given one argument, that argument is returned as
356 result. This function is called @code{list*} in some other
357 Schemes and in Common LISP.
360 @deffn {Scheme Procedure} list-copy lst
361 @deffnx {C Function} scm_list_copy (lst)
362 Return a (newly-created) copy of @var{lst}.
365 @deffn {Scheme Procedure} make-list n [init]
366 Create a list containing of @var{n} elements, where each element is
367 initialized to @var{init}. @var{init} defaults to the empty list
368 @code{()} if not given.
371 Note that @code{list-copy} only makes a copy of the pairs which make up
372 the spine of the lists. The list elements are not copied, which means
373 that modifying the elements of the new list also modifies the elements
374 of the old list. On the other hand, applying procedures like
375 @code{set-cdr!} or @code{delv!} to the new list will not alter the old
376 list. If you also need to copy the list elements (making a deep copy),
377 use the procedure @code{copy-tree} (@pxref{Copying}).
380 @subsubsection List Selection
382 These procedures are used to get some information about a list, or to
383 retrieve one or more elements of a list.
386 @deffn {Scheme Procedure} length lst
387 @deffnx {C Function} scm_length (lst)
388 Return the number of elements in list @var{lst}.
391 @deffn {Scheme Procedure} last-pair lst
392 @deffnx {C Function} scm_last_pair (lst)
393 Return the last pair in @var{lst}, signalling an error if
394 @var{lst} is circular.
398 @deffn {Scheme Procedure} list-ref list k
399 @deffnx {C Function} scm_list_ref (list, k)
400 Return the @var{k}th element from @var{list}.
404 @deffn {Scheme Procedure} list-tail lst k
405 @deffnx {Scheme Procedure} list-cdr-ref lst k
406 @deffnx {C Function} scm_list_tail (lst, k)
407 Return the "tail" of @var{lst} beginning with its @var{k}th element.
408 The first element of the list is considered to be element 0.
410 @code{list-tail} and @code{list-cdr-ref} are identical. It may help to
411 think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list,
412 or returning the results of cdring @var{k} times down @var{lst}.
415 @deffn {Scheme Procedure} list-head lst k
416 @deffnx {C Function} scm_list_head (lst, k)
417 Copy the first @var{k} elements from @var{lst} into a new list, and
422 @subsubsection Append and Reverse
424 @code{append} and @code{append!} are used to concatenate two or more
425 lists in order to form a new list. @code{reverse} and @code{reverse!}
426 return lists with the same elements as their arguments, but in reverse
427 order. The procedure variants with an @code{!} directly modify the
428 pairs which form the list, whereas the other procedures create new
429 pairs. This is why you should be careful when using the side-effecting
433 @deffn {Scheme Procedure} append lst1 @dots{} lstN
434 @deffnx {Scheme Procedure} append! lst1 @dots{} lstN
435 @deffnx {C Function} scm_append (lstlst)
436 @deffnx {C Function} scm_append_x (lstlst)
437 Return a list comprising all the elements of lists @var{lst1} to
441 (append '(x) '(y)) @result{} (x y)
442 (append '(a) '(b c d)) @result{} (a b c d)
443 (append '(a (b)) '((c))) @result{} (a (b) (c))
446 The last argument @var{lstN} may actually be any object; an improper
447 list results if the last argument is not a proper list.
450 (append '(a b) '(c . d)) @result{} (a b c . d)
451 (append '() 'a) @result{} a
454 @code{append} doesn't modify the given lists, but the return may share
455 structure with the final @var{lstN}. @code{append!} modifies the
456 given lists to form its return.
458 For @code{scm_append} and @code{scm_append_x}, @var{lstlst} is a list
459 of the list operands @var{lst1} @dots{} @var{lstN}. That @var{lstlst}
460 itself is not modified or used in the return.
464 @deffn {Scheme Procedure} reverse lst
465 @deffnx {Scheme Procedure} reverse! lst [newtail]
466 @deffnx {C Function} scm_reverse (lst)
467 @deffnx {C Function} scm_reverse_x (lst, newtail)
468 Return a list comprising the elements of @var{lst}, in reverse order.
470 @code{reverse} constructs a new list, @code{reverse!} modifies
471 @var{lst} in constructing its return.
473 For @code{reverse!}, the optional @var{newtail} is appended to to the
474 result. @var{newtail} isn't reversed, it simply becomes the list
475 tail. For @code{scm_reverse_x}, the @var{newtail} parameter is
476 mandatory, but can be @code{SCM_EOL} if no further tail is required.
479 @node List Modification
480 @subsubsection List Modification
482 The following procedures modify an existing list, either by changing
483 elements of the list, or by changing the list structure itself.
485 @deffn {Scheme Procedure} list-set! list k val
486 @deffnx {C Function} scm_list_set_x (list, k, val)
487 Set the @var{k}th element of @var{list} to @var{val}.
490 @deffn {Scheme Procedure} list-cdr-set! list k val
491 @deffnx {C Function} scm_list_cdr_set_x (list, k, val)
492 Set the @var{k}th cdr of @var{list} to @var{val}.
495 @deffn {Scheme Procedure} delq item lst
496 @deffnx {C Function} scm_delq (item, lst)
497 Return a newly-created copy of @var{lst} with elements
498 @code{eq?} to @var{item} removed. This procedure mirrors
499 @code{memq}: @code{delq} compares elements of @var{lst} against
500 @var{item} with @code{eq?}.
503 @deffn {Scheme Procedure} delv item lst
504 @deffnx {C Function} scm_delv (item, lst)
505 Return a newly-created copy of @var{lst} with elements
506 @code{eqv?} to @var{item} removed. This procedure mirrors
507 @code{memv}: @code{delv} compares elements of @var{lst} against
508 @var{item} with @code{eqv?}.
511 @deffn {Scheme Procedure} delete item lst
512 @deffnx {C Function} scm_delete (item, lst)
513 Return a newly-created copy of @var{lst} with elements
514 @code{equal?} to @var{item} removed. This procedure mirrors
515 @code{member}: @code{delete} compares elements of @var{lst}
516 against @var{item} with @code{equal?}.
518 See also SRFI-1 which has an extended @code{delete} (@ref{SRFI-1
519 Deleting}), and also an @code{lset-difference} which can delete
520 multiple @var{item}s in one call (@ref{SRFI-1 Set Operations}).
523 @deffn {Scheme Procedure} delq! item lst
524 @deffnx {Scheme Procedure} delv! item lst
525 @deffnx {Scheme Procedure} delete! item lst
526 @deffnx {C Function} scm_delq_x (item, lst)
527 @deffnx {C Function} scm_delv_x (item, lst)
528 @deffnx {C Function} scm_delete_x (item, lst)
529 These procedures are destructive versions of @code{delq}, @code{delv}
530 and @code{delete}: they modify the pointers in the existing @var{lst}
531 rather than creating a new list. Caveat evaluator: Like other
532 destructive list functions, these functions cannot modify the binding of
533 @var{lst}, and so cannot be used to delete the first element of
534 @var{lst} destructively.
537 @deffn {Scheme Procedure} delq1! item lst
538 @deffnx {C Function} scm_delq1_x (item, lst)
539 Like @code{delq!}, but only deletes the first occurrence of
540 @var{item} from @var{lst}. Tests for equality using
541 @code{eq?}. See also @code{delv1!} and @code{delete1!}.
544 @deffn {Scheme Procedure} delv1! item lst
545 @deffnx {C Function} scm_delv1_x (item, lst)
546 Like @code{delv!}, but only deletes the first occurrence of
547 @var{item} from @var{lst}. Tests for equality using
548 @code{eqv?}. See also @code{delq1!} and @code{delete1!}.
551 @deffn {Scheme Procedure} delete1! item lst
552 @deffnx {C Function} scm_delete1_x (item, lst)
553 Like @code{delete!}, but only deletes the first occurrence of
554 @var{item} from @var{lst}. Tests for equality using
555 @code{equal?}. See also @code{delq1!} and @code{delv1!}.
558 @deffn {Scheme Procedure} filter pred lst
559 @deffnx {Scheme Procedure} filter! pred lst
560 Return a list containing all elements from @var{lst} which satisfy the
561 predicate @var{pred}. The elements in the result list have the same
562 order as in @var{lst}. The order in which @var{pred} is applied to
563 the list elements is not specified.
565 @code{filter} does not change @var{lst}, but the result may share a
566 tail with it. @code{filter!} may modify @var{lst} to construct its
571 @subsubsection List Searching
573 The following procedures search lists for particular elements. They use
574 different comparison predicates for comparing list elements with the
575 object to be searched. When they fail, they return @code{#f}, otherwise
576 they return the sublist whose car is equal to the search object, where
577 equality depends on the equality predicate used.
580 @deffn {Scheme Procedure} memq x lst
581 @deffnx {C Function} scm_memq (x, lst)
582 Return the first sublist of @var{lst} whose car is @code{eq?}
583 to @var{x} where the sublists of @var{lst} are the non-empty
584 lists returned by @code{(list-tail @var{lst} @var{k})} for
585 @var{k} less than the length of @var{lst}. If @var{x} does not
586 occur in @var{lst}, then @code{#f} (not the empty list) is
591 @deffn {Scheme Procedure} memv x lst
592 @deffnx {C Function} scm_memv (x, lst)
593 Return the first sublist of @var{lst} whose car is @code{eqv?}
594 to @var{x} where the sublists of @var{lst} are the non-empty
595 lists returned by @code{(list-tail @var{lst} @var{k})} for
596 @var{k} less than the length of @var{lst}. If @var{x} does not
597 occur in @var{lst}, then @code{#f} (not the empty list) is
602 @deffn {Scheme Procedure} member x lst
603 @deffnx {C Function} scm_member (x, lst)
604 Return the first sublist of @var{lst} whose car is
605 @code{equal?} to @var{x} where the sublists of @var{lst} are
606 the non-empty lists returned by @code{(list-tail @var{lst}
607 @var{k})} for @var{k} less than the length of @var{lst}. If
608 @var{x} does not occur in @var{lst}, then @code{#f} (not the
609 empty list) is returned.
611 See also SRFI-1 which has an extended @code{member} function
612 (@ref{SRFI-1 Searching}).
617 @subsubsection List Mapping
619 List processing is very convenient in Scheme because the process of
620 iterating over the elements of a list can be highly abstracted. The
621 procedures in this section are the most basic iterating procedures for
622 lists. They take a procedure and one or more lists as arguments, and
623 apply the procedure to each element of the list. They differ in their
627 @c begin (texi-doc-string "guile" "map")
628 @deffn {Scheme Procedure} map proc arg1 arg2 @dots{}
629 @deffnx {Scheme Procedure} map-in-order proc arg1 arg2 @dots{}
630 @deffnx {C Function} scm_map (proc, arg1, args)
631 Apply @var{proc} to each element of the list @var{arg1} (if only two
632 arguments are given), or to the corresponding elements of the argument
633 lists (if more than two arguments are given). The result(s) of the
634 procedure applications are saved and returned in a list. For
635 @code{map}, the order of procedure applications is not specified,
636 @code{map-in-order} applies the procedure from left to right to the list
641 @c begin (texi-doc-string "guile" "for-each")
642 @deffn {Scheme Procedure} for-each proc arg1 arg2 @dots{}
643 Like @code{map}, but the procedure is always applied from left to right,
644 and the result(s) of the procedure applications are thrown away. The
645 return value is not specified.
648 See also SRFI-1 which extends these functions to take lists of unequal
649 lengths (@ref{SRFI-1 Fold and Map}).
655 Vectors are sequences of Scheme objects. Unlike lists, the length of a
656 vector, once the vector is created, cannot be changed. The advantage of
657 vectors over lists is that the time required to access one element of a vector
658 given its @dfn{position} (synonymous with @dfn{index}), a zero-origin number,
659 is constant, whereas lists have an access time linear to the position of the
660 accessed element in the list.
662 Vectors can contain any kind of Scheme object; it is even possible to
663 have different types of objects in the same vector. For vectors
664 containing vectors, you may wish to use arrays, instead. Note, too,
665 that vectors are the special case of one dimensional non-uniform arrays
666 and that most array procedures operate happily on vectors
670 * Vector Syntax:: Read syntax for vectors.
671 * Vector Creation:: Dynamic vector creation and validation.
672 * Vector Accessors:: Accessing and modifying vector contents.
673 * Vector Accessing from C:: Ways to work with vectors from C.
678 @subsubsection Read Syntax for Vectors
680 Vectors can literally be entered in source code, just like strings,
681 characters or some of the other data types. The read syntax for vectors
682 is as follows: A sharp sign (@code{#}), followed by an opening
683 parentheses, all elements of the vector in their respective read syntax,
684 and finally a closing parentheses. The following are examples of the
685 read syntax for vectors; where the first vector only contains numbers
686 and the second three different object types: a string, a symbol and a
687 number in hexadecimal notation.
691 #("Hello" foo #xdeadbeef)
694 Like lists, vectors have to be quoted:
697 '#(a b c) @result{} #(a b c)
700 @node Vector Creation
701 @subsubsection Dynamic Vector Creation and Validation
703 Instead of creating a vector implicitly by using the read syntax just
704 described, you can create a vector dynamically by calling one of the
705 @code{vector} and @code{list->vector} primitives with the list of Scheme
706 values that you want to place into a vector. The size of the vector
707 thus created is determined implicitly by the number of arguments given.
710 @rnindex list->vector
711 @deffn {Scheme Procedure} vector . l
712 @deffnx {Scheme Procedure} list->vector l
713 @deffnx {C Function} scm_vector (l)
714 Return a newly allocated vector composed of the
715 given arguments. Analogous to @code{list}.
718 (vector 'a 'b 'c) @result{} #(a b c)
722 The inverse operation is @code{vector->list}:
724 @rnindex vector->list
725 @deffn {Scheme Procedure} vector->list v
726 @deffnx {C Function} scm_vector_to_list (v)
727 Return a newly allocated list composed of the elements of @var{v}.
730 (vector->list '#(dah dah didah)) @result{} (dah dah didah)
731 (list->vector '(dididit dah)) @result{} #(dididit dah)
735 To allocate a vector with an explicitly specified size, use
736 @code{make-vector}. With this primitive you can also specify an initial
737 value for the vector elements (the same value for all elements, that
741 @deffn {Scheme Procedure} make-vector len [fill]
742 @deffnx {C Function} scm_make_vector (len, fill)
743 Return a newly allocated vector of @var{len} elements. If a
744 second argument is given, then each position is initialized to
745 @var{fill}. Otherwise the initial contents of each position is
749 @deftypefn {C Function} SCM scm_c_make_vector (size_t k, SCM fill)
750 Like @code{scm_make_vector}, but the length is given as a @code{size_t}.
753 To check whether an arbitrary Scheme value @emph{is} a vector, use the
754 @code{vector?} primitive:
757 @deffn {Scheme Procedure} vector? obj
758 @deffnx {C Function} scm_vector_p (obj)
759 Return @code{#t} if @var{obj} is a vector, otherwise return
763 @deftypefn {C Function} int scm_is_vector (SCM obj)
764 Return non-zero when @var{obj} is a vector, otherwise return
768 @node Vector Accessors
769 @subsubsection Accessing and Modifying Vector Contents
771 @code{vector-length} and @code{vector-ref} return information about a
772 given vector, respectively its size and the elements that are contained
775 @rnindex vector-length
776 @deffn {Scheme Procedure} vector-length vector
777 @deffnx {C Function} scm_vector_length vector
778 Return the number of elements in @var{vector} as an exact integer.
781 @deftypefn {C Function} size_t scm_c_vector_length (SCM v)
782 Return the number of elements in @var{vector} as a @code{size_t}.
786 @deffn {Scheme Procedure} vector-ref vector k
787 @deffnx {C Function} scm_vector_ref vector k
788 Return the contents of position @var{k} of @var{vector}.
789 @var{k} must be a valid index of @var{vector}.
791 (vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
792 (vector-ref '#(1 1 2 3 5 8 13 21)
793 (let ((i (round (* 2 (acos -1)))))
800 @deftypefn {C Function} SCM scm_c_vector_ref (SCM v, size_t k)
801 Return the contents of position @var{k} (a @code{size_t}) of
805 A vector created by one of the dynamic vector constructor procedures
806 (@pxref{Vector Creation}) can be modified using the following
809 @emph{NOTE:} According to R5RS, it is an error to use any of these
810 procedures on a literally read vector, because such vectors should be
811 considered as constants. Currently, however, Guile does not detect this
815 @deffn {Scheme Procedure} vector-set! vector k obj
816 @deffnx {C Function} scm_vector_set_x vector k obj
817 Store @var{obj} in position @var{k} of @var{vector}.
818 @var{k} must be a valid index of @var{vector}.
819 The value returned by @samp{vector-set!} is unspecified.
821 (let ((vec (vector 0 '(2 2 2 2) "Anna")))
822 (vector-set! vec 1 '("Sue" "Sue"))
823 vec) @result{} #(0 ("Sue" "Sue") "Anna")
827 @deftypefn {C Function} void scm_c_vector_set_x (SCM v, size_t k, SCM obj)
828 Store @var{obj} in position @var{k} (a @code{size_t}) of @var{v}.
831 @rnindex vector-fill!
832 @deffn {Scheme Procedure} vector-fill! v fill
833 @deffnx {C Function} scm_vector_fill_x (v, fill)
834 Store @var{fill} in every position of @var{vector}. The value
835 returned by @code{vector-fill!} is unspecified.
838 @deffn {Scheme Procedure} vector-copy vec
839 @deffnx {C Function} scm_vector_copy (vec)
840 Return a copy of @var{vec}.
843 @deffn {Scheme Procedure} vector-move-left! vec1 start1 end1 vec2 start2
844 @deffnx {C Function} scm_vector_move_left_x (vec1, start1, end1, vec2, start2)
845 Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
846 to @var{vec2} starting at position @var{start2}. @var{start1} and
847 @var{start2} are inclusive indices; @var{end1} is exclusive.
849 @code{vector-move-left!} copies elements in leftmost order.
850 Therefore, in the case where @var{vec1} and @var{vec2} refer to the
851 same vector, @code{vector-move-left!} is usually appropriate when
852 @var{start1} is greater than @var{start2}.
855 @deffn {Scheme Procedure} vector-move-right! vec1 start1 end1 vec2 start2
856 @deffnx {C Function} scm_vector_move_right_x (vec1, start1, end1, vec2, start2)
857 Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
858 to @var{vec2} starting at position @var{start2}. @var{start1} and
859 @var{start2} are inclusive indices; @var{end1} is exclusive.
861 @code{vector-move-right!} copies elements in rightmost order.
862 Therefore, in the case where @var{vec1} and @var{vec2} refer to the
863 same vector, @code{vector-move-right!} is usually appropriate when
864 @var{start1} is less than @var{start2}.
867 @node Vector Accessing from C
868 @subsubsection Vector Accessing from C
870 A vector can be read and modified from C with the functions
871 @code{scm_c_vector_ref} and @code{scm_c_vector_set_x}, for example. In
872 addition to these functions, there are two more ways to access vectors
873 from C that might be more efficient in certain situations: you can
874 restrict yourself to @dfn{simple vectors} and then use the very fast
875 @emph{simple vector macros}; or you can use the very general framework
876 for accessing all kinds of arrays (@pxref{Accessing Arrays from C}),
877 which is more verbose, but can deal efficiently with all kinds of
878 vectors (and arrays). For vectors, you can use the
879 @code{scm_vector_elements} and @code{scm_vector_writable_elements}
880 functions as shortcuts.
882 @deftypefn {C Function} int scm_is_simple_vector (SCM obj)
883 Return non-zero if @var{obj} is a simple vector, else return zero. A
884 simple vector is a vector that can be used with the @code{SCM_SIMPLE_*}
887 The following functions are guaranteed to return simple vectors:
888 @code{scm_make_vector}, @code{scm_c_make_vector}, @code{scm_vector},
889 @code{scm_list_to_vector}.
892 @deftypefn {C Macro} size_t SCM_SIMPLE_VECTOR_LENGTH (SCM vec)
893 Evaluates to the length of the simple vector @var{vec}. No type
897 @deftypefn {C Macro} SCM SCM_SIMPLE_VECTOR_REF (SCM vec, size_t idx)
898 Evaluates to the element at position @var{idx} in the simple vector
899 @var{vec}. No type or range checking is done.
902 @deftypefn {C Macro} void SCM_SIMPLE_VECTOR_SET (SCM vec, size_t idx, SCM val)
903 Sets the element at position @var{idx} in the simple vector
904 @var{vec} to @var{val}. No type or range checking is done.
907 @deftypefn {C Function} {const SCM *} scm_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
908 Acquire a handle for the vector @var{vec} and return a pointer to the
909 elements of it. This pointer can only be used to read the elements of
910 @var{vec}. When @var{vec} is not a vector, an error is signaled. The
911 handle mustr eventually be released with
912 @code{scm_array_handle_release}.
914 The variables pointed to by @var{lenp} and @var{incp} are filled with
915 the number of elements of the vector and the increment (number of
916 elements) between successive elements, respectively. Successive
917 elements of @var{vec} need not be contiguous in their underlying
918 ``root vector'' returned here; hence the increment is not necessarily
919 equal to 1 and may well be negative too (@pxref{Shared Arrays}).
921 The following example shows the typical way to use this function. It
922 creates a list of all elements of @var{vec} (in reverse order).
925 scm_t_array_handle handle;
931 elt = scm_vector_elements (vec, &handle, &len, &inc);
933 for (i = 0; i < len; i++, elt += inc)
934 list = scm_cons (*elt, list);
935 scm_array_handle_release (&handle);
940 @deftypefn {C Function} {SCM *} scm_vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
941 Like @code{scm_vector_elements} but the pointer can be used to modify
944 The following example shows the typical way to use this function. It
945 fills a vector with @code{#t}.
948 scm_t_array_handle handle;
953 elt = scm_vector_writable_elements (vec, &handle, &len, &inc);
954 for (i = 0; i < len; i++, elt += inc)
956 scm_array_handle_release (&handle);
961 @node Uniform Numeric Vectors
962 @subsection Uniform Numeric Vectors
964 A uniform numeric vector is a vector whose elements are all of a single
965 numeric type. Guile offers uniform numeric vectors for signed and
966 unsigned 8-bit, 16-bit, 32-bit, and 64-bit integers, two sizes of
967 floating point values, and complex floating-point numbers of these two
970 Strings could be regarded as uniform vectors of characters,
971 @xref{Strings}. Likewise, bit vectors could be regarded as uniform
972 vectors of bits, @xref{Bit Vectors}. Both are sufficiently different
973 from uniform numeric vectors that the procedures described here do not
974 apply to these two data types. However, both strings and bit vectors
975 are generalized vectors, @xref{Generalized Vectors}, and arrays,
978 Uniform numeric vectors are the special case of one dimensional uniform
981 Uniform numeric vectors can be useful since they consume less memory
982 than the non-uniform, general vectors. Also, since the types they can
983 store correspond directly to C types, it is easier to work with them
984 efficiently on a low level. Consider image processing as an example,
985 where you want to apply a filter to some image. While you could store
986 the pixels of an image in a general vector and write a general
987 convolution function, things are much more efficient with uniform
988 vectors: the convolution function knows that all pixels are unsigned
989 8-bit values (say), and can use a very tight inner loop.
991 That is, when it is written in C. Functions for efficiently working
992 with uniform numeric vectors from C are listed at the end of this
995 Procedures similar to the vector procedures (@pxref{Vectors}) are
996 provided for handling these uniform vectors, but they are distinct
997 datatypes and the two cannot be inter-mixed. If you want to work
998 primarily with uniform numeric vectors, but want to offer support for
999 general vectors as a convenience, you can use one of the
1000 @code{scm_any_to_*} functions. They will coerce lists and vectors to
1001 the given type of uniform vector. Alternatively, you can write two
1002 versions of your code: one that is fast and works only with uniform
1003 numeric vectors, and one that works with any kind of vector but is
1006 One set of the procedures listed below is a generic one: it works with
1007 all types of uniform numeric vectors. In addition to that, there is a
1008 set of procedures for each type that only works with that type. Unless
1009 you really need to the generality of the first set, it is best to use
1010 the more specific functions. They might not be that much faster, but
1011 their use can serve as a kind of declaration and makes it easier to
1014 The generic set of procedures uses @code{uniform} in its names, the
1015 specific ones use the tag from the following table.
1019 unsigned 8-bit integers
1022 signed 8-bit integers
1025 unsigned 16-bit integers
1028 signed 16-bit integers
1031 unsigned 32-bit integers
1034 signed 32-bit integers
1037 unsigned 64-bit integers
1040 signed 64-bit integers
1043 the C type @code{float}
1046 the C type @code{double}
1049 complex numbers in rectangular form with the real and imaginary part
1050 being a @code{float}
1053 complex numbers in rectangular form with the real and imaginary part
1054 being a @code{double}
1058 The external representation (ie.@: read syntax) for these vectors is
1059 similar to normal Scheme vectors, but with an additional tag from the
1060 table above indiciating the vector's type. For example,
1067 Note that the read syntax for floating-point here conflicts with
1068 @code{#f} for false. In Standard Scheme one can write @code{(1 #f3)}
1069 for a three element list @code{(1 #f 3)}, but for Guile @code{(1 #f3)}
1070 is invalid. @code{(1 #f 3)} is almost certainly what one should write
1071 anyway to make the intention clear, so this is rarely a problem.
1073 @deffn {Scheme Procedure} uniform-vector? obj
1074 @deffnx {Scheme Procedure} u8vector? obj
1075 @deffnx {Scheme Procedure} s8vector? obj
1076 @deffnx {Scheme Procedure} u16vector? obj
1077 @deffnx {Scheme Procedure} s16vector? obj
1078 @deffnx {Scheme Procedure} u32vector? obj
1079 @deffnx {Scheme Procedure} s32vector? obj
1080 @deffnx {Scheme Procedure} u64vector? obj
1081 @deffnx {Scheme Procedure} s64vector? obj
1082 @deffnx {Scheme Procedure} f32vector? obj
1083 @deffnx {Scheme Procedure} f64vector? obj
1084 @deffnx {Scheme Procedure} c32vector? obj
1085 @deffnx {Scheme Procedure} c64vector? obj
1086 @deffnx {C Function} scm_uniform_vector_p (obj)
1087 @deffnx {C Function} scm_u8vector_p (obj)
1088 @deffnx {C Function} scm_s8vector_p (obj)
1089 @deffnx {C Function} scm_u16vector_p (obj)
1090 @deffnx {C Function} scm_s16vector_p (obj)
1091 @deffnx {C Function} scm_u32vector_p (obj)
1092 @deffnx {C Function} scm_s32vector_p (obj)
1093 @deffnx {C Function} scm_u64vector_p (obj)
1094 @deffnx {C Function} scm_s64vector_p (obj)
1095 @deffnx {C Function} scm_f32vector_p (obj)
1096 @deffnx {C Function} scm_f64vector_p (obj)
1097 @deffnx {C Function} scm_c32vector_p (obj)
1098 @deffnx {C Function} scm_c64vector_p (obj)
1099 Return @code{#t} if @var{obj} is a homogeneous numeric vector of the
1103 @deffn {Scheme Procedure} make-u8vector n [value]
1104 @deffnx {Scheme Procedure} make-s8vector n [value]
1105 @deffnx {Scheme Procedure} make-u16vector n [value]
1106 @deffnx {Scheme Procedure} make-s16vector n [value]
1107 @deffnx {Scheme Procedure} make-u32vector n [value]
1108 @deffnx {Scheme Procedure} make-s32vector n [value]
1109 @deffnx {Scheme Procedure} make-u64vector n [value]
1110 @deffnx {Scheme Procedure} make-s64vector n [value]
1111 @deffnx {Scheme Procedure} make-f32vector n [value]
1112 @deffnx {Scheme Procedure} make-f64vector n [value]
1113 @deffnx {Scheme Procedure} make-c32vector n [value]
1114 @deffnx {Scheme Procedure} make-c64vector n [value]
1115 @deffnx {C Function} scm_make_u8vector n [value]
1116 @deffnx {C Function} scm_make_s8vector n [value]
1117 @deffnx {C Function} scm_make_u16vector n [value]
1118 @deffnx {C Function} scm_make_s16vector n [value]
1119 @deffnx {C Function} scm_make_u32vector n [value]
1120 @deffnx {C Function} scm_make_s32vector n [value]
1121 @deffnx {C Function} scm_make_u64vector n [value]
1122 @deffnx {C Function} scm_make_s64vector n [value]
1123 @deffnx {C Function} scm_make_f32vector n [value]
1124 @deffnx {C Function} scm_make_f64vector n [value]
1125 @deffnx {C Function} scm_make_c32vector n [value]
1126 @deffnx {C Function} scm_make_c64vector n [value]
1127 Return a newly allocated homogeneous numeric vector holding @var{n}
1128 elements of the indicated type. If @var{value} is given, the vector
1129 is initialized with that value, otherwise the contents are
1133 @deffn {Scheme Procedure} u8vector value @dots{}
1134 @deffnx {Scheme Procedure} s8vector value @dots{}
1135 @deffnx {Scheme Procedure} u16vector value @dots{}
1136 @deffnx {Scheme Procedure} s16vector value @dots{}
1137 @deffnx {Scheme Procedure} u32vector value @dots{}
1138 @deffnx {Scheme Procedure} s32vector value @dots{}
1139 @deffnx {Scheme Procedure} u64vector value @dots{}
1140 @deffnx {Scheme Procedure} s64vector value @dots{}
1141 @deffnx {Scheme Procedure} f32vector value @dots{}
1142 @deffnx {Scheme Procedure} f64vector value @dots{}
1143 @deffnx {Scheme Procedure} c32vector value @dots{}
1144 @deffnx {Scheme Procedure} c64vector value @dots{}
1145 @deffnx {C Function} scm_u8vector (values)
1146 @deffnx {C Function} scm_s8vector (values)
1147 @deffnx {C Function} scm_u16vector (values)
1148 @deffnx {C Function} scm_s16vector (values)
1149 @deffnx {C Function} scm_u32vector (values)
1150 @deffnx {C Function} scm_s32vector (values)
1151 @deffnx {C Function} scm_u64vector (values)
1152 @deffnx {C Function} scm_s64vector (values)
1153 @deffnx {C Function} scm_f32vector (values)
1154 @deffnx {C Function} scm_f64vector (values)
1155 @deffnx {C Function} scm_c32vector (values)
1156 @deffnx {C Function} scm_c64vector (values)
1157 Return a newly allocated homogeneous numeric vector of the indicated
1158 type, holding the given parameter @var{value}s. The vector length is
1159 the number of parameters given.
1162 @deffn {Scheme Procedure} uniform-vector-length vec
1163 @deffnx {Scheme Procedure} u8vector-length vec
1164 @deffnx {Scheme Procedure} s8vector-length vec
1165 @deffnx {Scheme Procedure} u16vector-length vec
1166 @deffnx {Scheme Procedure} s16vector-length vec
1167 @deffnx {Scheme Procedure} u32vector-length vec
1168 @deffnx {Scheme Procedure} s32vector-length vec
1169 @deffnx {Scheme Procedure} u64vector-length vec
1170 @deffnx {Scheme Procedure} s64vector-length vec
1171 @deffnx {Scheme Procedure} f32vector-length vec
1172 @deffnx {Scheme Procedure} f64vector-length vec
1173 @deffnx {Scheme Procedure} c32vector-length vec
1174 @deffnx {Scheme Procedure} c64vector-length vec
1175 @deffnx {C Function} scm_uniform_vector_length (vec)
1176 @deffnx {C Function} scm_u8vector_length (vec)
1177 @deffnx {C Function} scm_s8vector_length (vec)
1178 @deffnx {C Function} scm_u16vector_length (vec)
1179 @deffnx {C Function} scm_s16vector_length (vec)
1180 @deffnx {C Function} scm_u32vector_length (vec)
1181 @deffnx {C Function} scm_s32vector_length (vec)
1182 @deffnx {C Function} scm_u64vector_length (vec)
1183 @deffnx {C Function} scm_s64vector_length (vec)
1184 @deffnx {C Function} scm_f32vector_length (vec)
1185 @deffnx {C Function} scm_f64vector_length (vec)
1186 @deffnx {C Function} scm_c32vector_length (vec)
1187 @deffnx {C Function} scm_c64vector_length (vec)
1188 Return the number of elements in @var{vec}.
1191 @deffn {Scheme Procedure} uniform-vector-ref vec i
1192 @deffnx {Scheme Procedure} u8vector-ref vec i
1193 @deffnx {Scheme Procedure} s8vector-ref vec i
1194 @deffnx {Scheme Procedure} u16vector-ref vec i
1195 @deffnx {Scheme Procedure} s16vector-ref vec i
1196 @deffnx {Scheme Procedure} u32vector-ref vec i
1197 @deffnx {Scheme Procedure} s32vector-ref vec i
1198 @deffnx {Scheme Procedure} u64vector-ref vec i
1199 @deffnx {Scheme Procedure} s64vector-ref vec i
1200 @deffnx {Scheme Procedure} f32vector-ref vec i
1201 @deffnx {Scheme Procedure} f64vector-ref vec i
1202 @deffnx {Scheme Procedure} c32vector-ref vec i
1203 @deffnx {Scheme Procedure} c64vector-ref vec i
1204 @deffnx {C Function} scm_uniform_vector_ref (vec i)
1205 @deffnx {C Function} scm_u8vector_ref (vec i)
1206 @deffnx {C Function} scm_s8vector_ref (vec i)
1207 @deffnx {C Function} scm_u16vector_ref (vec i)
1208 @deffnx {C Function} scm_s16vector_ref (vec i)
1209 @deffnx {C Function} scm_u32vector_ref (vec i)
1210 @deffnx {C Function} scm_s32vector_ref (vec i)
1211 @deffnx {C Function} scm_u64vector_ref (vec i)
1212 @deffnx {C Function} scm_s64vector_ref (vec i)
1213 @deffnx {C Function} scm_f32vector_ref (vec i)
1214 @deffnx {C Function} scm_f64vector_ref (vec i)
1215 @deffnx {C Function} scm_c32vector_ref (vec i)
1216 @deffnx {C Function} scm_c64vector_ref (vec i)
1217 Return the element at index @var{i} in @var{vec}. The first element
1218 in @var{vec} is index 0.
1221 @deffn {Scheme Procedure} uniform-vector-set! vec i value
1222 @deffnx {Scheme Procedure} u8vector-set! vec i value
1223 @deffnx {Scheme Procedure} s8vector-set! vec i value
1224 @deffnx {Scheme Procedure} u16vector-set! vec i value
1225 @deffnx {Scheme Procedure} s16vector-set! vec i value
1226 @deffnx {Scheme Procedure} u32vector-set! vec i value
1227 @deffnx {Scheme Procedure} s32vector-set! vec i value
1228 @deffnx {Scheme Procedure} u64vector-set! vec i value
1229 @deffnx {Scheme Procedure} s64vector-set! vec i value
1230 @deffnx {Scheme Procedure} f32vector-set! vec i value
1231 @deffnx {Scheme Procedure} f64vector-set! vec i value
1232 @deffnx {Scheme Procedure} c32vector-set! vec i value
1233 @deffnx {Scheme Procedure} c64vector-set! vec i value
1234 @deffnx {C Function} scm_uniform_vector_set_x (vec i value)
1235 @deffnx {C Function} scm_u8vector_set_x (vec i value)
1236 @deffnx {C Function} scm_s8vector_set_x (vec i value)
1237 @deffnx {C Function} scm_u16vector_set_x (vec i value)
1238 @deffnx {C Function} scm_s16vector_set_x (vec i value)
1239 @deffnx {C Function} scm_u32vector_set_x (vec i value)
1240 @deffnx {C Function} scm_s32vector_set_x (vec i value)
1241 @deffnx {C Function} scm_u64vector_set_x (vec i value)
1242 @deffnx {C Function} scm_s64vector_set_x (vec i value)
1243 @deffnx {C Function} scm_f32vector_set_x (vec i value)
1244 @deffnx {C Function} scm_f64vector_set_x (vec i value)
1245 @deffnx {C Function} scm_c32vector_set_x (vec i value)
1246 @deffnx {C Function} scm_c64vector_set_x (vec i value)
1247 Set the element at index @var{i} in @var{vec} to @var{value}. The
1248 first element in @var{vec} is index 0. The return value is
1252 @deffn {Scheme Procedure} uniform-vector->list vec
1253 @deffnx {Scheme Procedure} u8vector->list vec
1254 @deffnx {Scheme Procedure} s8vector->list vec
1255 @deffnx {Scheme Procedure} u16vector->list vec
1256 @deffnx {Scheme Procedure} s16vector->list vec
1257 @deffnx {Scheme Procedure} u32vector->list vec
1258 @deffnx {Scheme Procedure} s32vector->list vec
1259 @deffnx {Scheme Procedure} u64vector->list vec
1260 @deffnx {Scheme Procedure} s64vector->list vec
1261 @deffnx {Scheme Procedure} f32vector->list vec
1262 @deffnx {Scheme Procedure} f64vector->list vec
1263 @deffnx {Scheme Procedure} c32vector->list vec
1264 @deffnx {Scheme Procedure} c64vector->list vec
1265 @deffnx {C Function} scm_uniform_vector_to_list (vec)
1266 @deffnx {C Function} scm_u8vector_to_list (vec)
1267 @deffnx {C Function} scm_s8vector_to_list (vec)
1268 @deffnx {C Function} scm_u16vector_to_list (vec)
1269 @deffnx {C Function} scm_s16vector_to_list (vec)
1270 @deffnx {C Function} scm_u32vector_to_list (vec)
1271 @deffnx {C Function} scm_s32vector_to_list (vec)
1272 @deffnx {C Function} scm_u64vector_to_list (vec)
1273 @deffnx {C Function} scm_s64vector_to_list (vec)
1274 @deffnx {C Function} scm_f32vector_to_list (vec)
1275 @deffnx {C Function} scm_f64vector_to_list (vec)
1276 @deffnx {C Function} scm_c32vector_to_list (vec)
1277 @deffnx {C Function} scm_c64vector_to_list (vec)
1278 Return a newly allocated list holding all elements of @var{vec}.
1281 @deffn {Scheme Procedure} list->u8vector lst
1282 @deffnx {Scheme Procedure} list->s8vector lst
1283 @deffnx {Scheme Procedure} list->u16vector lst
1284 @deffnx {Scheme Procedure} list->s16vector lst
1285 @deffnx {Scheme Procedure} list->u32vector lst
1286 @deffnx {Scheme Procedure} list->s32vector lst
1287 @deffnx {Scheme Procedure} list->u64vector lst
1288 @deffnx {Scheme Procedure} list->s64vector lst
1289 @deffnx {Scheme Procedure} list->f32vector lst
1290 @deffnx {Scheme Procedure} list->f64vector lst
1291 @deffnx {Scheme Procedure} list->c32vector lst
1292 @deffnx {Scheme Procedure} list->c64vector lst
1293 @deffnx {C Function} scm_list_to_u8vector (lst)
1294 @deffnx {C Function} scm_list_to_s8vector (lst)
1295 @deffnx {C Function} scm_list_to_u16vector (lst)
1296 @deffnx {C Function} scm_list_to_s16vector (lst)
1297 @deffnx {C Function} scm_list_to_u32vector (lst)
1298 @deffnx {C Function} scm_list_to_s32vector (lst)
1299 @deffnx {C Function} scm_list_to_u64vector (lst)
1300 @deffnx {C Function} scm_list_to_s64vector (lst)
1301 @deffnx {C Function} scm_list_to_f32vector (lst)
1302 @deffnx {C Function} scm_list_to_f64vector (lst)
1303 @deffnx {C Function} scm_list_to_c32vector (lst)
1304 @deffnx {C Function} scm_list_to_c64vector (lst)
1305 Return a newly allocated homogeneous numeric vector of the indicated type,
1306 initialized with the elements of the list @var{lst}.
1309 @deffn {Scheme Procedure} any->u8vector obj
1310 @deffnx {Scheme Procedure} any->s8vector obj
1311 @deffnx {Scheme Procedure} any->u16vector obj
1312 @deffnx {Scheme Procedure} any->s16vector obj
1313 @deffnx {Scheme Procedure} any->u32vector obj
1314 @deffnx {Scheme Procedure} any->s32vector obj
1315 @deffnx {Scheme Procedure} any->u64vector obj
1316 @deffnx {Scheme Procedure} any->s64vector obj
1317 @deffnx {Scheme Procedure} any->f32vector obj
1318 @deffnx {Scheme Procedure} any->f64vector obj
1319 @deffnx {Scheme Procedure} any->c32vector obj
1320 @deffnx {Scheme Procedure} any->c64vector obj
1321 @deffnx {C Function} scm_any_to_u8vector (obj)
1322 @deffnx {C Function} scm_any_to_s8vector (obj)
1323 @deffnx {C Function} scm_any_to_u16vector (obj)
1324 @deffnx {C Function} scm_any_to_s16vector (obj)
1325 @deffnx {C Function} scm_any_to_u32vector (obj)
1326 @deffnx {C Function} scm_any_to_s32vector (obj)
1327 @deffnx {C Function} scm_any_to_u64vector (obj)
1328 @deffnx {C Function} scm_any_to_s64vector (obj)
1329 @deffnx {C Function} scm_any_to_f32vector (obj)
1330 @deffnx {C Function} scm_any_to_f64vector (obj)
1331 @deffnx {C Function} scm_any_to_c32vector (obj)
1332 @deffnx {C Function} scm_any_to_c64vector (obj)
1333 Return a (maybe newly allocated) uniform numeric vector of the indicated
1334 type, initialized with the elements of @var{obj}, which must be a list,
1335 a vector, or a uniform vector. When @var{obj} is already a suitable
1336 uniform numeric vector, it is returned unchanged.
1339 @deftypefn {C Function} int scm_is_uniform_vector (SCM uvec)
1340 Return non-zero when @var{uvec} is a uniform numeric vector, zero
1344 @deftypefn {C Function} SCM scm_take_u8vector (const scm_t_uint8 *data, size_t len)
1345 @deftypefnx {C Function} SCM scm_take_s8vector (const scm_t_int8 *data, size_t len)
1346 @deftypefnx {C Function} SCM scm_take_u16vector (const scm_t_uint16 *data, size_t len)
1347 @deftypefnx {C Function} SCM scm_take_s168vector (const scm_t_int16 *data, size_t len)
1348 @deftypefnx {C Function} SCM scm_take_u32vector (const scm_t_uint32 *data, size_t len)
1349 @deftypefnx {C Function} SCM scm_take_s328vector (const scm_t_int32 *data, size_t len)
1350 @deftypefnx {C Function} SCM scm_take_u64vector (const scm_t_uint64 *data, size_t len)
1351 @deftypefnx {C Function} SCM scm_take_s64vector (const scm_t_int64 *data, size_t len)
1352 @deftypefnx {C Function} SCM scm_take_f32vector (const float *data, size_t len)
1353 @deftypefnx {C Function} SCM scm_take_f64vector (const double *data, size_t len)
1354 @deftypefnx {C Function} SCM scm_take_c32vector (const float *data, size_t len)
1355 @deftypefnx {C Function} SCM scm_take_c64vector (const double *data, size_t len)
1356 Return a new uniform numeric vector of the indicated type and length
1357 that uses the memory pointed to by @var{data} to store its elements.
1358 This memory will eventually be freed with @code{free}. The argument
1359 @var{len} specifies the number of elements in @var{data}, not its size
1362 The @code{c32} and @code{c64} variants take a pointer to a C array of
1363 @code{float}s or @code{double}s. The real parts of the complex numbers
1364 are at even indices in that array, the corresponding imaginary parts are
1365 at the following odd index.
1368 @deftypefn {C Function} size_t scm_c_uniform_vector_length (SCM uvec)
1369 Return the number of elements of @var{uvec} as a @code{size_t}.
1372 @deftypefn {C Function} {const void *} scm_uniform_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1373 @deftypefnx {C Function} {const scm_t_uint8 *} scm_u8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1374 @deftypefnx {C Function} {const scm_t_int8 *} scm_s8vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1375 @deftypefnx {C Function} {const scm_t_uint16 *} scm_u16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1376 @deftypefnx {C Function} {const scm_t_int16 *} scm_s16vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1377 @deftypefnx {C Function} {const scm_t_uint32 *} scm_u32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1378 @deftypefnx {C Function} {const scm_t_int32 *} scm_s32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1379 @deftypefnx {C Function} {const scm_t_uint64 *} scm_u64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1380 @deftypefnx {C Function} {const scm_t_int64 *} scm_s64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1381 @deftypefnx {C Function} {const float *} scm_f23vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1382 @deftypefnx {C Function} {const double *} scm_f64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1383 @deftypefnx {C Function} {const float *} scm_c32vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1384 @deftypefnx {C Function} {const double *} scm_c64vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1385 Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but
1386 returns a pointer to the elements of a uniform numeric vector of the
1390 @deftypefn {C Function} {void *} scm_uniform_vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1391 @deftypefnx {C Function} {scm_t_uint8 *} scm_u8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1392 @deftypefnx {C Function} {scm_t_int8 *} scm_s8vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1393 @deftypefnx {C Function} {scm_t_uint16 *} scm_u16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1394 @deftypefnx {C Function} {scm_t_int16 *} scm_s16vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1395 @deftypefnx {C Function} {scm_t_uint32 *} scm_u32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1396 @deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1397 @deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1398 @deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1399 @deftypefnx {C Function} {float *} scm_f23vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1400 @deftypefnx {C Function} {double *} scm_f64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1401 @deftypefnx {C Function} {float *} scm_c32vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1402 @deftypefnx {C Function} {double *} scm_c64vector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)
1403 Like @code{scm_vector_writable_elements} (@pxref{Vector Accessing from
1404 C}), but returns a pointer to the elements of a uniform numeric vector
1405 of the indicated kind.
1408 @deffn {Scheme Procedure} uniform-vector-read! uvec [port_or_fd [start [end]]]
1409 @deffnx {C Function} scm_uniform_vector_read_x (uvec, port_or_fd, start, end)
1410 Fill the elements of @var{uvec} by reading
1411 raw bytes from @var{port-or-fdes}, using host byte order.
1413 The optional arguments @var{start} (inclusive) and @var{end}
1414 (exclusive) allow a specified region to be read,
1415 leaving the remainder of the vector unchanged.
1417 When @var{port-or-fdes} is a port, all specified elements
1418 of @var{uvec} are attempted to be read, potentially blocking
1419 while waiting formore input or end-of-file.
1420 When @var{port-or-fd} is an integer, a single call to
1423 An error is signalled when the last element has only
1424 been partially filled before reaching end-of-file or in
1425 the single call to read(2).
1427 @code{uniform-vector-read!} returns the number of elements
1430 @var{port-or-fdes} may be omitted, in which case it defaults
1431 to the value returned by @code{(current-input-port)}.
1434 @deffn {Scheme Procedure} uniform-vector-write uvec [port_or_fd [start [end]]]
1435 @deffnx {C Function} scm_uniform_vector_write (uvec, port_or_fd, start, end)
1436 Write the elements of @var{uvec} as raw bytes to
1437 @var{port-or-fdes}, in the host byte order.
1439 The optional arguments @var{start} (inclusive)
1440 and @var{end} (exclusive) allow
1441 a specified region to be written.
1443 When @var{port-or-fdes} is a port, all specified elements
1444 of @var{uvec} are attempted to be written, potentially blocking
1445 while waiting for more room.
1446 When @var{port-or-fd} is an integer, a single call to
1449 An error is signalled when the last element has only
1450 been partially written in the single call to write(2).
1452 The number of objects actually written is returned.
1453 @var{port-or-fdes} may be
1454 omitted, in which case it defaults to the value returned by
1455 @code{(current-output-port)}.
1460 @subsection Bit Vectors
1463 Bit vectors are zero-origin, one-dimensional arrays of booleans. They
1464 are displayed as a sequence of @code{0}s and @code{1}s prefixed by
1468 (make-bitvector 8 #f) @result{}
1472 Bit vectors are are also generalized vectors, @xref{Generalized
1473 Vectors}, and can thus be used with the array procedures, @xref{Arrays}.
1474 Bit vectors are the special case of one dimensional bit arrays.
1476 @deffn {Scheme Procedure} bitvector? obj
1477 @deffnx {C Function} scm_bitvector_p (obj)
1478 Return @code{#t} when @var{obj} is a bitvector, else
1482 @deftypefn {C Function} int scm_is_bitvector (SCM obj)
1483 Return @code{1} when @var{obj} is a bitvector, else return @code{0}.
1486 @deffn {Scheme Procedure} make-bitvector len [fill]
1487 @deffnx {C Function} scm_make_bitvector (len, fill)
1488 Create a new bitvector of length @var{len} and
1489 optionally initialize all elements to @var{fill}.
1492 @deftypefn {C Function} SCM scm_c_make_bitvector (size_t len, SCM fill)
1493 Like @code{scm_make_bitvector}, but the length is given as a
1497 @deffn {Scheme Procedure} bitvector . bits
1498 @deffnx {C Function} scm_bitvector (bits)
1499 Create a new bitvector with the arguments as elements.
1502 @deffn {Scheme Procedure} bitvector-length vec
1503 @deffnx {C Function} scm_bitvector_length (vec)
1504 Return the length of the bitvector @var{vec}.
1507 @deftypefn {C Function} size_t scm_c_bitvector_length (SCM vec)
1508 Like @code{scm_bitvector_length}, but the length is returned as a
1512 @deffn {Scheme Procedure} bitvector-ref vec idx
1513 @deffnx {C Function} scm_bitvector_ref (vec, idx)
1514 Return the element at index @var{idx} of the bitvector
1518 @deftypefn {C Function} SCM scm_c_bitvector_ref (SCM obj, size_t idx)
1519 Return the element at index @var{idx} of the bitvector
1523 @deffn {Scheme Procedure} bitvector-set! vec idx val
1524 @deffnx {C Function} scm_bitvector_set_x (vec, idx, val)
1525 Set the element at index @var{idx} of the bitvector
1526 @var{vec} when @var{val} is true, else clear it.
1529 @deftypefn {C Function} SCM scm_c_bitvector_set_x (SCM obj, size_t idx, SCM val)
1530 Set the element at index @var{idx} of the bitvector
1531 @var{vec} when @var{val} is true, else clear it.
1534 @deffn {Scheme Procedure} bitvector-fill! vec val
1535 @deffnx {C Function} scm_bitvector_fill_x (vec, val)
1536 Set all elements of the bitvector
1537 @var{vec} when @var{val} is true, else clear them.
1540 @deffn {Scheme Procedure} list->bitvector list
1541 @deffnx {C Function} scm_list_to_bitvector (list)
1542 Return a new bitvector initialized with the elements
1546 @deffn {Scheme Procedure} bitvector->list vec
1547 @deffnx {C Function} scm_bitvector_to_list (vec)
1548 Return a new list initialized with the elements
1549 of the bitvector @var{vec}.
1552 @deffn {Scheme Procedure} bit-count bool bitvector
1553 @deffnx {C Function} scm_bit_count (bool, bitvector)
1554 Return a count of how many entries in @var{bitvector} are equal to
1555 @var{bool}. For example,
1558 (bit-count #f #*000111000) @result{} 6
1562 @deffn {Scheme Procedure} bit-position bool bitvector start
1563 @deffnx {C Function} scm_bit_position (bool, bitvector, start)
1564 Return the index of the first occurrance of @var{bool} in
1565 @var{bitvector}, starting from @var{start}. If there is no @var{bool}
1566 entry between @var{start} and the end of @var{bitvector}, then return
1567 @code{#f}. For example,
1570 (bit-position #t #*000101 0) @result{} 3
1571 (bit-position #f #*0001111 3) @result{} #f
1575 @deffn {Scheme Procedure} bit-invert! bitvector
1576 @deffnx {C Function} scm_bit_invert_x (bitvector)
1577 Modify @var{bitvector} by replacing each element with its negation.
1580 @deffn {Scheme Procedure} bit-set*! bitvector uvec bool
1581 @deffnx {C Function} scm_bit_set_star_x (bitvector, uvec, bool)
1582 Set entries of @var{bitvector} to @var{bool}, with @var{uvec}
1583 selecting the entries to change. The return value is unspecified.
1585 If @var{uvec} is a bit vector, then those entries where it has
1586 @code{#t} are the ones in @var{bitvector} which are set to @var{bool}.
1587 @var{uvec} and @var{bitvector} must be the same length. When
1588 @var{bool} is @code{#t} it's like @var{uvec} is OR'ed into
1589 @var{bitvector}. Or when @var{bool} is @code{#f} it can be seen as an
1593 (define bv #*01000010)
1594 (bit-set*! bv #*10010001 #t)
1596 @result{} #*11010011
1599 If @var{uvec} is a uniform vector of unsigned long integers, then
1600 they're indexes into @var{bitvector} which are set to @var{bool}.
1603 (define bv #*01000010)
1604 (bit-set*! bv #u(5 2 7) #t)
1606 @result{} #*01100111
1610 @deffn {Scheme Procedure} bit-count* bitvector uvec bool
1611 @deffnx {C Function} scm_bit_count_star (bitvector, uvec, bool)
1612 Return a count of how many entries in @var{bitvector} are equal to
1613 @var{bool}, with @var{uvec} selecting the entries to consider.
1615 @var{uvec} is interpreted in the same way as for @code{bit-set*!}
1616 above. Namely, if @var{uvec} is a bit vector then entries which have
1617 @code{#t} there are considered in @var{bitvector}. Or if @var{uvec}
1618 is a uniform vector of unsigned long integers then it's the indexes in
1619 @var{bitvector} to consider.
1624 (bit-count* #*01110111 #*11001101 #t) @result{} 3
1625 (bit-count* #*01110111 #u(7 0 4) #f) @result{} 2
1629 @deftypefn {C Function} {const scm_t_uint32 *} scm_bitvector_elements (SCM vec, scm_t_array_handle *handle, size_t *offp, size_t *lenp, ssize_t *incp)
1630 Like @code{scm_vector_elements} (@pxref{Vector Accessing from C}), but
1631 for bitvectors. The variable pointed to by @var{offp} is set to the
1632 value returned by @code{scm_array_handle_bit_elements_offset}. See
1633 @code{scm_array_handle_bit_elements} for how to use the returned
1634 pointer and the offset.
1637 @deftypefn {C Function} {scm_t_uint32 *} scm_bitvector_writable_elements (SCM vec, scm_t_array_handle *handle, size_t *offp, size_t *lenp, ssize_t *incp)
1638 Like @code{scm_bitvector_elements}, but the pointer is good for reading
1642 @node Generalized Vectors
1643 @subsection Generalized Vectors
1645 Guile has a number of data types that are generally vector-like:
1646 strings, uniform numeric vectors, bitvectors, and of course ordinary
1647 vectors of arbitrary Scheme values. These types are disjoint: a
1648 Scheme value belongs to at most one of the four types listed above.
1650 If you want to gloss over this distinction and want to treat all four
1651 types with common code, you can use the procedures in this section.
1652 They work with the @emph{generalized vector} type, which is the union
1653 of the four vector-like types.
1655 @deffn {Scheme Procedure} generalized-vector? obj
1656 @deffnx {C Function} scm_generalized_vector_p (obj)
1657 Return @code{#t} if @var{obj} is a vector, string,
1658 bitvector, or uniform numeric vector.
1661 @deffn {Scheme Procedure} generalized-vector-length v
1662 @deffnx {C Function} scm_generalized_vector_length (v)
1663 Return the length of the generalized vector @var{v}.
1666 @deffn {Scheme Procedure} generalized-vector-ref v idx
1667 @deffnx {C Function} scm_generalized_vector_ref (v, idx)
1668 Return the element at index @var{idx} of the
1669 generalized vector @var{v}.
1672 @deffn {Scheme Procedure} generalized-vector-set! v idx val
1673 @deffnx {C Function} scm_generalized_vector_set_x (v, idx, val)
1674 Set the element at index @var{idx} of the
1675 generalized vector @var{v} to @var{val}.
1678 @deffn {Scheme Procedure} generalized-vector->list v
1679 @deffnx {C Function} scm_generalized_vector_to_list (v)
1680 Return a new list whose elements are the elements of the
1681 generalized vector @var{v}.
1684 @deftypefn {C Function} int scm_is_generalized_vector (SCM obj)
1685 Return @code{1} if @var{obj} is a vector, string,
1686 bitvector, or uniform numeric vector; else return @code{0}.
1689 @deftypefn {C Function} size_t scm_c_generalized_vector_length (SCM v)
1690 Return the length of the generalized vector @var{v}.
1693 @deftypefn {C Function} SCM scm_c_generalized_vector_ref (SCM v, size_t idx)
1694 Return the element at index @var{idx} of the generalized vector @var{v}.
1697 @deftypefn {C Function} void scm_c_generalized_vector_set_x (SCM v, size_t idx, SCM val)
1698 Set the element at index @var{idx} of the generalized vector @var{v}
1702 @deftypefn {C Function} void scm_generalized_vector_get_handle (SCM v, scm_t_array_handle *handle)
1703 Like @code{scm_array_get_handle} but an error is signalled when @var{v}
1704 is not of rank one. You can use @code{scm_array_handle_ref} and
1705 @code{scm_array_handle_set} to read and write the elements of @var{v},
1706 or you can use functions like @code{scm_array_handle_<foo>_elements} to
1707 deal with specific types of vectors.
1714 @dfn{Arrays} are a collection of cells organized into an arbitrary
1715 number of dimensions. Each cell can be accessed in constant time by
1716 supplying an index for each dimension.
1718 In the current implementation, an array uses a generalized vector for
1719 the actual storage of its elements. Any kind of generalized vector
1720 will do, so you can have arrays of uniform numeric values, arrays of
1721 characters, arrays of bits, and of course, arrays of arbitrary Scheme
1722 values. For example, arrays with an underlying @code{c64vector} might
1723 be nice for digital signal processing, while arrays made from a
1724 @code{u8vector} might be used to hold gray-scale images.
1726 The number of dimensions of an array is called its @dfn{rank}. Thus,
1727 a matrix is an array of rank 2, while a vector has rank 1. When
1728 accessing an array element, you have to specify one exact integer for
1729 each dimension. These integers are called the @dfn{indices} of the
1730 element. An array specifies the allowed range of indices for each
1731 dimension via an inclusive lower and upper bound. These bounds can
1732 well be negative, but the upper bound must be greater than or equal to
1733 the lower bound minus one. When all lower bounds of an array are
1734 zero, it is called a @dfn{zero-origin} array.
1736 Arrays can be of rank 0, which could be interpreted as a scalar.
1737 Thus, a zero-rank array can store exactly one object and the list of
1738 indices of this element is the empty list.
1740 Arrays contain zero elements when one of their dimensions has a zero
1741 length. These empty arrays maintain information about their shape: a
1742 matrix with zero columns and 3 rows is different from a matrix with 3
1743 columns and zero rows, which again is different from a vector of
1746 Generalized vectors, such as strings, uniform numeric vectors, bit
1747 vectors and ordinary vectors, are the special case of one dimensional
1752 * Array Procedures::
1754 * Accessing Arrays from C::
1758 @subsubsection Array Syntax
1760 An array is displayed as @code{#} followed by its rank, followed by a
1761 tag that describes the underlying vector, optionally followed by
1762 information about its shape, and finally followed by the cells,
1763 organized into dimensions using parentheses.
1765 In more words, the array tag is of the form
1768 #<rank><vectag><@@lower><:len><@@lower><:len>...
1771 where @code{<rank>} is a positive integer in decimal giving the rank of
1772 the array. It is omitted when the rank is 1 and the array is non-shared
1773 and has zero-origin (see below). For shared arrays and for a non-zero
1774 origin, the rank is always printed even when it is 1 to dinstinguish
1775 them from ordinary vectors.
1777 The @code{<vectag>} part is the tag for a uniform numeric vector, like
1778 @code{u8}, @code{s16}, etc, @code{b} for bitvectors, or @code{a} for
1779 strings. It is empty for ordinary vectors.
1781 The @code{<@@lower>} part is a @samp{@@} character followed by a signed
1782 integer in decimal giving the lower bound of a dimension. There is one
1783 @code{<@@lower>} for each dimension. When all lower bounds are zero,
1784 all @code{<@@lower>} parts are omitted.
1786 The @code{<:len>} part is a @samp{:} character followed by an unsigned
1787 integer in decimal giving the length of a dimension. Like for the lower
1788 bounds, there is one @code{<:len>} for each dimension, and the
1789 @code{<:len>} part always follows the @code{<@@lower>} part for a
1790 dimension. Lengths are only then printed when they can't be deduced
1791 from the nested lists of elements of the array literal, which can happen
1792 when at least one length is zero.
1794 As a special case, an array of rank 0 is printed as
1795 @code{#0<vectag>(<scalar>)}, where @code{<scalar>} is the result of
1796 printing the single element of the array.
1802 is an ordinary array of rank 1 with lower bound 0 in dimension 0.
1803 (I.e., a regular vector.)
1806 is an ordinary array of rank 1 with lower bound 2 in dimension 0.
1808 @item #2((1 2 3) (4 5 6))
1809 is a non-uniform array of rank 2; a 3@cross{}3 matrix with index ranges 0..2
1813 is a uniform u8 array of rank 1.
1815 @item #2u32@@2@@3((1 2) (2 3))
1816 is a uniform u8 array of rank 2 with index ranges 2..3 and 3..4.
1819 is a two-dimensional array with index ranges 0..-1 and 0..-1, i.e. both
1820 dimensions have length zero.
1823 is a two-dimensional array with index ranges 0..-1 and 0..1, i.e. the
1824 first dimension has length zero, but the second has length 2.
1827 is a rank-zero array with contents 12.
1831 @node Array Procedures
1832 @subsubsection Array Procedures
1834 When an array is created, the range of each dimension must be
1835 specified, e.g., to create a 2@cross{}3 array with a zero-based index:
1838 (make-array 'ho 2 3) @result{} #2((ho ho ho) (ho ho ho))
1841 The range of each dimension can also be given explicitly, e.g., another
1842 way to create the same array:
1845 (make-array 'ho '(0 1) '(0 2)) @result{} #2((ho ho ho) (ho ho ho))
1848 The following procedures can be used with arrays (or vectors). An
1849 argument shown as @var{idx}@dots{} means one parameter for each
1850 dimension in the array. A @var{idxlist} argument means a list of such
1851 values, one for each dimension.
1854 @deffn {Scheme Procedure} array? obj
1855 @deffnx {C Function} scm_array_p (obj, unused)
1856 Return @code{#t} if the @var{obj} is an array, and @code{#f} if
1859 The second argument to scm_array_p is there for historical reasons,
1860 but it is not used. You should always pass @code{SCM_UNDEFINED} as
1864 @deffn {Scheme Procedure} typed-array? obj type
1865 @deffnx {C Function} scm_typed_array_p (obj, type)
1866 Return @code{#t} if the @var{obj} is an array of type @var{type}, and
1870 @deftypefn {C Function} int scm_is_array (SCM obj)
1871 Return @code{1} if the @var{obj} is an array and @code{0} if not.
1874 @deftypefn {C Function} int scm_is_typed_array (SCM obj, SCM type)
1875 Return @code{0} if the @var{obj} is an array of type @var{type}, and
1879 @deffn {Scheme Procedure} make-array fill bound @dots{}
1880 @deffnx {C Function} scm_make_array (fill, bounds)
1881 Equivalent to @code{(make-typed-array #t @var{fill} @var{bound} ...)}.
1884 @deffn {Scheme Procedure} make-typed-array type fill bound @dots{}
1885 @deffnx {C Function} scm_make_typed_array (type, fill, bounds)
1886 Create and return an array that has as many dimensions as there are
1887 @var{bound}s and (maybe) fill it with @var{fill}.
1889 The underlaying storage vector is created according to @var{type},
1890 which must be a symbol whose name is the `vectag' of the array as
1891 explained above, or @code{#t} for ordinary, non-specialized arrays.
1893 For example, using the symbol @code{f64} for @var{type} will create an
1894 array that uses a @code{f64vector} for storing its elements, and
1895 @code{a} will use a string.
1897 When @var{fill} is not the special @emph{unspecified} value, the new
1898 array is filled with @var{fill}. Otherwise, the initial contents of
1899 the array is unspecified. The special @emph{unspecified} value is
1900 stored in the variable @code{*unspecified*} so that for example
1901 @code{(make-typed-array 'u32 *unspecified* 4)} creates a uninitialized
1902 @code{u32} vector of length 4.
1904 Each @var{bound} may be a positive non-zero integer @var{N}, in which
1905 case the index for that dimension can range from 0 through @var{N-1}; or
1906 an explicit index range specifier in the form @code{(LOWER UPPER)},
1907 where both @var{lower} and @var{upper} are integers, possibly less than
1908 zero, and possibly the same number (however, @var{lower} cannot be
1909 greater than @var{upper}).
1912 @deffn {Scheme Procedure} list->array dimspec list
1913 Equivalent to @code{(list->typed-array #t @var{dimspec}
1917 @deffn {Scheme Procedure} list->typed-array type dimspec list
1918 @deffnx {C Function} scm_list_to_typed_array (type, dimspec, list)
1919 Return an array of the type indicated by @var{type} with elements the
1920 same as those of @var{list}.
1922 The argument @var{dimspec} determines the number of dimensions of the
1923 array and their lower bounds. When @var{dimspec} is an exact integer,
1924 it gives the number of dimensions directly and all lower bounds are
1925 zero. When it is a list of exact integers, then each element is the
1926 lower index bound of a dimension, and there will be as many dimensions
1927 as elements in the list.
1930 @deffn {Scheme Procedure} array-type array
1931 Return the type of @var{array}. This is the `vectag' used for
1932 printing @var{array} (or @code{#t} for ordinary arrays) and can be
1933 used with @code{make-typed-array} to create an array of the same kind
1937 @deffn {Scheme Procedure} array-ref array idx @dots{}
1938 Return the element at @code{(idx @dots{})} in @var{array}.
1941 (define a (make-array 999 '(1 2) '(3 4)))
1942 (array-ref a 2 4) @result{} 999
1946 @deffn {Scheme Procedure} array-in-bounds? array idx @dots{}
1947 @deffnx {C Function} scm_array_in_bounds_p (array, idxlist)
1948 Return @code{#t} if the given index would be acceptable to
1952 (define a (make-array #f '(1 2) '(3 4)))
1953 (array-in-bounds? a 2 3) @result{} #t
1954 (array-in-bounds? a 0 0) @result{} #f
1958 @deffn {Scheme Procedure} array-set! array obj idx @dots{}
1959 @deffnx {C Function} scm_array_set_x (array, obj, idxlist)
1960 Set the element at @code{(idx @dots{})} in @var{array} to @var{obj}.
1961 The return value is unspecified.
1964 (define a (make-array #f '(0 1) '(0 1)))
1965 (array-set! a #t 1 1)
1966 a @result{} #2((#f #f) (#f #t))
1970 @deffn {Scheme Procedure} enclose-array array dim1 @dots{}
1971 @deffnx {C Function} scm_enclose_array (array, dimlist)
1972 @var{dim1}, @var{dim2} @dots{} should be nonnegative integers less than
1973 the rank of @var{array}. @code{enclose-array} returns an array
1974 resembling an array of shared arrays. The dimensions of each shared
1975 array are the same as the @var{dim}th dimensions of the original array,
1976 the dimensions of the outer array are the same as those of the original
1977 array that did not match a @var{dim}.
1979 An enclosed array is not a general Scheme array. Its elements may not
1980 be set using @code{array-set!}. Two references to the same element of
1981 an enclosed array will be @code{equal?} but will not in general be
1982 @code{eq?}. The value returned by @code{array-prototype} when given an
1983 enclosed array is unspecified.
1988 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1)
1990 #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>
1992 (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0)
1994 #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
1998 @deffn {Scheme Procedure} array-shape array
1999 @deffnx {Scheme Procedure} array-dimensions array
2000 @deffnx {C Function} scm_array_dimensions (array)
2001 Return a list of the bounds for each dimenson of @var{array}.
2003 @code{array-shape} gives @code{(@var{lower} @var{upper})} for each
2004 dimension. @code{array-dimensions} instead returns just
2005 @math{@var{upper}+1} for dimensions with a 0 lower bound. Both are
2006 suitable as input to @code{make-array}.
2011 (define a (make-array 'foo '(-1 3) 5))
2012 (array-shape a) @result{} ((-1 3) (0 4))
2013 (array-dimensions a) @result{} ((-1 3) 5)
2017 @deffn {Scheme Procedure} array-rank obj
2018 @deffnx {C Function} scm_array_rank (obj)
2019 Return the rank of @var{array}.
2022 @deftypefn {C Function} size_t scm_c_array_rank (SCM array)
2023 Return the rank of @var{array} as a @code{size_t}.
2026 @deffn {Scheme Procedure} array->list array
2027 @deffnx {C Function} scm_array_to_list (array)
2028 Return a list consisting of all the elements, in order, of
2032 @c FIXME: Describe how the order affects the copying (it matters for
2033 @c shared arrays with the same underlying root vector, presumably).
2035 @deffn {Scheme Procedure} array-copy! src dst
2036 @deffnx {Scheme Procedure} array-copy-in-order! src dst
2037 @deffnx {C Function} scm_array_copy_x (src, dst)
2038 Copy every element from vector or array @var{src} to the corresponding
2039 element of @var{dst}. @var{dst} must have the same rank as @var{src},
2040 and be at least as large in each dimension. The return value is
2044 @deffn {Scheme Procedure} array-fill! array fill
2045 @deffnx {C Function} scm_array_fill_x (array, fill)
2046 Store @var{fill} in every element of @var{array}. The value returned
2050 @c begin (texi-doc-string "guile" "array-equal?")
2051 @deffn {Scheme Procedure} array-equal? array1 array2 @dots{}
2052 Return @code{#t} if all arguments are arrays with the same shape, the
2053 same type, and have corresponding elements which are either
2054 @code{equal?} or @code{array-equal?}. This function differs from
2055 @code{equal?} (@pxref{Equality}) in that a one dimensional shared
2056 array may be @code{array-equal?} but not @code{equal?} to a vector or
2060 @c FIXME: array-map! accepts no source arrays at all, and in that
2061 @c case makes calls "(proc)". Is that meant to be a documented
2064 @c FIXME: array-for-each doesn't say what happens if the sources have
2065 @c different index ranges. The code currently iterates over the
2066 @c indices of the first and expects the others to cover those. That
2067 @c at least vaguely matches array-map!, but is is meant to be a
2068 @c documented feature?
2070 @deffn {Scheme Procedure} array-map! dst proc src1 @dots{} srcN
2071 @deffnx {Scheme Procedure} array-map-in-order! dst proc src1 @dots{} srcN
2072 @deffnx {C Function} scm_array_map_x (dst, proc, srclist)
2073 Set each element of the @var{dst} array to values obtained from calls
2074 to @var{proc}. The value returned is unspecified.
2076 Each call is @code{(@var{proc} @var{elem1} @dots{} @var{elemN})},
2077 where each @var{elem} is from the corresponding @var{src} array, at
2078 the @var{dst} index. @code{array-map-in-order!} makes the calls in
2079 row-major order, @code{array-map!} makes them in an unspecified order.
2081 The @var{src} arrays must have the same number of dimensions as
2082 @var{dst}, and must have a range for each dimension which covers the
2083 range in @var{dst}. This ensures all @var{dst} indices are valid in
2087 @deffn {Scheme Procedure} array-for-each proc src1 @dots{} srcN
2088 @deffnx {C Function} scm_array_for_each (proc, src1, srclist)
2089 Apply @var{proc} to each tuple of elements of @var{src1} @dots{}
2090 @var{srcN}, in row-major order. The value returned is unspecified.
2093 @deffn {Scheme Procedure} array-index-map! dst proc
2094 @deffnx {C Function} scm_array_index_map_x (dst, proc)
2095 Set each element of the @var{dst} array to values returned by calls to
2096 @var{proc}. The value returned is unspecified.
2098 Each call is @code{(@var{proc} @var{i1} @dots{} @var{iN})}, where
2099 @var{i1}@dots{}@var{iN} is the destination index, one parameter for
2100 each dimension. The order in which the calls are made is unspecified.
2102 For example, to create a @m{4\times4, 4x4} matrix representing a
2106 \advance\leftskip by 2\lispnarrowing {
2124 (define a (make-array #f 4 4))
2125 (array-index-map! a (lambda (i j)
2126 (modulo (+ i j) 4)))
2130 @deffn {Scheme Procedure} uniform-array-read! ra [port_or_fd [start [end]]]
2131 @deffnx {C Function} scm_uniform_array_read_x (ra, port_or_fd, start, end)
2132 Attempt to read all elements of @var{ura}, in lexicographic order, as
2133 binary objects from @var{port-or-fdes}.
2134 If an end of file is encountered,
2135 the objects up to that point are put into @var{ura}
2136 (starting at the beginning) and the remainder of the array is
2139 The optional arguments @var{start} and @var{end} allow
2140 a specified region of a vector (or linearized array) to be read,
2141 leaving the remainder of the vector unchanged.
2143 @code{uniform-array-read!} returns the number of objects read.
2144 @var{port-or-fdes} may be omitted, in which case it defaults to the value
2145 returned by @code{(current-input-port)}.
2148 @deffn {Scheme Procedure} uniform-array-write v [port_or_fd [start [end]]]
2149 @deffnx {C Function} scm_uniform_array_write (v, port_or_fd, start, end)
2150 Writes all elements of @var{ura} as binary objects to
2153 The optional arguments @var{start}
2155 a specified region of a vector (or linearized array) to be written.
2157 The number of objects actually written is returned.
2158 @var{port-or-fdes} may be
2159 omitted, in which case it defaults to the value returned by
2160 @code{(current-output-port)}.
2164 @subsubsection Shared Arrays
2166 @deffn {Scheme Procedure} make-shared-array oldarray mapfunc bound @dots{}
2167 @deffnx {C Function} scm_make_shared_array (oldarray, mapfunc, boundlist)
2168 Return a new array which shares the storage of @var{oldarray}.
2169 Changes made through either affect the same underlying storage. The
2170 @var{bound@dots{}} arguments are the shape of the new array, the same
2171 as @code{make-array} (@pxref{Array Procedures}).
2173 @var{mapfunc} translates coordinates from the new array to the
2174 @var{oldarray}. It's called as @code{(@var{mapfunc} newidx1 @dots{})}
2175 with one parameter for each dimension of the new array, and should
2176 return a list of indices for @var{oldarray}, one for each dimension of
2179 @var{mapfunc} must be affine linear, meaning that each @var{oldarray}
2180 index must be formed by adding integer multiples (possibly negative)
2181 of some or all of @var{newidx1} etc, plus a possible integer offset.
2182 The multiples and offset must be the same in each call.
2185 One good use for a shared array is to restrict the range of some
2186 dimensions, so as to apply say @code{array-for-each} or
2187 @code{array-fill!} to only part of an array. The plain @code{list}
2188 function can be used for @var{mapfunc} in this case, making no changes
2189 to the index values. For example,
2192 (make-shared-array #2((a b c) (d e f) (g h i)) list 3 2)
2193 @result{} #2((a b) (d e) (g h))
2196 The new array can have fewer dimensions than @var{oldarray}, for
2197 example to take a column from an array.
2200 (make-shared-array #2((a b c) (d e f) (g h i))
2201 (lambda (i) (list i 2))
2206 A diagonal can be taken by using the single new array index for both
2207 row and column in the old array. For example,
2210 (make-shared-array #2((a b c) (d e f) (g h i))
2211 (lambda (i) (list i i))
2216 Dimensions can be increased by for instance considering portions of a
2217 one dimensional array as rows in a two dimensional array.
2218 (@code{array-contents} below can do the opposite, flattening an
2222 (make-shared-array #1(a b c d e f g h i j k l)
2223 (lambda (i j) (list (+ (* i 3) j)))
2225 @result{} #2((a b c) (d e f) (g h i) (j k l))
2228 By negating an index the order that elements appear can be reversed.
2229 The following just reverses the column order,
2232 (make-shared-array #2((a b c) (d e f) (g h i))
2233 (lambda (i j) (list i (- 2 j)))
2235 @result{} #2((c b a) (f e d) (i h g))
2238 A fixed offset on indexes allows for instance a change from a 0 based
2242 (define x #2((a b c) (d e f) (g h i)))
2243 (define y (make-shared-array x
2244 (lambda (i j) (list (1- i) (1- j)))
2246 (array-ref x 0 0) @result{} a
2247 (array-ref y 1 1) @result{} a
2250 A multiple on an index allows every Nth element of an array to be
2251 taken. The following is every third element,
2254 (make-shared-array #1(a b c d e f g h i j k l)
2255 (lambda (i) (list (* i 3)))
2257 @result{} #1(a d g j)
2260 The above examples can be combined to make weird and wonderful
2261 selections from an array, but it's important to note that because
2262 @var{mapfunc} must be affine linear, arbitrary permutations are not
2265 In the current implementation, @var{mapfunc} is not called for every
2266 access to the new array but only on some sample points to establish a
2267 base and stride for new array indices in @var{oldarray} data. A few
2268 sample points are enough because @var{mapfunc} is linear.
2271 @deffn {Scheme Procedure} shared-array-increments array
2272 @deffnx {C Function} scm_shared_array_increments (array)
2273 For each dimension, return the distance between elements in the root vector.
2276 @deffn {Scheme Procedure} shared-array-offset array
2277 @deffnx {C Function} scm_shared_array_offset (array)
2278 Return the root vector index of the first element in the array.
2281 @deffn {Scheme Procedure} shared-array-root array
2282 @deffnx {C Function} scm_shared_array_root (array)
2283 Return the root vector of a shared array.
2286 @deffn {Scheme Procedure} array-contents array [strict]
2287 @deffnx {C Function} scm_array_contents (array, strict)
2288 If @var{array} may be @dfn{unrolled} into a one dimensional shared array
2289 without changing their order (last subscript changing fastest), then
2290 @code{array-contents} returns that shared array, otherwise it returns
2291 @code{#f}. All arrays made by @code{make-array} and
2292 @code{make-typed-array} may be unrolled, some arrays made by
2293 @code{make-shared-array} may not be.
2295 If the optional argument @var{strict} is provided, a shared array will
2296 be returned only if its elements are stored internally contiguous in
2300 @deffn {Scheme Procedure} transpose-array array dim1 @dots{}
2301 @deffnx {C Function} scm_transpose_array (array, dimlist)
2302 Return an array sharing contents with @var{array}, but with
2303 dimensions arranged in a different order. There must be one
2304 @var{dim} argument for each dimension of @var{array}.
2305 @var{dim1}, @var{dim2}, @dots{} should be integers between 0
2306 and the rank of the array to be returned. Each integer in that
2307 range must appear at least once in the argument list.
2309 The values of @var{dim1}, @var{dim2}, @dots{} correspond to
2310 dimensions in the array to be returned, and their positions in the
2311 argument list to dimensions of @var{array}. Several @var{dim}s
2312 may have the same value, in which case the returned array will
2313 have smaller rank than @var{array}.
2316 (transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
2317 (transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
2318 (transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
2319 #2((a 4) (b 5) (c 6))
2323 @node Accessing Arrays from C
2324 @subsubsection Accessing Arrays from C
2326 Arrays, especially uniform numeric arrays, are useful to efficiently
2327 represent large amounts of rectangularily organized information, such as
2328 matrices, images, or generally blobs of binary data. It is desirable to
2329 access these blobs in a C like manner so that they can be handed to
2330 external C code such as linear algebra libraries or image processing
2333 While pointers to the elements of an array are in use, the array itself
2334 must be protected so that the pointer remains valid. Such a protected
2335 array is said to be @dfn{reserved}. A reserved array can be read but
2336 modifications to it that would cause the pointer to its elements to
2337 become invalid are prevented. When you attempt such a modification, an
2340 (This is similar to locking the array while it is in use, but without
2341 the danger of a deadlock. In a multi-threaded program, you will need
2342 additional synchronization to avoid modifying reserved arrays.)
2344 You must take care to always unreserve an array after reserving it,
2345 also in the presence of non-local exits. To simplify this, reserving
2346 and unreserving work like a dynwind context (@pxref{Dynamic Wind}): a
2347 call to @code{scm_array_get_handle} can be thought of as beginning a
2348 dynwind context and @code{scm_array_handle_release} as ending it.
2349 When a non-local exit happens between these two calls, the array is
2350 implicitely unreserved.
2352 That is, you need to properly pair reserving and unreserving in your
2353 code, but you don't need to worry about non-local exits.
2355 These calls and other pairs of calls that establish dynwind contexts
2356 need to be properly nested. If you begin a context prior to reserving
2357 an array, you need to unreserve the array before ending the context.
2358 Likewise, when reserving two or more arrays in a certain order, you
2359 need to unreserve them in the opposite order.
2361 Once you have reserved an array and have retrieved the pointer to its
2362 elements, you must figure out the layout of the elements in memory.
2363 Guile allows slices to be taken out of arrays without actually making a
2364 copy, such as making an alias for the diagonal of a matrix that can be
2365 treated as a vector. Arrays that result from such an operation are not
2366 stored contiguously in memory and when working with their elements
2367 directly, you need to take this into account.
2369 The layout of array elements in memory can be defined via a
2370 @emph{mapping function} that computes a scalar position from a vector of
2371 indices. The scalar position then is the offset of the element with the
2372 given indices from the start of the storage block of the array.
2374 In Guile, this mapping function is restricted to be @dfn{affine}: all
2375 mapping functions of Guile arrays can be written as @code{p = b +
2376 c[0]*i[0] + c[1]*i[1] + ... + c[n-1]*i[n-1]} where @code{i[k]} is the
2377 @nicode{k}th index and @code{n} is the rank of the array. For
2378 example, a matrix of size 3x3 would have @code{b == 0}, @code{c[0] ==
2379 3} and @code{c[1] == 1}. When you transpose this matrix (with
2380 @code{transpose-array}, say), you will get an array whose mapping
2381 function has @code{b == 0}, @code{c[0] == 1} and @code{c[1] == 3}.
2383 The function @code{scm_array_handle_dims} gives you (indirect) access to
2384 the coefficients @code{c[k]}.
2387 Note that there are no functions for accessing the elements of a
2388 character array yet. Once the string implementation of Guile has been
2389 changed to use Unicode, we will provide them.
2391 @deftp {C Type} scm_t_array_handle
2392 This is a structure type that holds all information necessary to manage
2393 the reservation of arrays as explained above. Structures of this type
2394 must be allocated on the stack and must only be accessed by the
2395 functions listed below.
2398 @deftypefn {C Function} void scm_array_get_handle (SCM array, scm_t_array_handle *handle)
2399 Reserve @var{array}, which must be an array, and prepare @var{handle} to
2400 be used with the functions below. You must eventually call
2401 @code{scm_array_handle_release} on @var{handle}, and do this in a
2402 properly nested fashion, as explained above. The structure pointed to
2403 by @var{handle} does not need to be initialized before calling this
2407 @deftypefn {C Function} void scm_array_handle_release (scm_t_array_handle *handle)
2408 End the array reservation represented by @var{handle}. After a call to
2409 this function, @var{handle} might be used for another reservation.
2412 @deftypefn {C Function} size_t scm_array_handle_rank (scm_t_array_handle *handle)
2413 Return the rank of the array represented by @var{handle}.
2416 @deftp {C Type} scm_t_array_dim
2417 This structure type holds information about the layout of one dimension
2418 of an array. It includes the following fields:
2423 The lower and upper bounds (both inclusive) of the permissible index
2424 range for the given dimension. Both values can be negative, but
2425 @var{lbnd} is always less than or equal to @var{ubnd}.
2428 The distance from one element of this dimension to the next. Note, too,
2429 that this can be negative.
2433 @deftypefn {C Function} {const scm_t_array_dim *} scm_array_handle_dims (scm_t_array_handle *handle)
2434 Return a pointer to a C vector of information about the dimensions of
2435 the array represented by @var{handle}. This pointer is valid as long as
2436 the array remains reserved. As explained above, the
2437 @code{scm_t_array_dim} structures returned by this function can be used
2438 calculate the position of an element in the storage block of the array
2441 This position can then be used as an index into the C array pointer
2442 returned by the various @code{scm_array_handle_<foo>_elements}
2443 functions, or with @code{scm_array_handle_ref} and
2444 @code{scm_array_handle_set}.
2446 Here is how one can compute the position @var{pos} of an element given
2447 its indices in the vector @var{indices}:
2450 ssize_t indices[RANK];
2451 scm_t_array_dim *dims;
2456 for (i = 0; i < RANK; i++)
2458 if (indices[i] < dims[i].lbnd || indices[i] > dims[i].ubnd)
2460 pos += (indices[i] - dims[i].lbnd) * dims[i].inc;
2465 @deftypefn {C Function} ssize_t scm_array_handle_pos (scm_t_array_handle *handle, SCM indices)
2466 Compute the position corresponding to @var{indices}, a list of
2467 indices. The position is computed as described above for
2468 @code{scm_array_handle_dims}. The number of the indices and their
2469 range is checked and an approrpiate error is signalled for invalid
2473 @deftypefn {C Function} SCM scm_array_handle_ref (scm_t_array_handle *handle, ssize_t pos)
2474 Return the element at position @var{pos} in the storage block of the
2475 array represented by @var{handle}. Any kind of array is acceptable. No
2476 range checking is done on @var{pos}.
2479 @deftypefn {C Function} void scm_array_handle_set (scm_t_array_handle *handle, ssize_t pos, SCM val)
2480 Set the element at position @var{pos} in the storage block of the array
2481 represented by @var{handle} to @var{val}. Any kind of array is
2482 acceptable. No range checking is done on @var{pos}. An error is
2483 signalled when the array can not store @var{val}.
2486 @deftypefn {C Function} {const SCM *} scm_array_handle_elements (scm_t_array_handle *handle)
2487 Return a pointer to the elements of a ordinary array of general Scheme
2488 values (i.e., a non-uniform array) for reading. This pointer is valid
2489 as long as the array remains reserved.
2492 @deftypefn {C Function} {SCM *} scm_array_handle_writable_elements (scm_t_array_handle *handle)
2493 Like @code{scm_array_handle_elements}, but the pointer is good for
2494 reading and writing.
2497 @deftypefn {C Function} {const void *} scm_array_handle_uniform_elements (scm_t_array_handle *handle)
2498 Return a pointer to the elements of a uniform numeric array for reading.
2499 This pointer is valid as long as the array remains reserved. The size
2500 of each element is given by @code{scm_array_handle_uniform_element_size}.
2503 @deftypefn {C Function} {void *} scm_array_handle_uniform_writable_elements (scm_t_array_handle *handle)
2504 Like @code{scm_array_handle_uniform_elements}, but the pointer is good
2505 reading and writing.
2508 @deftypefn {C Function} size_t scm_array_handle_uniform_element_size (scm_t_array_handle *handle)
2509 Return the size of one element of the uniform numeric array represented
2513 @deftypefn {C Function} {const scm_t_uint8 *} scm_array_handle_u8_elements (scm_t_array_handle *handle)
2514 @deftypefnx {C Function} {const scm_t_int8 *} scm_array_handle_s8_elements (scm_t_array_handle *handle)
2515 @deftypefnx {C Function} {const scm_t_uint16 *} scm_array_handle_u16_elements (scm_t_array_handle *handle)
2516 @deftypefnx {C Function} {const scm_t_int16 *} scm_array_handle_s16_elements (scm_t_array_handle *handle)
2517 @deftypefnx {C Function} {const scm_t_uint32 *} scm_array_handle_u32_elements (scm_t_array_handle *handle)
2518 @deftypefnx {C Function} {const scm_t_int32 *} scm_array_handle_s32_elements (scm_t_array_handle *handle)
2519 @deftypefnx {C Function} {const scm_t_uint64 *} scm_array_handle_u64_elements (scm_t_array_handle *handle)
2520 @deftypefnx {C Function} {const scm_t_int64 *} scm_array_handle_s64_elements (scm_t_array_handle *handle)
2521 @deftypefnx {C Function} {const float *} scm_array_handle_f32_elements (scm_t_array_handle *handle)
2522 @deftypefnx {C Function} {const double *} scm_array_handle_f64_elements (scm_t_array_handle *handle)
2523 @deftypefnx {C Function} {const float *} scm_array_handle_c32_elements (scm_t_array_handle *handle)
2524 @deftypefnx {C Function} {const double *} scm_array_handle_c64_elements (scm_t_array_handle *handle)
2525 Return a pointer to the elements of a uniform numeric array of the
2526 indicated kind for reading. This pointer is valid as long as the array
2529 The pointers for @code{c32} and @code{c64} uniform numeric arrays point
2530 to pairs of floating point numbers. The even index holds the real part,
2531 the odd index the imaginary part of the complex number.
2534 @deftypefn {C Function} {scm_t_uint8 *} scm_array_handle_u8_writable_elements (scm_t_array_handle *handle)
2535 @deftypefnx {C Function} {scm_t_int8 *} scm_array_handle_s8_writable_elements (scm_t_array_handle *handle)
2536 @deftypefnx {C Function} {scm_t_uint16 *} scm_array_handle_u16_writable_elements (scm_t_array_handle *handle)
2537 @deftypefnx {C Function} {scm_t_int16 *} scm_array_handle_s16_writable_elements (scm_t_array_handle *handle)
2538 @deftypefnx {C Function} {scm_t_uint32 *} scm_array_handle_u32_writable_elements (scm_t_array_handle *handle)
2539 @deftypefnx {C Function} {scm_t_int32 *} scm_array_handle_s32_writable_elements (scm_t_array_handle *handle)
2540 @deftypefnx {C Function} {scm_t_uint64 *} scm_array_handle_u64_writable_elements (scm_t_array_handle *handle)
2541 @deftypefnx {C Function} {scm_t_int64 *} scm_array_handle_s64_writable_elements (scm_t_array_handle *handle)
2542 @deftypefnx {C Function} {float *} scm_array_handle_f32_writable_elements (scm_t_array_handle *handle)
2543 @deftypefnx {C Function} {double *} scm_array_handle_f64_writable_elements (scm_t_array_handle *handle)
2544 @deftypefnx {C Function} {float *} scm_array_handle_c32_writable_elements (scm_t_array_handle *handle)
2545 @deftypefnx {C Function} {double *} scm_array_handle_c64_writable_elements (scm_t_array_handle *handle)
2546 Like @code{scm_array_handle_<kind>_elements}, but the pointer is good
2547 for reading and writing.
2550 @deftypefn {C Function} {const scm_t_uint32 *} scm_array_handle_bit_elements (scm_t_array_handle *handle)
2551 Return a pointer to the words that store the bits of the represented
2552 array, which must be a bit array.
2554 Unlike other arrays, bit arrays have an additional offset that must be
2555 figured into index calculations. That offset is returned by
2556 @code{scm_array_handle_bit_elements_offset}.
2558 To find a certain bit you first need to calculate its position as
2559 explained above for @code{scm_array_handle_dims} and then add the
2560 offset. This gives the absolute position of the bit, which is always a
2561 non-negative integer.
2563 Each word of the bit array storage block contains exactly 32 bits, with
2564 the least significant bit in that word having the lowest absolute
2565 position number. The next word contains the next 32 bits.
2567 Thus, the following code can be used to access a bit whose position
2568 according to @code{scm_array_handle_dims} is given in @var{pos}:
2572 scm_t_array_handle handle;
2576 size_t word_pos, mask;
2578 scm_array_get_handle (&bit_array, &handle);
2579 bits = scm_array_handle_bit_elements (&handle);
2582 abs_pos = pos + scm_array_handle_bit_elements_offset (&handle);
2583 word_pos = abs_pos / 32;
2584 mask = 1L << (abs_pos % 32);
2586 if (bits[word_pos] & mask)
2589 scm_array_handle_release (&handle);
2594 @deftypefn {C Function} {scm_t_uint32 *} scm_array_handle_bit_writable_elements (scm_t_array_handle *handle)
2595 Like @code{scm_array_handle_bit_elements} but the pointer is good for
2596 reading and writing. You must take care not to modify bits outside of
2597 the allowed index range of the array, even for contiguous arrays.
2603 A @dfn{record type} is a first class object representing a user-defined
2604 data type. A @dfn{record} is an instance of a record type.
2606 @deffn {Scheme Procedure} record? obj
2607 Return @code{#t} if @var{obj} is a record of any type and @code{#f}
2610 Note that @code{record?} may be true of any Scheme value; there is no
2611 promise that records are disjoint with other Scheme types.
2614 @deffn {Scheme Procedure} make-record-type type-name field-names [print]
2615 Create and return a new @dfn{record-type descriptor}.
2617 @var{type-name} is a string naming the type. Currently it's only used
2618 in the printed representation of records, and in diagnostics.
2619 @var{field-names} is a list of symbols naming the fields of a record
2620 of the type. Duplicates are not allowed among these symbols.
2623 (make-record-type "employee" '(name age salary))
2626 The optional @var{print} argument is a function used by
2627 @code{display}, @code{write}, etc, for printing a record of the new
2628 type. It's called as @code{(@var{print} record port)} and should look
2629 at @var{record} and write to @var{port}.
2632 @deffn {Scheme Procedure} record-constructor rtd [field-names]
2633 Return a procedure for constructing new members of the type represented
2634 by @var{rtd}. The returned procedure accepts exactly as many arguments
2635 as there are symbols in the given list, @var{field-names}; these are
2636 used, in order, as the initial values of those fields in a new record,
2637 which is returned by the constructor procedure. The values of any
2638 fields not named in that list are unspecified. The @var{field-names}
2639 argument defaults to the list of field names in the call to
2640 @code{make-record-type} that created the type represented by @var{rtd};
2641 if the @var{field-names} argument is provided, it is an error if it
2642 contains any duplicates or any symbols not in the default list.
2645 @deffn {Scheme Procedure} record-predicate rtd
2646 Return a procedure for testing membership in the type represented by
2647 @var{rtd}. The returned procedure accepts exactly one argument and
2648 returns a true value if the argument is a member of the indicated record
2649 type; it returns a false value otherwise.
2652 @deffn {Scheme Procedure} record-accessor rtd field-name
2653 Return a procedure for reading the value of a particular field of a
2654 member of the type represented by @var{rtd}. The returned procedure
2655 accepts exactly one argument which must be a record of the appropriate
2656 type; it returns the current value of the field named by the symbol
2657 @var{field-name} in that record. The symbol @var{field-name} must be a
2658 member of the list of field-names in the call to @code{make-record-type}
2659 that created the type represented by @var{rtd}.
2662 @deffn {Scheme Procedure} record-modifier rtd field-name
2663 Return a procedure for writing the value of a particular field of a
2664 member of the type represented by @var{rtd}. The returned procedure
2665 accepts exactly two arguments: first, a record of the appropriate type,
2666 and second, an arbitrary Scheme value; it modifies the field named by
2667 the symbol @var{field-name} in that record to contain the given value.
2668 The returned value of the modifier procedure is unspecified. The symbol
2669 @var{field-name} must be a member of the list of field-names in the call
2670 to @code{make-record-type} that created the type represented by
2674 @deffn {Scheme Procedure} record-type-descriptor record
2675 Return a record-type descriptor representing the type of the given
2676 record. That is, for example, if the returned descriptor were passed to
2677 @code{record-predicate}, the resulting predicate would return a true
2678 value when passed the given record. Note that it is not necessarily the
2679 case that the returned descriptor is the one that was passed to
2680 @code{record-constructor} in the call that created the constructor
2681 procedure that created the given record.
2684 @deffn {Scheme Procedure} record-type-name rtd
2685 Return the type-name associated with the type represented by rtd. The
2686 returned value is @code{eqv?} to the @var{type-name} argument given in
2687 the call to @code{make-record-type} that created the type represented by
2691 @deffn {Scheme Procedure} record-type-fields rtd
2692 Return a list of the symbols naming the fields in members of the type
2693 represented by @var{rtd}. The returned value is @code{equal?} to the
2694 field-names argument given in the call to @code{make-record-type} that
2695 created the type represented by @var{rtd}.
2700 @subsection Structures
2703 A @dfn{structure} is a first class data type which holds Scheme values
2704 or C words in fields numbered 0 upwards. A @dfn{vtable} represents a
2705 structure type, giving field types and permissions, and an optional
2706 print function for @code{write} etc.
2708 Structures are lower level than records (@pxref{Records}) but have
2709 some extra features. The vtable system allows sets of types be
2710 constructed, with class data. The uninterpreted words can
2711 inter-operate with C code, allowing arbitrary pointers or other values
2712 to be stored along side usual Scheme @code{SCM} values.
2716 * Structure Basics::
2721 @node Vtables, Structure Basics, Structures, Structures
2722 @subsubsection Vtables
2724 A vtable is a structure type, specifying its layout, and other
2725 information. A vtable is actually itself a structure, but there's no
2726 need to worray about that initially (@pxref{Vtable Contents}.)
2728 @deffn {Scheme Procedure} make-vtable fields [print]
2729 Create a new vtable.
2731 @var{fields} is a string describing the fields in the structures to be
2732 created. Each field is represented by two characters, a type letter
2733 and a permissions letter, for example @code{"pw"}. The types are as
2738 @code{p} -- a Scheme value. ``p'' stands for ``protected'' meaning
2739 it's protected against garbage collection.
2742 @code{u} -- an arbitrary word of data (an @code{scm_t_bits}). At the
2743 Scheme level it's read and written as an unsigned integer. ``u''
2744 stands for ``uninterpreted'' (it's not treated as a Scheme value), or
2745 ``unprotected'' (it's not marked during GC), or ``unsigned long'' (its
2746 size), or all of these things.
2749 @code{s} -- a self-reference. Such a field holds the @code{SCM} value
2750 of the structure itself (a circular reference). This can be useful in
2751 C code where you might have a pointer to the data array, and want to
2752 get the Scheme @code{SCM} handle for the structure. In Scheme code it
2756 The second letter for each field is a permission code,
2760 @code{w} -- writable, the field can be read and written.
2762 @code{r} -- read-only, the field can be read but not written.
2764 @code{o} -- opaque, the field can be neither read nor written at the
2765 Scheme level. This can be used for fields which should only be used
2768 @code{W},@code{R},@code{O} -- a tail array, with permissions for the
2769 array fields as per @code{w},@code{r},@code{o}.
2772 A tail array is further fields at the end of a structure. The last
2773 field in the layout string might be for instance @samp{pW} to have a
2774 tail of writable Scheme-valued fields. The @samp{pW} field itself
2775 holds the tail size, and the tail fields come after it.
2777 Here are some examples.
2780 (make-vtable "pw") ;; one writable field
2781 (make-vtable "prpw") ;; one read-only and one writable
2782 (make-vtable "pwuwuw") ;; one scheme and two uninterpreted
2784 (make-vtable "prpW") ;; one fixed then a tail array
2787 The optional @var{print} argument is a function called by
2788 @code{display} and @code{write} (etc) to give a printed representation
2789 of a structure created from this vtable. It's called
2790 @code{(@var{print} struct port)} and should look at @var{struct} and
2791 write to @var{port}. The default print merely gives a form like
2792 @samp{#<struct ADDR:ADDR>} with a pair of machine addresses.
2794 The following print function for example shows the two fields of its
2799 (lambda (struct port)
2801 (display (struct-ref struct 0) port)
2802 (display " and " port)
2803 (display (struct-ref struct 1) port)
2804 (display ">" port)))
2809 @node Structure Basics, Vtable Contents, Vtables, Structures
2810 @subsubsection Structure Basics
2812 This section describes the basic procedures for working with
2813 structures. @code{make-struct} creates a structure, and
2814 @code{struct-ref} and @code{struct-set!} access write fields.
2816 @deffn {Scheme Procedure} make-struct vtable tail-size [init...]
2817 @deffnx {C Function} scm_make_struct (vtable, tail_size, init_list)
2818 Create a new structure, with layout per the given @var{vtable}
2821 @var{tail-size} is the size of the tail array if @var{vtable}
2822 specifies a tail array. @var{tail-size} should be 0 when @var{vtable}
2823 doesn't specify a tail array.
2825 The optional @var{init}@dots{} arguments are initial values for the
2826 fields of the structure (and the tail array). This is the only way to
2827 put values in read-only fields. If there are fewer @var{init}
2828 arguments than fields then the defaults are @code{#f} for a Scheme
2829 field (type @code{p}) or 0 for an uninterpreted field (type @code{u}).
2831 Type @code{s} self-reference fields, permission @code{o} opaque
2832 fields, and the count field of a tail array are all ignored for the
2833 @var{init} arguments, ie.@: an argument is not consumed by such a
2834 field. An @code{s} is always set to the structure itself, an @code{o}
2835 is always set to @code{#f} or 0 (with the intention that C code will
2836 do something to it later), and the tail count is always the given
2842 (define v (make-vtable "prpwpw"))
2843 (define s (make-struct v 0 123 "abc" 456))
2844 (struct-ref s 0) @result{} 123
2845 (struct-ref s 1) @result{} "abc"
2849 (define v (make-vtable "prpW"))
2850 (define s (make-struct v 6 "fixed field" 'x 'y))
2851 (struct-ref s 0) @result{} "fixed field"
2852 (struct-ref s 1) @result{} 2 ;; tail size
2853 (struct-ref s 2) @result{} x ;; tail array ...
2854 (struct-ref s 3) @result{} y
2855 (struct-ref s 4) @result{} #f
2859 @deffn {Scheme Procedure} struct? obj
2860 @deffnx {C Function} scm_struct_p (obj)
2861 Return @code{#t} if @var{obj} is a structure, or @code{#f} if not.
2864 @deffn {Scheme Procedure} struct-ref struct n
2865 @deffnx {C Function} scm_struct_ref (struct, n)
2866 Return the contents of field number @var{n} in @var{struct}. The
2867 first field is number 0.
2869 An error is thrown if @var{n} is out of range, or if the field cannot
2870 be read because it's @code{o} opaque.
2873 @deffn {Scheme Procedure} struct-set! struct n value
2874 @deffnx {C Function} scm_struct_set_x (struct, n, value)
2875 Set field number @var{n} in @var{struct} to @var{value}. The first
2878 An error is thrown if @var{n} is out of range, or if the field cannot
2879 be written because it's @code{r} read-only or @code{o} opaque.
2882 @deffn {Scheme Procedure} struct-vtable struct
2883 @deffnx {C Function} scm_struct_vtable (struct)
2884 Return the vtable used by @var{struct}.
2886 This can be used to examine the layout of an unknown structure, see
2887 @ref{Vtable Contents}.
2891 @node Vtable Contents, Vtable Vtables, Structure Basics, Structures
2892 @subsubsection Vtable Contents
2894 A vtable is itself a structure, with particular fields that hold
2895 information about the structures to be created. These include the
2896 fields of those structures, and the print function for them. The
2897 variables below allow access to those fields.
2899 @deffn {Scheme Procedure} struct-vtable? obj
2900 @deffnx {C Function} scm_struct_vtable_p (obj)
2901 Return @code{#t} if @var{obj} is a vtable structure.
2903 Note that because vtables are simply structures with a particular
2904 layout, @code{struct-vtable?} can potentially return true on an
2905 application structure which merely happens to look like a vtable.
2908 @defvr {Scheme Variable} vtable-index-layout
2909 @defvrx {C Macro} scm_vtable_index_layout
2910 The field number of the layout specification in a vtable. The layout
2911 specification is a symbol like @code{pwpw} formed from the fields
2912 string passed to @code{make-vtable}, or created by
2913 @code{make-struct-layout} (@pxref{Vtable Vtables}).
2916 (define v (make-vtable "pwpw" 0))
2917 (struct-ref v vtable-index-layout) @result{} pwpw
2920 This field is read-only, since the layout of structures using a vtable
2924 @defvr {Scheme Variable} vtable-index-vtable
2925 @defvrx {C Macro} scm_vtable_index_vtable
2926 A self-reference to the vtable, ie.@: a type @code{s} field. This is
2927 used by C code within Guile and has no use at the Scheme level.
2930 @defvr {Scheme Variable} vtable-index-printer
2931 @defvrx {C Macro} scm_vtable_index_printer
2932 The field number of the printer function. This field contains @code{#f}
2933 if the default print function should be used.
2936 (define (my-print-func struct port)
2938 (define v (make-vtable "pwpw" my-print-func))
2939 (struct-ref v vtable-index-printer) @result{} my-print-func
2942 This field is writable, allowing the print function to be changed
2946 @deffn {Scheme Procedure} struct-vtable-name vtable
2947 @deffnx {Scheme Procedure} set-struct-vtable-name! vtable name
2948 @deffnx {C Function} scm_struct_vtable_name (vtable)
2949 @deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name)
2950 Get or set the name of @var{vtable}. @var{name} is a symbol and is
2951 used in the default print function when printing structures created
2955 (define v (make-vtable "pw"))
2956 (set-struct-vtable-name! v 'my-name)
2958 (define s (make-struct v 0))
2959 (display s) @print{} #<my-name b7ab3ae0:b7ab3730>
2963 @deffn {Scheme Procedure} struct-vtable-tag vtable
2964 @deffnx {C Function} scm_struct_vtable_tag (vtable)
2965 Return the tag of the given @var{vtable}.
2967 @c FIXME: what can be said about what this means?
2972 @node Vtable Vtables, , Vtable Contents, Structures
2973 @subsubsection Vtable Vtables
2975 As noted above, a vtable is a structure and that structure is itself
2976 described by a vtable. Such a ``vtable of a vtable'' can be created
2977 with @code{make-vtable-vtable} below. This can be used to build sets
2978 of related vtables, possibly with extra application fields.
2980 This second level of vtable can be a little confusing. The ball
2981 example below is a typical use, adding a ``class data'' field to the
2982 vtables, from which instance structures are created. The current
2983 implementation of Guile's own records (@pxref{Records}) does something
2984 similar, a record type descriptor is a vtable with room to hold the
2985 field names of the records to be created from it.
2987 @deffn {Scheme Procedure} make-vtable-vtable user-fields tail-size [print]
2988 @deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_size, print_and_init_list)
2989 Create a ``vtable-vtable'' which can be used to create vtables. This
2990 vtable-vtable is also a vtable, and is self-describing, meaning its
2991 vtable is itself. The following is a simple usage.
2994 (define vt-vt (make-vtable-vtable "" 0))
2995 (define vt (make-struct vt-vt 0
2996 (make-struct-layout "pwpw"))
2997 (define s (make-struct vt 0 123 456))
2999 (struct-ref s 0) @result{} 123
3002 @code{make-struct} is used to create a vtable from the vtable-vtable.
3003 The first initializer is a layout object (field
3004 @code{vtable-index-layout}), usually obtained from
3005 @code{make-struct-layout} (below). An optional second initializer is
3006 a printer function (field @code{vtable-index-printer}), used as
3007 described under @code{make-vtable} (@pxref{Vtables}).
3010 @var{user-fields} is a layout string giving extra fields to have in
3011 the vtables. A vtable starts with some base fields as per @ref{Vtable
3012 Contents}, and @var{user-fields} is appended. The @var{user-fields}
3013 start at field number @code{vtable-offset-user} (below), and exist in
3014 both the vtable-vtable and in the vtables created from it. Such
3015 fields provide space for ``class data''. For example,
3018 (define vt-of-vt (make-vtable-vtable "pw" 0))
3019 (define vt (make-struct vt-of-vt 0))
3020 (struct-set! vt vtable-offset-user "my class data")
3023 @var{tail-size} is the size of the tail array in the vtable-vtable
3024 itself, if @var{user-fields} specifies a tail array. This should be 0
3025 if nothing extra is required or the format has no tail array. The
3026 tail array field such as @samp{pW} holds the tail array size, as
3027 usual, and is followed by the extra space.
3030 (define vt-vt (make-vtable-vtable "pW" 20))
3031 (define my-vt-tail-start (1+ vtable-offset-user))
3032 (struct-set! vt-vt (+ 3 my-vt-tail-start) "data in tail")
3035 The optional @var{print} argument is used by @code{display} and
3036 @code{write} (etc) to print the vtable-vtable and any vtables created
3037 from it. It's called as @code{(@var{print} vtable port)} and should
3038 look at @var{vtable} and write to @var{port}. The default is the
3039 usual structure print function, which just gives machine addresses.
3042 @deffn {Scheme Procedure} make-struct-layout fields
3043 @deffnx {C Function} scm_make_struct_layout (fields)
3044 Return a structure layout symbol, from a @var{fields} string.
3045 @var{fields} is as described under @code{make-vtable}
3046 (@pxref{Vtables}). An invalid @var{fields} string is an error.
3049 (make-struct-layout "prpW") @result{} prpW
3050 (make-struct-layout "blah") @result{} ERROR
3054 @defvr {Scheme Variable} vtable-offset-user
3055 @defvrx {C Macro} scm_vtable_offset_user
3056 The first field in a vtable which is available for application use.
3057 Such fields only exist when specified by @var{user-fields} in
3058 @code{make-vtable-vtable} above.
3062 Here's an extended vtable-vtable example, creating classes of
3063 ``balls''. Each class has a ``colour'', which is fixed. Instances of
3064 those classes are created, and such each such ball has an ``owner'',
3065 which can be changed.
3068 (define ball-root (make-vtable-vtable "pr" 0))
3070 (define (make-ball-type ball-color)
3071 (make-struct ball-root 0
3072 (make-struct-layout "pw")
3074 (format port "#<a ~A ball owned by ~A>"
3078 (define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
3079 (define (owner ball) (struct-ref ball 0))
3081 (define red (make-ball-type 'red))
3082 (define green (make-ball-type 'green))
3084 (define (make-ball type owner) (make-struct type 0 owner))
3086 (define ball (make-ball green 'Nisse))
3087 ball @result{} #<a green ball owned by Nisse>
3091 @node Dictionary Types
3092 @subsection Dictionary Types
3094 A @dfn{dictionary} object is a data structure used to index
3095 information in a user-defined way. In standard Scheme, the main
3096 aggregate data types are lists and vectors. Lists are not really
3097 indexed at all, and vectors are indexed only by number
3098 (e.g. @code{(vector-ref foo 5)}). Often you will find it useful
3099 to index your data on some other type; for example, in a library
3100 catalog you might want to look up a book by the name of its
3101 author. Dictionaries are used to help you organize information in
3104 An @dfn{association list} (or @dfn{alist} for short) is a list of
3105 key-value pairs. Each pair represents a single quantity or
3106 object; the @code{car} of the pair is a key which is used to
3107 identify the object, and the @code{cdr} is the object's value.
3109 A @dfn{hash table} also permits you to index objects with
3110 arbitrary keys, but in a way that makes looking up any one object
3111 extremely fast. A well-designed hash system makes hash table
3112 lookups almost as fast as conventional array or vector references.
3114 Alists are popular among Lisp programmers because they use only
3115 the language's primitive operations (lists, @dfn{car}, @dfn{cdr}
3116 and the equality primitives). No changes to the language core are
3117 necessary. Therefore, with Scheme's built-in list manipulation
3118 facilities, it is very convenient to handle data stored in an
3119 association list. Also, alists are highly portable and can be
3120 easily implemented on even the most minimal Lisp systems.
3122 However, alists are inefficient, especially for storing large
3123 quantities of data. Because we want Guile to be useful for large
3124 software systems as well as small ones, Guile provides a rich set
3125 of tools for using either association lists or hash tables.
3127 @node Association Lists
3128 @subsection Association Lists
3129 @tpindex Association Lists
3131 @cindex association List
3135 An association list is a conventional data structure that is often used
3136 to implement simple key-value databases. It consists of a list of
3137 entries in which each entry is a pair. The @dfn{key} of each entry is
3138 the @code{car} of the pair and the @dfn{value} of each entry is the
3142 ASSOCIATION LIST ::= '( (KEY1 . VALUE1)
3150 Association lists are also known, for short, as @dfn{alists}.
3152 The structure of an association list is just one example of the infinite
3153 number of possible structures that can be built using pairs and lists.
3154 As such, the keys and values in an association list can be manipulated
3155 using the general list structure procedures @code{cons}, @code{car},
3156 @code{cdr}, @code{set-car!}, @code{set-cdr!} and so on. However,
3157 because association lists are so useful, Guile also provides specific
3158 procedures for manipulating them.
3161 * Alist Key Equality::
3162 * Adding or Setting Alist Entries::
3163 * Retrieving Alist Entries::
3164 * Removing Alist Entries::
3165 * Sloppy Alist Functions::
3169 @node Alist Key Equality
3170 @subsubsection Alist Key Equality
3172 All of Guile's dedicated association list procedures, apart from
3173 @code{acons}, come in three flavours, depending on the level of equality
3174 that is required to decide whether an existing key in the association
3175 list is the same as the key that the procedure call uses to identify the
3180 Procedures with @dfn{assq} in their name use @code{eq?} to determine key
3184 Procedures with @dfn{assv} in their name use @code{eqv?} to determine
3188 Procedures with @dfn{assoc} in their name use @code{equal?} to
3189 determine key equality.
3192 @code{acons} is an exception because it is used to build association
3193 lists which do not require their entries' keys to be unique.
3195 @node Adding or Setting Alist Entries
3196 @subsubsection Adding or Setting Alist Entries
3198 @code{acons} adds a new entry to an association list and returns the
3199 combined association list. The combined alist is formed by consing the
3200 new entry onto the head of the alist specified in the @code{acons}
3201 procedure call. So the specified alist is not modified, but its
3202 contents become shared with the tail of the combined alist that
3203 @code{acons} returns.
3205 In the most common usage of @code{acons}, a variable holding the
3206 original association list is updated with the combined alist:
3209 (set! address-list (acons name address address-list))
3212 In such cases, it doesn't matter that the old and new values of
3213 @code{address-list} share some of their contents, since the old value is
3214 usually no longer independently accessible.
3216 Note that @code{acons} adds the specified new entry regardless of
3217 whether the alist may already contain entries with keys that are, in
3218 some sense, the same as that of the new entry. Thus @code{acons} is
3219 ideal for building alists where there is no concept of key uniqueness.
3222 (set! task-list (acons 3 "pay gas bill" '()))
3225 ((3 . "pay gas bill"))
3227 (set! task-list (acons 3 "tidy bedroom" task-list))
3230 ((3 . "tidy bedroom") (3 . "pay gas bill"))
3233 @code{assq-set!}, @code{assv-set!} and @code{assoc-set!} are used to add
3234 or replace an entry in an association list where there @emph{is} a
3235 concept of key uniqueness. If the specified association list already
3236 contains an entry whose key is the same as that specified in the
3237 procedure call, the existing entry is replaced by the new one.
3238 Otherwise, the new entry is consed onto the head of the old association
3239 list to create the combined alist. In all cases, these procedures
3240 return the combined alist.
3242 @code{assq-set!} and friends @emph{may} destructively modify the
3243 structure of the old association list in such a way that an existing
3244 variable is correctly updated without having to @code{set!} it to the
3250 (("mary" . "34 Elm Road") ("james" . "16 Bow Street"))
3252 (assoc-set! address-list "james" "1a London Road")
3254 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
3258 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
3264 (assoc-set! address-list "bob" "11 Newington Avenue")
3266 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
3267 ("james" . "1a London Road"))
3271 (("mary" . "34 Elm Road") ("james" . "1a London Road"))
3274 The only safe way to update an association list variable when adding or
3275 replacing an entry like this is to @code{set!} the variable to the
3280 (assoc-set! address-list "bob" "11 Newington Avenue"))
3283 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
3284 ("james" . "1a London Road"))
3287 Because of this slight inconvenience, you may find it more convenient to
3288 use hash tables to store dictionary data. If your application will not
3289 be modifying the contents of an alist very often, this may not make much
3292 If you need to keep the old value of an association list in a form
3293 independent from the list that results from modification by
3294 @code{acons}, @code{assq-set!}, @code{assv-set!} or @code{assoc-set!},
3295 use @code{list-copy} to copy the old association list before modifying
3298 @deffn {Scheme Procedure} acons key value alist
3299 @deffnx {C Function} scm_acons (key, value, alist)
3300 Add a new key-value pair to @var{alist}. A new pair is
3301 created whose car is @var{key} and whose cdr is @var{value}, and the
3302 pair is consed onto @var{alist}, and the new list is returned. This
3303 function is @emph{not} destructive; @var{alist} is not modified.
3306 @deffn {Scheme Procedure} assq-set! alist key val
3307 @deffnx {Scheme Procedure} assv-set! alist key value
3308 @deffnx {Scheme Procedure} assoc-set! alist key value
3309 @deffnx {C Function} scm_assq_set_x (alist, key, val)
3310 @deffnx {C Function} scm_assv_set_x (alist, key, val)
3311 @deffnx {C Function} scm_assoc_set_x (alist, key, val)
3312 Reassociate @var{key} in @var{alist} with @var{value}: find any existing
3313 @var{alist} entry for @var{key} and associate it with the new
3314 @var{value}. If @var{alist} does not contain an entry for @var{key},
3315 add a new one. Return the (possibly new) alist.
3317 These functions do not attempt to verify the structure of @var{alist},
3318 and so may cause unusual results if passed an object that is not an
3322 @node Retrieving Alist Entries
3323 @subsubsection Retrieving Alist Entries
3328 @code{assq}, @code{assv} and @code{assoc} find the entry in an alist
3329 for a given key, and return the @code{(@var{key} . @var{value})} pair.
3330 @code{assq-ref}, @code{assv-ref} and @code{assoc-ref} do a similar
3331 lookup, but return just the @var{value}.
3333 @deffn {Scheme Procedure} assq key alist
3334 @deffnx {Scheme Procedure} assv key alist
3335 @deffnx {Scheme Procedure} assoc key alist
3336 @deffnx {C Function} scm_assq (key, alist)
3337 @deffnx {C Function} scm_assv (key, alist)
3338 @deffnx {C Function} scm_assoc (key, alist)
3339 Return the first entry in @var{alist} with the given @var{key}. The
3340 return is the pair @code{(KEY . VALUE)} from @var{alist}. If there's
3341 no matching entry the return is @code{#f}.
3343 @code{assq} compares keys with @code{eq?}, @code{assv} uses
3344 @code{eqv?} and @code{assoc} uses @code{equal?}. See also SRFI-1
3345 which has an extended @code{assoc} (@ref{SRFI-1 Association Lists}).
3348 @deffn {Scheme Procedure} assq-ref alist key
3349 @deffnx {Scheme Procedure} assv-ref alist key
3350 @deffnx {Scheme Procedure} assoc-ref alist key
3351 @deffnx {C Function} scm_assq_ref (alist, key)
3352 @deffnx {C Function} scm_assv_ref (alist, key)
3353 @deffnx {C Function} scm_assoc_ref (alist, key)
3354 Return the value from the first entry in @var{alist} with the given
3355 @var{key}, or @code{#f} if there's no such entry.
3357 @code{assq-ref} compares keys with @code{eq?}, @code{assv-ref} uses
3358 @code{eqv?} and @code{assoc-ref} uses @code{equal?}.
3360 Notice these functions have the @var{key} argument last, like other
3361 @code{-ref} functions, but this is opposite to what what @code{assq}
3364 When the return is @code{#f} it can be either @var{key} not found, or
3365 an entry which happens to have value @code{#f} in the @code{cdr}. Use
3366 @code{assq} etc above if you need to differentiate these cases.
3370 @node Removing Alist Entries
3371 @subsubsection Removing Alist Entries
3373 To remove the element from an association list whose key matches a
3374 specified key, use @code{assq-remove!}, @code{assv-remove!} or
3375 @code{assoc-remove!} (depending, as usual, on the level of equality
3376 required between the key that you specify and the keys in the
3379 As with @code{assq-set!} and friends, the specified alist may or may not
3380 be modified destructively, and the only safe way to update a variable
3381 containing the alist is to @code{set!} it to the value that
3382 @code{assq-remove!} and friends return.
3387 (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road")
3388 ("james" . "1a London Road"))
3390 (set! address-list (assoc-remove! address-list "mary"))
3393 (("bob" . "11 Newington Avenue") ("james" . "1a London Road"))
3396 Note that, when @code{assq/v/oc-remove!} is used to modify an
3397 association list that has been constructed only using the corresponding
3398 @code{assq/v/oc-set!}, there can be at most one matching entry in the
3399 alist, so the question of multiple entries being removed in one go does
3400 not arise. If @code{assq/v/oc-remove!} is applied to an association
3401 list that has been constructed using @code{acons}, or an
3402 @code{assq/v/oc-set!} with a different level of equality, or any mixture
3403 of these, it removes only the first matching entry from the alist, even
3404 if the alist might contain further matching entries. For example:
3407 (define address-list '())
3408 (set! address-list (assq-set! address-list "mary" "11 Elm Street"))
3409 (set! address-list (assq-set! address-list "mary" "57 Pine Drive"))
3412 (("mary" . "57 Pine Drive") ("mary" . "11 Elm Street"))
3414 (set! address-list (assoc-remove! address-list "mary"))
3417 (("mary" . "11 Elm Street"))
3420 In this example, the two instances of the string "mary" are not the same
3421 when compared using @code{eq?}, so the two @code{assq-set!} calls add
3422 two distinct entries to @code{address-list}. When compared using
3423 @code{equal?}, both "mary"s in @code{address-list} are the same as the
3424 "mary" in the @code{assoc-remove!} call, but @code{assoc-remove!} stops
3425 after removing the first matching entry that it finds, and so one of the
3426 "mary" entries is left in place.
3428 @deffn {Scheme Procedure} assq-remove! alist key
3429 @deffnx {Scheme Procedure} assv-remove! alist key
3430 @deffnx {Scheme Procedure} assoc-remove! alist key
3431 @deffnx {C Function} scm_assq_remove_x (alist, key)
3432 @deffnx {C Function} scm_assv_remove_x (alist, key)
3433 @deffnx {C Function} scm_assoc_remove_x (alist, key)
3434 Delete the first entry in @var{alist} associated with @var{key}, and return
3435 the resulting alist.
3438 @node Sloppy Alist Functions
3439 @subsubsection Sloppy Alist Functions
3441 @code{sloppy-assq}, @code{sloppy-assv} and @code{sloppy-assoc} behave
3442 like the corresponding non-@code{sloppy-} procedures, except that they
3443 return @code{#f} when the specified association list is not well-formed,
3444 where the non-@code{sloppy-} versions would signal an error.
3446 Specifically, there are two conditions for which the non-@code{sloppy-}
3447 procedures signal an error, which the @code{sloppy-} procedures handle
3448 instead by returning @code{#f}. Firstly, if the specified alist as a
3449 whole is not a proper list:
3452 (assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
3454 ERROR: In procedure assoc in expression (assoc "mary" (quote #)):
3455 ERROR: Wrong type argument in position 2 (expecting association list): ((1 . 2) ("key" . "door") . "open sesame")
3457 (sloppy-assoc "mary" '((1 . 2) ("key" . "door") . "open sesame"))
3463 Secondly, if one of the entries in the specified alist is not a pair:
3466 (assoc 2 '((1 . 1) 2 (3 . 9)))
3468 ERROR: In procedure assoc in expression (assoc 2 (quote #)):
3469 ERROR: Wrong type argument in position 2 (expecting association list): ((1 . 1) 2 (3 . 9))
3471 (sloppy-assoc 2 '((1 . 1) 2 (3 . 9)))
3476 Unless you are explicitly working with badly formed association lists,
3477 it is much safer to use the non-@code{sloppy-} procedures, because they
3478 help to highlight coding and data errors that the @code{sloppy-}
3479 versions would silently cover up.
3481 @deffn {Scheme Procedure} sloppy-assq key alist
3482 @deffnx {C Function} scm_sloppy_assq (key, alist)
3483 Behaves like @code{assq} but does not do any error checking.
3484 Recommended only for use in Guile internals.
3487 @deffn {Scheme Procedure} sloppy-assv key alist
3488 @deffnx {C Function} scm_sloppy_assv (key, alist)
3489 Behaves like @code{assv} but does not do any error checking.
3490 Recommended only for use in Guile internals.
3493 @deffn {Scheme Procedure} sloppy-assoc key alist
3494 @deffnx {C Function} scm_sloppy_assoc (key, alist)
3495 Behaves like @code{assoc} but does not do any error checking.
3496 Recommended only for use in Guile internals.
3500 @subsubsection Alist Example
3502 Here is a longer example of how alists may be used in practice.
3505 (define capitals '(("New York" . "Albany")
3506 ("Oregon" . "Salem")
3507 ("Florida" . "Miami")))
3509 ;; What's the capital of Oregon?
3510 (assoc "Oregon" capitals) @result{} ("Oregon" . "Salem")
3511 (assoc-ref capitals "Oregon") @result{} "Salem"
3513 ;; We left out South Dakota.
3515 (assoc-set! capitals "South Dakota" "Pierre"))
3517 @result{} (("South Dakota" . "Pierre")
3518 ("New York" . "Albany")
3519 ("Oregon" . "Salem")
3520 ("Florida" . "Miami"))
3522 ;; And we got Florida wrong.
3524 (assoc-set! capitals "Florida" "Tallahassee"))
3526 @result{} (("South Dakota" . "Pierre")
3527 ("New York" . "Albany")
3528 ("Oregon" . "Salem")
3529 ("Florida" . "Tallahassee"))
3531 ;; After Oregon secedes, we can remove it.
3533 (assoc-remove! capitals "Oregon"))
3535 @result{} (("South Dakota" . "Pierre")
3536 ("New York" . "Albany")
3537 ("Florida" . "Tallahassee"))
3541 @subsection Hash Tables
3542 @tpindex Hash Tables
3544 Hash tables are dictionaries which offer similar functionality as
3545 association lists: They provide a mapping from keys to values. The
3546 difference is that association lists need time linear in the size of
3547 elements when searching for entries, whereas hash tables can normally
3548 search in constant time. The drawback is that hash tables require a
3549 little bit more memory, and that you can not use the normal list
3550 procedures (@pxref{Lists}) for working with them.
3552 Guile provides two types of hashtables. One is an abstract data type
3553 that can only be manipulated with the functions in this section. The
3554 other type is concrete: it uses a normal vector with alists as
3555 elements. The advantage of the abstract hash tables is that they will
3556 be automatically resized when they become too full or too empty.
3559 * Hash Table Examples:: Demonstration of hash table usage.
3560 * Hash Table Reference:: Hash table procedure descriptions.
3564 @node Hash Table Examples
3565 @subsubsection Hash Table Examples
3567 For demonstration purposes, this section gives a few usage examples of
3568 some hash table procedures, together with some explanation what they do.
3570 First we start by creating a new hash table with 31 slots, and
3571 populate it with two key/value pairs.
3574 (define h (make-hash-table 31))
3576 ;; This is an opaque object
3581 ;; We can also use a vector of alists.
3582 (define h (make-vector 7 '()))
3586 #(() () () () () () ())
3588 ;; Inserting into a hash table can be done with hashq-set!
3589 (hashq-set! h 'foo "bar")
3593 (hashq-set! h 'braz "zonk")
3597 ;; Or with hash-create-handle!
3598 (hashq-create-handle! h 'frob #f)
3602 ;; The vector now contains three elements in the alists and the frob
3603 ;; entry is at index (hashq 'frob).
3606 #(() () () () ((frob . #f) (braz . "zonk")) () ((foo . "bar")))
3614 You can get the value for a given key with the procedure
3615 @code{hashq-ref}, but the problem with this procedure is that you
3616 cannot reliably determine whether a key does exists in the table. The
3617 reason is that the procedure returns @code{#f} if the key is not in
3618 the table, but it will return the same value if the key is in the
3619 table and just happens to have the value @code{#f}, as you can see in
3620 the following examples.
3631 (hashq-ref h 'not-there)
3636 Better is to use the procedure @code{hashq-get-handle}, which makes a
3637 distinction between the two cases. Just like @code{assq}, this
3638 procedure returns a key/value-pair on success, and @code{#f} if the
3642 (hashq-get-handle h 'foo)
3646 (hashq-get-handle h 'not-there)
3651 There is no procedure for calculating the number of key/value-pairs in
3652 a hash table, but @code{hash-fold} can be used for doing exactly that.
3655 (hash-fold (lambda (key value seed) (+ 1 seed)) 0 h)
3660 @node Hash Table Reference
3661 @subsubsection Hash Table Reference
3663 @c FIXME: Describe in broad terms what happens for resizing, and what
3664 @c the initial size means for this.
3666 Like the association list functions, the hash table functions come in
3667 several varieties, according to the equality test used for the keys.
3668 Plain @code{hash-} functions use @code{equal?}, @code{hashq-}
3669 functions use @code{eq?}, @code{hashv-} functions use @code{eqv?}, and
3670 the @code{hashx-} functions use an application supplied test.
3672 A single @code{make-hash-table} creates a hash table suitable for use
3673 with any set of functions, but it's imperative that just one set is
3674 then used consistently, or results will be unpredictable.
3676 Hash tables are implemented as a vector indexed by a hash value formed
3677 from the key, with an association list of key/value pairs for each
3678 bucket in case distinct keys hash together. Direct access to the
3679 pairs in those lists is provided by the @code{-handle-} functions.
3680 The abstract kind of hash tables hide the vector in an opaque object
3681 that represents the hash table, while for the concrete kind the vector
3682 @emph{is} the hashtable.
3684 When the number of table entries in an abstract hash table goes above
3685 a threshold, the vector is made larger and the entries are rehashed,
3686 to prevent the bucket lists from becoming too long and slowing down
3687 accesses. When the number of entries goes below a threshold, the
3688 vector is shrunk to save space.
3690 A abstract hash table is created with @code{make-hash-table}. To
3691 create a vector that is suitable as a hash table, use
3692 @code{(make-vector @var{size} '())}, for example.
3694 For the @code{hashx-} ``extended'' routines, an application supplies a
3695 @var{hash} function producing an integer index like @code{hashq} etc
3696 below, and an @var{assoc} alist search function like @code{assq} etc
3697 (@pxref{Retrieving Alist Entries}). Here's an example of such
3698 functions implementing case-insensitive hashing of string keys,
3701 (use-modules (srfi srfi-1)
3704 (define (my-hash str size)
3705 (remainder (string-hash-ci str) size))
3706 (define (my-assoc str alist)
3707 (find (lambda (pair) (string-ci=? str (car pair))) alist))
3709 (define my-table (make-hash-table))
3710 (hashx-set! my-hash my-assoc my-table "foo" 123)
3712 (hashx-ref my-hash my-assoc my-table "FOO")
3716 In a @code{hashx-} @var{hash} function the aim is to spread keys
3717 across the vector, so bucket lists don't become long. But the actual
3718 values are arbitrary as long as they're in the range 0 to
3719 @math{@var{size}-1}. Helpful functions for forming a hash value, in
3720 addition to @code{hashq} etc below, include @code{symbol-hash}
3721 (@pxref{Symbol Keys}), @code{string-hash} and @code{string-hash-ci}
3722 (@pxref{String Comparison}), and @code{char-set-hash}
3723 (@pxref{Character Set Predicates/Comparison}).
3726 @deffn {Scheme Procedure} make-hash-table [size]
3727 Create a new abstract hash table object, with an optional minimum
3730 When @var{size} is given, the table vector will still grow and shrink
3731 automatically, as described above, but with @var{size} as a minimum.
3732 If an application knows roughly how many entries the table will hold
3733 then it can use @var{size} to avoid rehashing when initial entries are
3737 @deffn {Scheme Procedure} hash-table? obj
3738 @deffnx {C Function} scm_hash_table_p (obj)
3739 Return @code{#t} if @var{obj} is a abstract hash table object.
3742 @deffn {Scheme Procedure} hash-clear! table
3743 @deffnx {C Function} scm_hash_clear_x (table)
3744 Remove all items from @var{table} (without triggering a resize).
3747 @deffn {Scheme Procedure} hash-ref table key [dflt]
3748 @deffnx {Scheme Procedure} hashq-ref table key [dflt]
3749 @deffnx {Scheme Procedure} hashv-ref table key [dflt]
3750 @deffnx {Scheme Procedure} hashx-ref hash assoc table key [dflt]
3751 @deffnx {C Function} scm_hash_ref (table, key, dflt)
3752 @deffnx {C Function} scm_hashq_ref (table, key, dflt)
3753 @deffnx {C Function} scm_hashv_ref (table, key, dflt)
3754 @deffnx {C Function} scm_hashx_ref (hash, assoc, table, key, dflt)
3755 Lookup @var{key} in the given hash @var{table}, and return the
3756 associated value. If @var{key} is not found, return @var{dflt}, or
3757 @code{#f} if @var{dflt} is not given.
3760 @deffn {Scheme Procedure} hash-set! table key val
3761 @deffnx {Scheme Procedure} hashq-set! table key val
3762 @deffnx {Scheme Procedure} hashv-set! table key val
3763 @deffnx {Scheme Procedure} hashx-set! hash assoc table key val
3764 @deffnx {C Function} scm_hash_set_x (table, key, val)
3765 @deffnx {C Function} scm_hashq_set_x (table, key, val)
3766 @deffnx {C Function} scm_hashv_set_x (table, key, val)
3767 @deffnx {C Function} scm_hashx_set_x (hash, assoc, table, key, val)
3768 Associate @var{val} with @var{key} in the given hash @var{table}. If
3769 @var{key} is already present then it's associated value is changed.
3770 If it's not present then a new entry is created.
3773 @deffn {Scheme Procedure} hash-remove! table key
3774 @deffnx {Scheme Procedure} hashq-remove! table key
3775 @deffnx {Scheme Procedure} hashv-remove! table key
3776 @deffnx {Scheme Procedure} hashx-remove! hash assoc table key
3777 @deffnx {C Function} scm_hash_remove_x (table, key)
3778 @deffnx {C Function} scm_hashq_remove_x (table, key)
3779 @deffnx {C Function} scm_hashv_remove_x (table, key)
3780 @deffnx {C Function} scm_hashx_remove_x (hash, assoc, table, key)
3781 Remove any association for @var{key} in the given hash @var{table}.
3782 If @var{key} is not in @var{table} then nothing is done.
3785 @deffn {Scheme Procedure} hash key size
3786 @deffnx {Scheme Procedure} hashq key size
3787 @deffnx {Scheme Procedure} hashv key size
3788 @deffnx {C Function} scm_hash (key, size)
3789 @deffnx {C Function} scm_hashq (key, size)
3790 @deffnx {C Function} scm_hashv (key, size)
3791 Return a hash value for @var{key}. This is a number in the range
3792 @math{0} to @math{@var{size}-1}, which is suitable for use in a hash
3793 table of the given @var{size}.
3795 Note that @code{hashq} and @code{hashv} may use internal addresses of
3796 objects, so if an object is garbage collected and re-created it can
3797 have a different hash value, even when the two are notionally
3798 @code{eq?}. For instance with symbols,
3801 (hashq 'something 123) @result{} 19
3803 (hashq 'something 123) @result{} 62
3806 In normal use this is not a problem, since an object entered into a
3807 hash table won't be garbage collected until removed. It's only if
3808 hashing calculations are somehow separated from normal references that
3809 its lifetime needs to be considered.
3812 @deffn {Scheme Procedure} hash-get-handle table key
3813 @deffnx {Scheme Procedure} hashq-get-handle table key
3814 @deffnx {Scheme Procedure} hashv-get-handle table key
3815 @deffnx {Scheme Procedure} hashx-get-handle hash assoc table key
3816 @deffnx {C Function} scm_hash_get_handle (table, key)
3817 @deffnx {C Function} scm_hashq_get_handle (table, key)
3818 @deffnx {C Function} scm_hashv_get_handle (table, key)
3819 @deffnx {C Function} scm_hashx_get_handle (hash, assoc, table, key)
3820 Return the @code{(@var{key} . @var{value})} pair for @var{key} in the
3821 given hash @var{table}, or @code{#f} if @var{key} is not in
3825 @deffn {Scheme Procedure} hash-create-handle! table key init
3826 @deffnx {Scheme Procedure} hashq-create-handle! table key init
3827 @deffnx {Scheme Procedure} hashv-create-handle! table key init
3828 @deffnx {Scheme Procedure} hashx-create-handle! hash assoc table key init
3829 @deffnx {C Function} scm_hash_create_handle_x (table, key, init)
3830 @deffnx {C Function} scm_hashq_create_handle_x (table, key, init)
3831 @deffnx {C Function} scm_hashv_create_handle_x (table, key, init)
3832 @deffnx {C Function} scm_hashx_create_handle_x (hash, assoc, table, key, init)
3833 Return the @code{(@var{key} . @var{value})} pair for @var{key} in the
3834 given hash @var{table}. If @var{key} is not in @var{table} then
3835 create an entry for it with @var{init} as the value, and return that
3839 @deffn {Scheme Procedure} hash-map->list proc table
3840 @deffnx {Scheme Procedure} hash-for-each proc table
3841 @deffnx {C Function} scm_hash_map_to_list (proc, table)
3842 @deffnx {C Function} scm_hash_for_each (proc, table)
3843 Apply @var{proc} to the entries in the given hash @var{table}. Each
3844 call is @code{(@var{proc} @var{key} @var{value})}. @code{hash-map->list}
3845 returns a list of the results from these calls, @code{hash-for-each}
3846 discards the results and returns an unspecified value.
3848 Calls are made over the table entries in an unspecified order, and for
3849 @code{hash-map->list} the order of the values in the returned list is
3850 unspecified. Results will be unpredictable if @var{table} is modified
3853 For example the following returns a new alist comprising all the
3854 entries from @code{mytable}, in no particular order.
3857 (hash-map->list cons mytable)
3861 @deffn {Scheme Procedure} hash-for-each-handle proc table
3862 @deffnx {C Function} scm_hash_for_each_handle (proc, table)
3863 Apply @var{proc} to the entries in the given hash @var{table}. Each
3864 call is @code{(@var{proc} @var{handle})}, where @var{handle} is a
3865 @code{(@var{key} . @var{value})} pair. Return an unspecified value.
3867 @code{hash-for-each-handle} differs from @code{hash-for-each} only in
3868 the argument list of @var{proc}.
3871 @deffn {Scheme Procedure} hash-fold proc init table
3872 @deffnx {C Function} scm_hash_fold (proc, init, table)
3873 Accumulate a result by applying @var{proc} to the elements of the
3874 given hash @var{table}. Each call is @code{(@var{proc} @var{key}
3875 @var{value} @var{prior-result})}, where @var{key} and @var{value} are
3876 from the @var{table} and @var{prior-result} is the return from the
3877 previous @var{proc} call. For the first call, @var{prior-result} is
3878 the given @var{init} value.
3880 Calls are made over the table entries in an unspecified order.
3881 Results will be unpredictable if @var{table} is modified while
3882 @code{hash-fold} is running.
3884 For example, the following returns a count of how many keys in
3885 @code{mytable} are strings.
3888 (hash-fold (lambda (key value prior)
3889 (if (string? key) (1+ prior) prior))
3896 @c TeX-master: "guile.texi"