Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 | |
4 | @c Free Software Foundation, Inc. | |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
7 | @page | |
8 | @node Compound Data Types | |
9 | @section Compound Data Types | |
10 | ||
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. | |
16 | ||
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. | |
20 | ||
21 | @menu | |
22 | * Pairs:: Scheme's basic building block. | |
23 | * Lists:: Special list functions supported by Guile. | |
24 | * Vectors:: One-dimensional arrays of Scheme objects. | |
e6b226b9 MV |
25 | * Uniform Vectors:: Vectors with elements of a single type. |
26 | * Bit Vectors:: Vectors of bits. | |
27 | * Arrays:: Matrices, etc. | |
07d83abe MV |
28 | * Records:: |
29 | * Structures:: | |
07d83abe MV |
30 | * Dictionary Types:: About dictionary types in general. |
31 | * Association Lists:: List-based dictionaries. | |
32 | * Hash Tables:: Table-based dictionaries. | |
33 | @end menu | |
34 | ||
35 | ||
36 | @node Pairs | |
37 | @subsection Pairs | |
38 | @tpindex Pairs | |
39 | ||
40 | Pairs are used to combine two Scheme objects into one compound object. | |
41 | Hence the name: A pair stores a pair of objects. | |
42 | ||
43 | The data type @dfn{pair} is extremely important in Scheme, just like in | |
44 | any other Lisp dialect. The reason is that pairs are not only used to | |
45 | make two values available as one object, but that pairs are used for | |
46 | constructing lists of values. Because lists are so important in Scheme, | |
47 | they are described in a section of their own (@pxref{Lists}). | |
48 | ||
49 | Pairs can literally get entered in source code or at the REPL, in the | |
50 | so-called @dfn{dotted list} syntax. This syntax consists of an opening | |
51 | parentheses, the first element of the pair, a dot, the second element | |
52 | and a closing parentheses. The following example shows how a pair | |
53 | consisting of the two numbers 1 and 2, and a pair containing the symbols | |
54 | @code{foo} and @code{bar} can be entered. It is very important to write | |
55 | the whitespace before and after the dot, because otherwise the Scheme | |
56 | parser would not be able to figure out where to split the tokens. | |
57 | ||
58 | @lisp | |
59 | (1 . 2) | |
60 | (foo . bar) | |
61 | @end lisp | |
62 | ||
63 | But beware, if you want to try out these examples, you have to | |
64 | @dfn{quote} the expressions. More information about quotation is | |
65 | available in the section (REFFIXME). The correct way to try these | |
66 | examples is as follows. | |
67 | ||
68 | @lisp | |
69 | '(1 . 2) | |
70 | @result{} | |
71 | (1 . 2) | |
72 | '(foo . bar) | |
73 | @result{} | |
74 | (foo . bar) | |
75 | @end lisp | |
76 | ||
77 | A new pair is made by calling the procedure @code{cons} with two | |
78 | arguments. Then the argument values are stored into a newly allocated | |
79 | pair, and the pair is returned. The name @code{cons} stands for | |
80 | "construct". Use the procedure @code{pair?} to test whether a | |
81 | given Scheme object is a pair or not. | |
82 | ||
83 | @rnindex cons | |
84 | @deffn {Scheme Procedure} cons x y | |
85 | @deffnx {C Function} scm_cons (x, y) | |
86 | Return a newly allocated pair whose car is @var{x} and whose | |
87 | cdr is @var{y}. The pair is guaranteed to be different (in the | |
88 | sense of @code{eq?}) from every previously existing object. | |
89 | @end deffn | |
90 | ||
91 | @rnindex pair? | |
92 | @deffn {Scheme Procedure} pair? x | |
93 | @deffnx {C Function} scm_pair_p (x) | |
94 | Return @code{#t} if @var{x} is a pair; otherwise return | |
95 | @code{#f}. | |
96 | @end deffn | |
97 | ||
7f4c83e3 MV |
98 | @deftypefn {C Function} int scm_is_pair (SCM x) |
99 | Return 1 when @var{x} is a pair; otherwise return 0. | |
100 | @end deftypefn | |
101 | ||
07d83abe MV |
102 | The two parts of a pair are traditionally called @dfn{car} and |
103 | @dfn{cdr}. They can be retrieved with procedures of the same name | |
104 | (@code{car} and @code{cdr}), and can be modified with the procedures | |
105 | @code{set-car!} and @code{set-cdr!}. Since a very common operation in | |
106 | Scheme programs is to access the car of a pair, or the car of the cdr of | |
107 | a pair, etc., the procedures called @code{caar}, @code{cadr} and so on | |
108 | are also predefined. | |
109 | ||
110 | @rnindex car | |
111 | @rnindex cdr | |
112 | @deffn {Scheme Procedure} car pair | |
113 | @deffnx {Scheme Procedure} cdr pair | |
7f4c83e3 MV |
114 | @deffnx {C Function} scm_car (pair) |
115 | @deffnx {C Function} scm_cdr (pair) | |
07d83abe MV |
116 | Return the car or the cdr of @var{pair}, respectively. |
117 | @end deffn | |
118 | ||
7f4c83e3 MV |
119 | @deffn {Scheme Procedure} cddr pair |
120 | @deffnx {Scheme Procedure} cdar pair | |
121 | @deffnx {Scheme Procedure} cadr pair | |
122 | @deffnx {Scheme Procedure} caar pair | |
123 | @deffnx {Scheme Procedure} cdddr pair | |
124 | @deffnx {Scheme Procedure} cddar pair | |
125 | @deffnx {Scheme Procedure} cdadr pair | |
126 | @deffnx {Scheme Procedure} cdaar pair | |
127 | @deffnx {Scheme Procedure} caddr pair | |
128 | @deffnx {Scheme Procedure} cadar pair | |
129 | @deffnx {Scheme Procedure} caadr pair | |
130 | @deffnx {Scheme Procedure} caaar pair | |
07d83abe | 131 | @deffnx {Scheme Procedure} cddddr pair |
7f4c83e3 MV |
132 | @deffnx {Scheme Procedure} cdddar pair |
133 | @deffnx {Scheme Procedure} cddadr pair | |
134 | @deffnx {Scheme Procedure} cddaar pair | |
135 | @deffnx {Scheme Procedure} cdaddr pair | |
136 | @deffnx {Scheme Procedure} cdadar pair | |
137 | @deffnx {Scheme Procedure} cdaadr pair | |
138 | @deffnx {Scheme Procedure} cdaaar pair | |
139 | @deffnx {Scheme Procedure} cadddr pair | |
140 | @deffnx {Scheme Procedure} caddar pair | |
141 | @deffnx {Scheme Procedure} cadadr pair | |
142 | @deffnx {Scheme Procedure} cadaar pair | |
143 | @deffnx {Scheme Procedure} caaddr pair | |
144 | @deffnx {Scheme Procedure} caadar pair | |
145 | @deffnx {Scheme Procedure} caaadr pair | |
146 | @deffnx {Scheme Procedure} caaaar pair | |
147 | @deffnx {C Function} scm_cddr (pair) | |
148 | @deffnx {C Function} scm_cdar (pair) | |
149 | @deffnx {C Function} scm_cadr (pair) | |
150 | @deffnx {C Function} scm_caar (pair) | |
151 | @deffnx {C Function} scm_cdddr (pair) | |
152 | @deffnx {C Function} scm_cddar (pair) | |
153 | @deffnx {C Function} scm_cdadr (pair) | |
154 | @deffnx {C Function} scm_cdaar (pair) | |
155 | @deffnx {C Function} scm_caddr (pair) | |
156 | @deffnx {C Function} scm_cadar (pair) | |
157 | @deffnx {C Function} scm_caadr (pair) | |
158 | @deffnx {C Function} scm_caaar (pair) | |
159 | @deffnx {C Function} scm_cddddr (pair) | |
160 | @deffnx {C Function} scm_cdddar (pair) | |
161 | @deffnx {C Function} scm_cddadr (pair) | |
162 | @deffnx {C Function} scm_cddaar (pair) | |
163 | @deffnx {C Function} scm_cdaddr (pair) | |
164 | @deffnx {C Function} scm_cdadar (pair) | |
165 | @deffnx {C Function} scm_cdaadr (pair) | |
166 | @deffnx {C Function} scm_cdaaar (pair) | |
167 | @deffnx {C Function} scm_cadddr (pair) | |
168 | @deffnx {C Function} scm_caddar (pair) | |
169 | @deffnx {C Function} scm_cadadr (pair) | |
170 | @deffnx {C Function} scm_cadaar (pair) | |
171 | @deffnx {C Function} scm_caaddr (pair) | |
172 | @deffnx {C Function} scm_caadar (pair) | |
173 | @deffnx {C Function} scm_caaadr (pair) | |
174 | @deffnx {C Function} scm_caaaar (pair) | |
07d83abe MV |
175 | These procedures are compositions of @code{car} and @code{cdr}, where |
176 | for example @code{caddr} could be defined by | |
177 | ||
178 | @lisp | |
179 | (define caddr (lambda (x) (car (cdr (cdr x))))) | |
180 | @end lisp | |
181 | @end deffn | |
182 | ||
183 | @rnindex set-car! | |
184 | @deffn {Scheme Procedure} set-car! pair value | |
185 | @deffnx {C Function} scm_set_car_x (pair, value) | |
186 | Stores @var{value} in the car field of @var{pair}. The value returned | |
187 | by @code{set-car!} is unspecified. | |
188 | @end deffn | |
189 | ||
190 | @rnindex set-cdr! | |
191 | @deffn {Scheme Procedure} set-cdr! pair value | |
192 | @deffnx {C Function} scm_set_cdr_x (pair, value) | |
193 | Stores @var{value} in the cdr field of @var{pair}. The value returned | |
194 | by @code{set-cdr!} is unspecified. | |
195 | @end deffn | |
196 | ||
197 | ||
198 | @node Lists | |
199 | @subsection Lists | |
200 | @tpindex Lists | |
201 | ||
202 | A very important data type in Scheme---as well as in all other Lisp | |
203 | dialects---is the data type @dfn{list}.@footnote{Strictly speaking, | |
204 | Scheme does not have a real datatype @dfn{list}. Lists are made up of | |
205 | @dfn{chained pairs}, and only exist by definition---a list is a chain | |
206 | of pairs which looks like a list.} | |
207 | ||
208 | This is the short definition of what a list is: | |
209 | ||
210 | @itemize @bullet | |
211 | @item | |
212 | Either the empty list @code{()}, | |
213 | ||
214 | @item | |
215 | or a pair which has a list in its cdr. | |
216 | @end itemize | |
217 | ||
218 | @c FIXME::martin: Describe the pair chaining in more detail. | |
219 | ||
220 | @c FIXME::martin: What is a proper, what an improper list? | |
221 | @c What is a circular list? | |
222 | ||
223 | @c FIXME::martin: Maybe steal some graphics from the Elisp reference | |
224 | @c manual? | |
225 | ||
226 | @menu | |
227 | * List Syntax:: Writing literal lists. | |
228 | * List Predicates:: Testing lists. | |
229 | * List Constructors:: Creating new lists. | |
230 | * List Selection:: Selecting from lists, getting their length. | |
231 | * Append/Reverse:: Appending and reversing lists. | |
232 | * List Modification:: Modifying existing lists. | |
233 | * List Searching:: Searching for list elements | |
234 | * List Mapping:: Applying procedures to lists. | |
235 | @end menu | |
236 | ||
237 | @node List Syntax | |
238 | @subsubsection List Read Syntax | |
239 | ||
240 | The syntax for lists is an opening parentheses, then all the elements of | |
241 | the list (separated by whitespace) and finally a closing | |
242 | parentheses.@footnote{Note that there is no separation character between | |
243 | the list elements, like a comma or a semicolon.}. | |
244 | ||
245 | @lisp | |
246 | (1 2 3) ; @r{a list of the numbers 1, 2 and 3} | |
247 | ("foo" bar 3.1415) ; @r{a string, a symbol and a real number} | |
248 | () ; @r{the empty list} | |
249 | @end lisp | |
250 | ||
251 | The last example needs a bit more explanation. A list with no elements, | |
252 | called the @dfn{empty list}, is special in some ways. It is used for | |
253 | terminating lists by storing it into the cdr of the last pair that makes | |
254 | up a list. An example will clear that up: | |
255 | ||
256 | @lisp | |
257 | (car '(1)) | |
258 | @result{} | |
259 | 1 | |
260 | (cdr '(1)) | |
261 | @result{} | |
262 | () | |
263 | @end lisp | |
264 | ||
265 | This example also shows that lists have to be quoted (REFFIXME) when | |
266 | written, because they would otherwise be mistakingly taken as procedure | |
267 | applications (@pxref{Simple Invocation}). | |
268 | ||
269 | ||
270 | @node List Predicates | |
271 | @subsubsection List Predicates | |
272 | ||
273 | Often it is useful to test whether a given Scheme object is a list or | |
274 | not. List-processing procedures could use this information to test | |
275 | whether their input is valid, or they could do different things | |
276 | depending on the datatype of their arguments. | |
277 | ||
278 | @rnindex list? | |
279 | @deffn {Scheme Procedure} list? x | |
280 | @deffnx {C Function} scm_list_p (x) | |
281 | Return @code{#t} iff @var{x} is a proper list, else @code{#f}. | |
282 | @end deffn | |
283 | ||
284 | The predicate @code{null?} is often used in list-processing code to | |
285 | tell whether a given list has run out of elements. That is, a loop | |
286 | somehow deals with the elements of a list until the list satisfies | |
287 | @code{null?}. Then, the algorithm terminates. | |
288 | ||
289 | @rnindex null? | |
290 | @deffn {Scheme Procedure} null? x | |
291 | @deffnx {C Function} scm_null_p (x) | |
292 | Return @code{#t} iff @var{x} is the empty list, else @code{#f}. | |
293 | @end deffn | |
294 | ||
7f4c83e3 MV |
295 | @deftypefn {C Function} int scm_is_null (SCM x) |
296 | Return 1 when @var{x} is the empty list; otherwise return 0. | |
297 | @end deftypefn | |
298 | ||
299 | ||
07d83abe MV |
300 | @node List Constructors |
301 | @subsubsection List Constructors | |
302 | ||
303 | This section describes the procedures for constructing new lists. | |
304 | @code{list} simply returns a list where the elements are the arguments, | |
305 | @code{cons*} is similar, but the last argument is stored in the cdr of | |
306 | the last pair of the list. | |
307 | ||
308 | @c C Function scm_list(rest) used to be documented here, but it's a | |
309 | @c no-op since it does nothing but return the list the caller must | |
310 | @c have already created. | |
311 | @c | |
312 | @deffn {Scheme Procedure} list elem1 @dots{} elemN | |
313 | @deffnx {C Function} scm_list_1 (elem1) | |
314 | @deffnx {C Function} scm_list_2 (elem1, elem2) | |
315 | @deffnx {C Function} scm_list_3 (elem1, elem2, elem3) | |
316 | @deffnx {C Function} scm_list_4 (elem1, elem2, elem3, elem4) | |
317 | @deffnx {C Function} scm_list_5 (elem1, elem2, elem3, elem4, elem5) | |
318 | @deffnx {C Function} scm_list_n (elem1, @dots{}, elemN, @nicode{SCM_UNDEFINED}) | |
319 | @rnindex list | |
320 | Return a new list containing elements @var{elem1} to @var{elemN}. | |
321 | ||
322 | @code{scm_list_n} takes a variable number of arguments, terminated by | |
323 | the special @code{SCM_UNDEFINED}. That final @code{SCM_UNDEFINED} is | |
324 | not included in the list. None of @var{elem1} to @var{elemN} can | |
325 | themselves be @code{SCM_UNDEFINED}, or @code{scm_list_n} will | |
326 | terminate at that point. | |
327 | @end deffn | |
328 | ||
329 | @c C Function scm_cons_star(arg1,rest) used to be documented here, | |
330 | @c but it's not really a useful interface, since it expects the | |
331 | @c caller to have already consed up all but the first argument | |
332 | @c already. | |
333 | @c | |
334 | @deffn {Scheme Procedure} cons* arg1 arg2 @dots{} | |
335 | Like @code{list}, but the last arg provides the tail of the | |
336 | constructed list, returning @code{(cons @var{arg1} (cons | |
337 | @var{arg2} (cons @dots{} @var{argn})))}. Requires at least one | |
338 | argument. If given one argument, that argument is returned as | |
339 | result. This function is called @code{list*} in some other | |
340 | Schemes and in Common LISP. | |
341 | @end deffn | |
342 | ||
343 | @deffn {Scheme Procedure} list-copy lst | |
344 | @deffnx {C Function} scm_list_copy (lst) | |
345 | Return a (newly-created) copy of @var{lst}. | |
346 | @end deffn | |
347 | ||
348 | @deffn {Scheme Procedure} make-list n [init] | |
349 | Create a list containing of @var{n} elements, where each element is | |
350 | initialized to @var{init}. @var{init} defaults to the empty list | |
351 | @code{()} if not given. | |
352 | @end deffn | |
353 | ||
354 | Note that @code{list-copy} only makes a copy of the pairs which make up | |
355 | the spine of the lists. The list elements are not copied, which means | |
356 | that modifying the elements of the new list also modifies the elements | |
357 | of the old list. On the other hand, applying procedures like | |
358 | @code{set-cdr!} or @code{delv!} to the new list will not alter the old | |
359 | list. If you also need to copy the list elements (making a deep copy), | |
360 | use the procedure @code{copy-tree} (@pxref{Copying}). | |
361 | ||
362 | @node List Selection | |
363 | @subsubsection List Selection | |
364 | ||
365 | These procedures are used to get some information about a list, or to | |
366 | retrieve one or more elements of a list. | |
367 | ||
368 | @rnindex length | |
369 | @deffn {Scheme Procedure} length lst | |
370 | @deffnx {C Function} scm_length (lst) | |
371 | Return the number of elements in list @var{lst}. | |
372 | @end deffn | |
373 | ||
374 | @deffn {Scheme Procedure} last-pair lst | |
375 | @deffnx {C Function} scm_last_pair (lst) | |
cdf1ad3b | 376 | Return the last pair in @var{lst}, signalling an error if |
07d83abe MV |
377 | @var{lst} is circular. |
378 | @end deffn | |
379 | ||
380 | @rnindex list-ref | |
381 | @deffn {Scheme Procedure} list-ref list k | |
382 | @deffnx {C Function} scm_list_ref (list, k) | |
383 | Return the @var{k}th element from @var{list}. | |
384 | @end deffn | |
385 | ||
386 | @rnindex list-tail | |
387 | @deffn {Scheme Procedure} list-tail lst k | |
388 | @deffnx {Scheme Procedure} list-cdr-ref lst k | |
389 | @deffnx {C Function} scm_list_tail (lst, k) | |
390 | Return the "tail" of @var{lst} beginning with its @var{k}th element. | |
391 | The first element of the list is considered to be element 0. | |
392 | ||
393 | @code{list-tail} and @code{list-cdr-ref} are identical. It may help to | |
394 | think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list, | |
395 | or returning the results of cdring @var{k} times down @var{lst}. | |
396 | @end deffn | |
397 | ||
398 | @deffn {Scheme Procedure} list-head lst k | |
399 | @deffnx {C Function} scm_list_head (lst, k) | |
400 | Copy the first @var{k} elements from @var{lst} into a new list, and | |
401 | return it. | |
402 | @end deffn | |
403 | ||
404 | @node Append/Reverse | |
405 | @subsubsection Append and Reverse | |
406 | ||
407 | @code{append} and @code{append!} are used to concatenate two or more | |
408 | lists in order to form a new list. @code{reverse} and @code{reverse!} | |
409 | return lists with the same elements as their arguments, but in reverse | |
410 | order. The procedure variants with an @code{!} directly modify the | |
411 | pairs which form the list, whereas the other procedures create new | |
412 | pairs. This is why you should be careful when using the side-effecting | |
413 | variants. | |
414 | ||
415 | @rnindex append | |
416 | @deffn {Scheme Procedure} append lst1 @dots{} lstN | |
417 | @deffnx {Scheme Procedure} append! lst1 @dots{} lstN | |
418 | @deffnx {C Function} scm_append (lstlst) | |
419 | @deffnx {C Function} scm_append_x (lstlst) | |
420 | Return a list comprising all the elements of lists @var{lst1} to | |
421 | @var{lstN}. | |
422 | ||
423 | @lisp | |
424 | (append '(x) '(y)) @result{} (x y) | |
425 | (append '(a) '(b c d)) @result{} (a b c d) | |
426 | (append '(a (b)) '((c))) @result{} (a (b) (c)) | |
427 | @end lisp | |
428 | ||
429 | The last argument @var{lstN} may actually be any object; an improper | |
430 | list results if the last argument is not a proper list. | |
431 | ||
432 | @lisp | |
433 | (append '(a b) '(c . d)) @result{} (a b c . d) | |
434 | (append '() 'a) @result{} a | |
435 | @end lisp | |
436 | ||
437 | @code{append} doesn't modify the given lists, but the return may share | |
438 | structure with the final @var{lstN}. @code{append!} modifies the | |
439 | given lists to form its return. | |
440 | ||
441 | For @code{scm_append} and @code{scm_append_x}, @var{lstlst} is a list | |
442 | of the list operands @var{lst1} @dots{} @var{lstN}. That @var{lstlst} | |
443 | itself is not modified or used in the return. | |
444 | @end deffn | |
445 | ||
446 | @rnindex reverse | |
447 | @deffn {Scheme Procedure} reverse lst | |
448 | @deffnx {Scheme Procedure} reverse! lst [newtail] | |
449 | @deffnx {C Function} scm_reverse (lst) | |
450 | @deffnx {C Function} scm_reverse_x (lst, newtail) | |
451 | Return a list comprising the elements of @var{lst}, in reverse order. | |
452 | ||
453 | @code{reverse} constructs a new list, @code{reverse!} modifies | |
454 | @var{lst} in constructing its return. | |
455 | ||
456 | For @code{reverse!}, the optional @var{newtail} is appended to to the | |
457 | result. @var{newtail} isn't reversed, it simply becomes the list | |
458 | tail. For @code{scm_reverse_x}, the @var{newtail} parameter is | |
459 | mandatory, but can be @code{SCM_EOL} if no further tail is required. | |
460 | @end deffn | |
461 | ||
462 | @node List Modification | |
463 | @subsubsection List Modification | |
464 | ||
465 | The following procedures modify an existing list, either by changing | |
466 | elements of the list, or by changing the list structure itself. | |
467 | ||
468 | @deffn {Scheme Procedure} list-set! list k val | |
469 | @deffnx {C Function} scm_list_set_x (list, k, val) | |
470 | Set the @var{k}th element of @var{list} to @var{val}. | |
471 | @end deffn | |
472 | ||
473 | @deffn {Scheme Procedure} list-cdr-set! list k val | |
474 | @deffnx {C Function} scm_list_cdr_set_x (list, k, val) | |
475 | Set the @var{k}th cdr of @var{list} to @var{val}. | |
476 | @end deffn | |
477 | ||
478 | @deffn {Scheme Procedure} delq item lst | |
479 | @deffnx {C Function} scm_delq (item, lst) | |
480 | Return a newly-created copy of @var{lst} with elements | |
481 | @code{eq?} to @var{item} removed. This procedure mirrors | |
482 | @code{memq}: @code{delq} compares elements of @var{lst} against | |
483 | @var{item} with @code{eq?}. | |
484 | @end deffn | |
485 | ||
486 | @deffn {Scheme Procedure} delv item lst | |
487 | @deffnx {C Function} scm_delv (item, lst) | |
488 | Return a newly-created copy of @var{lst} with elements | |
489 | @code{eqv?} to @var{item} removed. This procedure mirrors | |
490 | @code{memv}: @code{delv} compares elements of @var{lst} against | |
491 | @var{item} with @code{eqv?}. | |
492 | @end deffn | |
493 | ||
494 | @deffn {Scheme Procedure} delete item lst | |
495 | @deffnx {C Function} scm_delete (item, lst) | |
496 | Return a newly-created copy of @var{lst} with elements | |
497 | @code{equal?} to @var{item} removed. This procedure mirrors | |
498 | @code{member}: @code{delete} compares elements of @var{lst} | |
499 | against @var{item} with @code{equal?}. | |
500 | @end deffn | |
501 | ||
502 | @deffn {Scheme Procedure} delq! item lst | |
503 | @deffnx {Scheme Procedure} delv! item lst | |
504 | @deffnx {Scheme Procedure} delete! item lst | |
505 | @deffnx {C Function} scm_delq_x (item, lst) | |
506 | @deffnx {C Function} scm_delv_x (item, lst) | |
507 | @deffnx {C Function} scm_delete_x (item, lst) | |
508 | These procedures are destructive versions of @code{delq}, @code{delv} | |
509 | and @code{delete}: they modify the pointers in the existing @var{lst} | |
510 | rather than creating a new list. Caveat evaluator: Like other | |
511 | destructive list functions, these functions cannot modify the binding of | |
512 | @var{lst}, and so cannot be used to delete the first element of | |
513 | @var{lst} destructively. | |
514 | @end deffn | |
515 | ||
516 | @deffn {Scheme Procedure} delq1! item lst | |
517 | @deffnx {C Function} scm_delq1_x (item, lst) | |
518 | Like @code{delq!}, but only deletes the first occurrence of | |
519 | @var{item} from @var{lst}. Tests for equality using | |
520 | @code{eq?}. See also @code{delv1!} and @code{delete1!}. | |
521 | @end deffn | |
522 | ||
523 | @deffn {Scheme Procedure} delv1! item lst | |
524 | @deffnx {C Function} scm_delv1_x (item, lst) | |
525 | Like @code{delv!}, but only deletes the first occurrence of | |
526 | @var{item} from @var{lst}. Tests for equality using | |
527 | @code{eqv?}. See also @code{delq1!} and @code{delete1!}. | |
528 | @end deffn | |
529 | ||
530 | @deffn {Scheme Procedure} delete1! item lst | |
531 | @deffnx {C Function} scm_delete1_x (item, lst) | |
532 | Like @code{delete!}, but only deletes the first occurrence of | |
533 | @var{item} from @var{lst}. Tests for equality using | |
534 | @code{equal?}. See also @code{delq1!} and @code{delv1!}. | |
535 | @end deffn | |
536 | ||
537 | @deffn {Scheme Procedure} filter pred lst | |
538 | @deffnx {Scheme Procedure} filter! pred lst | |
539 | Return a list containing all elements from @var{lst} which satisfy the | |
540 | predicate @var{pred}. The elements in the result list have the same | |
541 | order as in @var{lst}. The order in which @var{pred} is applied to | |
542 | the list elements is not specified. | |
543 | ||
544 | @code{filter!} is allowed, but not required to modify the structure of | |
545 | @end deffn | |
546 | ||
547 | @node List Searching | |
548 | @subsubsection List Searching | |
549 | ||
550 | The following procedures search lists for particular elements. They use | |
551 | different comparison predicates for comparing list elements with the | |
552 | object to be searched. When they fail, they return @code{#f}, otherwise | |
553 | they return the sublist whose car is equal to the search object, where | |
554 | equality depends on the equality predicate used. | |
555 | ||
556 | @rnindex memq | |
557 | @deffn {Scheme Procedure} memq x lst | |
558 | @deffnx {C Function} scm_memq (x, lst) | |
559 | Return the first sublist of @var{lst} whose car is @code{eq?} | |
560 | to @var{x} where the sublists of @var{lst} are the non-empty | |
561 | lists returned by @code{(list-tail @var{lst} @var{k})} for | |
562 | @var{k} less than the length of @var{lst}. If @var{x} does not | |
563 | occur in @var{lst}, then @code{#f} (not the empty list) is | |
564 | returned. | |
565 | @end deffn | |
566 | ||
567 | @rnindex memv | |
568 | @deffn {Scheme Procedure} memv x lst | |
569 | @deffnx {C Function} scm_memv (x, lst) | |
570 | Return the first sublist of @var{lst} whose car is @code{eqv?} | |
571 | to @var{x} where the sublists of @var{lst} are the non-empty | |
572 | lists returned by @code{(list-tail @var{lst} @var{k})} for | |
573 | @var{k} less than the length of @var{lst}. If @var{x} does not | |
574 | occur in @var{lst}, then @code{#f} (not the empty list) is | |
575 | returned. | |
576 | @end deffn | |
577 | ||
578 | @rnindex member | |
579 | @deffn {Scheme Procedure} member x lst | |
580 | @deffnx {C Function} scm_member (x, lst) | |
581 | Return the first sublist of @var{lst} whose car is | |
582 | @code{equal?} to @var{x} where the sublists of @var{lst} are | |
583 | the non-empty lists returned by @code{(list-tail @var{lst} | |
584 | @var{k})} for @var{k} less than the length of @var{lst}. If | |
585 | @var{x} does not occur in @var{lst}, then @code{#f} (not the | |
586 | empty list) is returned. | |
587 | @end deffn | |
588 | ||
589 | ||
590 | @node List Mapping | |
591 | @subsubsection List Mapping | |
592 | ||
593 | List processing is very convenient in Scheme because the process of | |
594 | iterating over the elements of a list can be highly abstracted. The | |
595 | procedures in this section are the most basic iterating procedures for | |
596 | lists. They take a procedure and one or more lists as arguments, and | |
597 | apply the procedure to each element of the list. They differ in their | |
598 | return value. | |
599 | ||
600 | @rnindex map | |
601 | @c begin (texi-doc-string "guile" "map") | |
602 | @deffn {Scheme Procedure} map proc arg1 arg2 @dots{} | |
603 | @deffnx {Scheme Procedure} map-in-order proc arg1 arg2 @dots{} | |
604 | @deffnx {C Function} scm_map (proc, arg1, args) | |
605 | Apply @var{proc} to each element of the list @var{arg1} (if only two | |
606 | arguments are given), or to the corresponding elements of the argument | |
607 | lists (if more than two arguments are given). The result(s) of the | |
608 | procedure applications are saved and returned in a list. For | |
609 | @code{map}, the order of procedure applications is not specified, | |
610 | @code{map-in-order} applies the procedure from left to right to the list | |
611 | elements. | |
612 | @end deffn | |
613 | ||
614 | @rnindex for-each | |
615 | @c begin (texi-doc-string "guile" "for-each") | |
616 | @deffn {Scheme Procedure} for-each proc arg1 arg2 @dots{} | |
617 | Like @code{map}, but the procedure is always applied from left to right, | |
618 | and the result(s) of the procedure applications are thrown away. The | |
619 | return value is not specified. | |
620 | @end deffn | |
621 | ||
622 | ||
623 | @node Vectors | |
624 | @subsection Vectors | |
625 | @tpindex Vectors | |
626 | ||
627 | Vectors are sequences of Scheme objects. Unlike lists, the length of a | |
628 | vector, once the vector is created, cannot be changed. The advantage of | |
629 | vectors over lists is that the time required to access one element of a vector | |
630 | given its @dfn{position} (synonymous with @dfn{index}), a zero-origin number, | |
631 | is constant, whereas lists have an access time linear to the position of the | |
632 | accessed element in the list. | |
633 | ||
e6b226b9 MV |
634 | Vectors can contain any kind of Scheme object; it is even possible to |
635 | have different types of objects in the same vector. For vectors | |
636 | containing vectors, you may wish to use arrays, instead. Note, too, | |
637 | that vectors are the special case of non-uniform, one-dimensional, | |
638 | zero-origin arrays and that most array procedures operate happily on | |
639 | vectors (@pxref{Arrays}). | |
07d83abe MV |
640 | |
641 | @menu | |
642 | * Vector Syntax:: Read syntax for vectors. | |
643 | * Vector Creation:: Dynamic vector creation and validation. | |
644 | * Vector Accessors:: Accessing and modifying vector contents. | |
645 | @end menu | |
646 | ||
647 | ||
648 | @node Vector Syntax | |
649 | @subsubsection Read Syntax for Vectors | |
650 | ||
651 | Vectors can literally be entered in source code, just like strings, | |
652 | characters or some of the other data types. The read syntax for vectors | |
653 | is as follows: A sharp sign (@code{#}), followed by an opening | |
654 | parentheses, all elements of the vector in their respective read syntax, | |
655 | and finally a closing parentheses. The following are examples of the | |
656 | read syntax for vectors; where the first vector only contains numbers | |
657 | and the second three different object types: a string, a symbol and a | |
658 | number in hexadecimal notation. | |
659 | ||
660 | @lisp | |
661 | #(1 2 3) | |
662 | #("Hello" foo #xdeadbeef) | |
663 | @end lisp | |
664 | ||
665 | Like lists, vectors have to be quoted (REFFIXME): | |
666 | ||
667 | @lisp | |
668 | '#(a b c) @result{} #(a b c) | |
669 | @end lisp | |
670 | ||
671 | @node Vector Creation | |
672 | @subsubsection Dynamic Vector Creation and Validation | |
673 | ||
674 | Instead of creating a vector implicitly by using the read syntax just | |
675 | described, you can create a vector dynamically by calling one of the | |
676 | @code{vector} and @code{list->vector} primitives with the list of Scheme | |
677 | values that you want to place into a vector. The size of the vector | |
678 | thus created is determined implicitly by the number of arguments given. | |
679 | ||
680 | @rnindex vector | |
681 | @rnindex list->vector | |
682 | @deffn {Scheme Procedure} vector . l | |
683 | @deffnx {Scheme Procedure} list->vector l | |
684 | @deffnx {C Function} scm_vector (l) | |
685 | Return a newly allocated vector composed of the | |
686 | given arguments. Analogous to @code{list}. | |
687 | ||
688 | @lisp | |
689 | (vector 'a 'b 'c) @result{} #(a b c) | |
690 | @end lisp | |
691 | @end deffn | |
692 | ||
693 | (As an aside, an interesting implementation detail is that the Guile | |
694 | reader reads the @code{#(@dots{})} syntax by reading everything but the | |
695 | initial @code{#} as a @emph{list}, and then passing the list that | |
696 | results to @code{list->vector}. Notice how neatly this fits with the | |
697 | similarity between the read (and print) syntaxes for lists and vectors.) | |
698 | ||
699 | The inverse operation is @code{vector->list}: | |
700 | ||
701 | @rnindex vector->list | |
702 | @deffn {Scheme Procedure} vector->list v | |
703 | @deffnx {C Function} scm_vector_to_list (v) | |
704 | Return a newly allocated list composed of the elements of @var{v}. | |
705 | ||
706 | @lisp | |
707 | (vector->list '#(dah dah didah)) @result{} (dah dah didah) | |
708 | (list->vector '(dididit dah)) @result{} #(dididit dah) | |
709 | @end lisp | |
710 | @end deffn | |
711 | ||
712 | To allocate a vector with an explicitly specified size, use | |
713 | @code{make-vector}. With this primitive you can also specify an initial | |
714 | value for the vector elements (the same value for all elements, that | |
715 | is): | |
716 | ||
717 | @rnindex make-vector | |
718 | @deffn {Scheme Procedure} make-vector k [fill] | |
719 | @deffnx {C Function} scm_make_vector (k, fill) | |
720 | Return a newly allocated vector of @var{k} elements. If a | |
721 | second argument is given, then each position is initialized to | |
722 | @var{fill}. Otherwise the initial contents of each position is | |
723 | unspecified. | |
724 | @end deffn | |
725 | ||
726 | To check whether an arbitrary Scheme value @emph{is} a vector, use the | |
727 | @code{vector?} primitive: | |
728 | ||
729 | @rnindex vector? | |
730 | @deffn {Scheme Procedure} vector? obj | |
731 | @deffnx {C Function} scm_vector_p (obj) | |
732 | Return @code{#t} if @var{obj} is a vector, otherwise return | |
733 | @code{#f}. | |
734 | @end deffn | |
735 | ||
736 | ||
737 | @node Vector Accessors | |
738 | @subsubsection Accessing and Modifying Vector Contents | |
739 | ||
740 | @code{vector-length} and @code{vector-ref} return information about a | |
741 | given vector, respectively its size and the elements that are contained | |
742 | in the vector. | |
743 | ||
744 | @rnindex vector-length | |
745 | @deffn {Scheme Procedure} vector-length vector | |
746 | @deffnx {C Function} scm_vector_length vector | |
747 | Return the number of elements in @var{vector} as an exact integer. | |
748 | @end deffn | |
749 | ||
750 | @rnindex vector-ref | |
751 | @deffn {Scheme Procedure} vector-ref vector k | |
752 | @deffnx {C Function} scm_vector_ref vector k | |
753 | Return the contents of position @var{k} of @var{vector}. | |
754 | @var{k} must be a valid index of @var{vector}. | |
755 | @lisp | |
756 | (vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8 | |
757 | (vector-ref '#(1 1 2 3 5 8 13 21) | |
758 | (let ((i (round (* 2 (acos -1))))) | |
759 | (if (inexact? i) | |
760 | (inexact->exact i) | |
761 | i))) @result{} 13 | |
762 | @end lisp | |
763 | @end deffn | |
764 | ||
765 | A vector created by one of the dynamic vector constructor procedures | |
766 | (@pxref{Vector Creation}) can be modified using the following | |
767 | procedures. | |
768 | ||
769 | @emph{NOTE:} According to R5RS, it is an error to use any of these | |
770 | procedures on a literally read vector, because such vectors should be | |
771 | considered as constants. Currently, however, Guile does not detect this | |
772 | error. | |
773 | ||
774 | @rnindex vector-set! | |
775 | @deffn {Scheme Procedure} vector-set! vector k obj | |
776 | @deffnx {C Function} scm_vector_set_x vector k obj | |
777 | Store @var{obj} in position @var{k} of @var{vector}. | |
778 | @var{k} must be a valid index of @var{vector}. | |
779 | The value returned by @samp{vector-set!} is unspecified. | |
780 | @lisp | |
781 | (let ((vec (vector 0 '(2 2 2 2) "Anna"))) | |
782 | (vector-set! vec 1 '("Sue" "Sue")) | |
783 | vec) @result{} #(0 ("Sue" "Sue") "Anna") | |
784 | @end lisp | |
785 | @end deffn | |
786 | ||
787 | @rnindex vector-fill! | |
788 | @deffn {Scheme Procedure} vector-fill! v fill | |
789 | @deffnx {C Function} scm_vector_fill_x (v, fill) | |
790 | Store @var{fill} in every position of @var{vector}. The value | |
791 | returned by @code{vector-fill!} is unspecified. | |
792 | @end deffn | |
793 | ||
794 | @deffn {Scheme Procedure} vector-move-left! vec1 start1 end1 vec2 start2 | |
795 | @deffnx {C Function} scm_vector_move_left_x (vec1, start1, end1, vec2, start2) | |
796 | Copy elements from @var{vec1}, positions @var{start1} to @var{end1}, | |
797 | to @var{vec2} starting at position @var{start2}. @var{start1} and | |
798 | @var{start2} are inclusive indices; @var{end1} is exclusive. | |
799 | ||
800 | @code{vector-move-left!} copies elements in leftmost order. | |
801 | Therefore, in the case where @var{vec1} and @var{vec2} refer to the | |
802 | same vector, @code{vector-move-left!} is usually appropriate when | |
803 | @var{start1} is greater than @var{start2}. | |
804 | @end deffn | |
805 | ||
806 | @deffn {Scheme Procedure} vector-move-right! vec1 start1 end1 vec2 start2 | |
807 | @deffnx {C Function} scm_vector_move_right_x (vec1, start1, end1, vec2, start2) | |
808 | Copy elements from @var{vec1}, positions @var{start1} to @var{end1}, | |
809 | to @var{vec2} starting at position @var{start2}. @var{start1} and | |
810 | @var{start2} are inclusive indices; @var{end1} is exclusive. | |
811 | ||
812 | @code{vector-move-right!} copies elements in rightmost order. | |
813 | Therefore, in the case where @var{vec1} and @var{vec2} refer to the | |
814 | same vector, @code{vector-move-right!} is usually appropriate when | |
815 | @var{start1} is less than @var{start2}. | |
816 | @end deffn | |
817 | ||
e6b226b9 MV |
818 | @node Uniform Vectors |
819 | @subsection Uniform Vectors | |
07d83abe | 820 | |
e6b226b9 MV |
821 | A uniform vector is a vector elements are all of a single type. Guile |
822 | offers uniform vectors for signed and unsigned 8-bit, 16-bit, 32-bit, | |
823 | and 64-bit integers and for two sizes of floating point values. | |
07d83abe | 824 | |
e6b226b9 MV |
825 | Strings could be regarded as uniform vectors of characters, |
826 | @xref{Strings}. Likewise, bit vectors could be regarded as uniform | |
827 | vectors of bits, @xref{Bit Vectors}. Both are sufficiently different | |
828 | that the procedures described here do not apply to these two data types. | |
829 | However, both strings and bit vectors are arrays, @xref{Arrays}. | |
07d83abe | 830 | |
e6b226b9 MV |
831 | Uniform vectors are the special case of one-dimensional, uniform, |
832 | zero-origin array. | |
07d83abe | 833 | |
e6b226b9 MV |
834 | Uniform vectors can be useful since they consume less memory than the |
835 | non-uniform, general vectors. Also, since the types they can store | |
836 | correspond directly to C types, it is easier to work with them | |
837 | efficiently on a low level. Consider image processing as an example, | |
838 | where you want to apply a filter to some image. While you could store | |
839 | the pixels of an image in a general vector and write a general | |
840 | convolution function, things are much more efficient with uniform | |
841 | vectors: the convolution function knows that all pixels are unsigned | |
842 | 8-bit values (say), and can use a very tight inner loop. (That is, when | |
843 | it is written in C.) | |
07d83abe | 844 | |
e6b226b9 MV |
845 | Procedures similar to the vector procedures (@pxref{Vectors}) are |
846 | provided for handling these homogeneous vectors, but they are distinct | |
847 | datatypes and the two cannot be inter-mixed. | |
07d83abe | 848 | |
e6b226b9 MV |
849 | One set of these procedures is a generic one: it works with all types of |
850 | uniform vectors. In addition to that, there is a set of procedures for | |
851 | each type that only works with that type. Unless you really need to the | |
852 | generality of the first set, it is best to use the more specific | |
853 | functions. They might not be that much faster, but their use can serve | |
854 | as a kind of declaration and makes it easier to optimize later on. | |
07d83abe | 855 | |
e6b226b9 MV |
856 | (Functions for efficiently working with uniform vectors from C are |
857 | listed at the end of this section.) | |
07d83abe | 858 | |
e6b226b9 MV |
859 | The generic set of procedures uses @code{uniform-vector} in its names, |
860 | the specific ones use the tag from the following table. | |
07d83abe | 861 | |
e6b226b9 MV |
862 | @table @nicode |
863 | @item u8 | |
864 | unsigned 8-bit integers | |
07d83abe | 865 | |
e6b226b9 MV |
866 | @item s8 |
867 | signed 8-bit integers | |
07d83abe | 868 | |
e6b226b9 MV |
869 | @item u16 |
870 | unsigned 16-bit integers | |
07d83abe | 871 | |
e6b226b9 MV |
872 | @item s16 |
873 | signed 16-bit integers | |
07d83abe | 874 | |
e6b226b9 MV |
875 | @item u32 |
876 | unsigned 32-bit integers | |
07d83abe | 877 | |
e6b226b9 MV |
878 | @item s32 |
879 | signed 32-bit integers | |
07d83abe | 880 | |
e6b226b9 MV |
881 | @item u64 |
882 | unsigned 64-bit integers | |
07d83abe | 883 | |
e6b226b9 MV |
884 | @item s64 |
885 | signed 64-bit integers | |
07d83abe | 886 | |
e6b226b9 MV |
887 | @item f32 |
888 | the C type @code{float} | |
07d83abe | 889 | |
e6b226b9 MV |
890 | @item f64 |
891 | the C type @code{double} | |
892 | @end table | |
07d83abe | 893 | |
e6b226b9 MV |
894 | The external representation (ie.@: read syntax) for these vectors is |
895 | similar to normal Scheme vectors, but with an additional tag from the | |
896 | tabel above indiciating the vector's type. For example, | |
07d83abe | 897 | |
e6b226b9 MV |
898 | @lisp |
899 | #u16(1 2 3) | |
900 | #f64(3.1415 2.71) | |
901 | @end lisp | |
07d83abe | 902 | |
e6b226b9 MV |
903 | Note that the read syntax for floating-point here conflicts with |
904 | @code{#f} for false. In Standard Scheme one can write @code{(1 #f3)} | |
905 | for a three element list @code{(1 #f 3)}, but for Guile @code{(1 #f3)} | |
906 | is invalid. @code{(1 #f 3)} is almost certainly what one should write | |
907 | anyway to make the intention clear, so this is rarely a problem. | |
908 | ||
909 | @deffn {Scheme Procedure} uniform-vector? obj | |
910 | @deffnx {Scheme Procedure} u8vector? obj | |
911 | @deffnx {Scheme Procedure} s8vector? obj | |
912 | @deffnx {Scheme Procedure} u16vector? obj | |
913 | @deffnx {Scheme Procedure} s16vector? obj | |
914 | @deffnx {Scheme Procedure} u32vector? obj | |
915 | @deffnx {Scheme Procedure} s32vector? obj | |
916 | @deffnx {Scheme Procedure} u64vector? obj | |
917 | @deffnx {Scheme Procedure} s64vector? obj | |
918 | @deffnx {Scheme Procedure} f32vector? obj | |
919 | @deffnx {Scheme Procedure} f64vector? obj | |
920 | @deffnx {C Function} scm_uniform_vector_p obj | |
921 | @deffnx {C Function} scm_u8vector_p obj | |
922 | @deffnx {C Function} scm_s8vector_p obj | |
923 | @deffnx {C Function} scm_u16vector_p obj | |
924 | @deffnx {C Function} scm_s16vector_p obj | |
925 | @deffnx {C Function} scm_u32vector_p obj | |
926 | @deffnx {C Function} scm_s32vector_p obj | |
927 | @deffnx {C Function} scm_u64vector_p obj | |
928 | @deffnx {C Function} scm_s64vector_p obj | |
929 | @deffnx {C Function} scm_f32vector_p obj | |
930 | @deffnx {C Function} scm_f64vector_p obj | |
931 | Return @code{#t} if @var{obj} is a homogeneous numeric vector of the | |
932 | indicated type. | |
933 | @end deffn | |
934 | ||
935 | @deffn {Scheme Procedure} make-u8vector n [value] | |
936 | @deffnx {Scheme Procedure} make-s8vector n [value] | |
937 | @deffnx {Scheme Procedure} make-u16vector n [value] | |
938 | @deffnx {Scheme Procedure} make-s16vector n [value] | |
939 | @deffnx {Scheme Procedure} make-u32vector n [value] | |
940 | @deffnx {Scheme Procedure} make-s32vector n [value] | |
941 | @deffnx {Scheme Procedure} make-u64vector n [value] | |
942 | @deffnx {Scheme Procedure} make-s64vector n [value] | |
943 | @deffnx {Scheme Procedure} make-f32vector n [value] | |
944 | @deffnx {Scheme Procedure} make-f64vector n [value] | |
945 | @deffnx {C Function} scm_make_u8vector n [value] | |
946 | @deffnx {C Function} scm_make_s8vector n [value] | |
947 | @deffnx {C Function} scm_make_u16vector n [value] | |
948 | @deffnx {C Function} scm_make_s16vector n [value] | |
949 | @deffnx {C Function} scm_make_u32vector n [value] | |
950 | @deffnx {C Function} scm_make_s32vector n [value] | |
951 | @deffnx {C Function} scm_make_u64vector n [value] | |
952 | @deffnx {C Function} scm_make_s64vector n [value] | |
953 | @deffnx {C Function} scm_make_f32vector n [value] | |
954 | @deffnx {C Function} scm_make_f64vector n [value] | |
955 | Return a newly allocated homogeneous numeric vector holding @var{n} | |
956 | elements of the indicated type. If @var{value} is given, the vector | |
957 | is initialized with that value, otherwise the contents are | |
958 | unspecified. | |
959 | @end deffn | |
07d83abe | 960 | |
e6b226b9 MV |
961 | @deffn {Scheme Procedure} u8vector value @dots{} |
962 | @deffnx {Scheme Procedure} s8vector value @dots{} | |
963 | @deffnx {Scheme Procedure} u16vector value @dots{} | |
964 | @deffnx {Scheme Procedure} s16vector value @dots{} | |
965 | @deffnx {Scheme Procedure} u32vector value @dots{} | |
966 | @deffnx {Scheme Procedure} s32vector value @dots{} | |
967 | @deffnx {Scheme Procedure} u64vector value @dots{} | |
968 | @deffnx {Scheme Procedure} s64vector value @dots{} | |
969 | @deffnx {Scheme Procedure} f32vector value @dots{} | |
970 | @deffnx {Scheme Procedure} f64vector value @dots{} | |
971 | @deffnx {C Function} scm_u8vector values | |
972 | @deffnx {C Function} scm_s8vector values | |
973 | @deffnx {C Function} scm_u16vector valus | |
974 | @deffnx {C Function} scm_s16vector valus | |
975 | @deffnx {C Function} scm_u32vector valus | |
976 | @deffnx {C Function} scm_s32vector valus | |
977 | @deffnx {C Function} scm_u64vector valus | |
978 | @deffnx {C Function} scm_s64vector valus | |
979 | @deffnx {C Function} scm_f32vector valus | |
980 | @deffnx {C Function} scm_f64vector valus | |
981 | Return a newly allocated homogeneous numeric vector of the indicated | |
982 | type, holding the given parameter @var{value}s. The vector length is | |
983 | the number of parameters given. | |
984 | @end deffn | |
985 | ||
986 | @deffn {Scheme Procedure} uniform-vector-length vec | |
987 | @deffnx {Scheme Procedure} u8vector-length vec | |
988 | @deffnx {Scheme Procedure} s8vector-length vec | |
989 | @deffnx {Scheme Procedure} u16vector-length vec | |
990 | @deffnx {Scheme Procedure} s16vector-length vec | |
991 | @deffnx {Scheme Procedure} u32vector-length vec | |
992 | @deffnx {Scheme Procedure} s32vector-length vec | |
993 | @deffnx {Scheme Procedure} u64vector-length vec | |
994 | @deffnx {Scheme Procedure} s64vector-length vec | |
995 | @deffnx {Scheme Procedure} f32vector-length vec | |
996 | @deffnx {Scheme Procedure} f64vector-length vec | |
997 | @deffnx {C Function} scm_uniform_vector_length vec | |
998 | @deffnx {C Function} scm_u8vector_length vec | |
999 | @deffnx {C Function} scm_s8vector_length vec | |
1000 | @deffnx {C Function} scm_u16vector_length vec | |
1001 | @deffnx {C Function} scm_s16vector_length vec | |
1002 | @deffnx {C Function} scm_u32vector_length vec | |
1003 | @deffnx {C Function} scm_s32vector_length vec | |
1004 | @deffnx {C Function} scm_u64vector_length vec | |
1005 | @deffnx {C Function} scm_s64vector_length vec | |
1006 | @deffnx {C Function} scm_f32vector_length vec | |
1007 | @deffnx {C Function} scm_f64vector_length vec | |
1008 | Return the number of elements in @var{vec}. | |
1009 | @end deffn | |
1010 | ||
1011 | @deffn {Scheme Procedure} uniform-vector-ref vec i | |
1012 | @deffnx {Scheme Procedure} u8vector-ref vec i | |
1013 | @deffnx {Scheme Procedure} s8vector-ref vec i | |
1014 | @deffnx {Scheme Procedure} u16vector-ref vec i | |
1015 | @deffnx {Scheme Procedure} s16vector-ref vec i | |
1016 | @deffnx {Scheme Procedure} u32vector-ref vec i | |
1017 | @deffnx {Scheme Procedure} s32vector-ref vec i | |
1018 | @deffnx {Scheme Procedure} u64vector-ref vec i | |
1019 | @deffnx {Scheme Procedure} s64vector-ref vec i | |
1020 | @deffnx {Scheme Procedure} f32vector-ref vec i | |
1021 | @deffnx {Scheme Procedure} f64vector-ref vec i | |
1022 | @deffnx {C Function} scm_uniform_vector_ref vec i | |
1023 | @deffnx {C Function} scm_u8vector_ref vec i | |
1024 | @deffnx {C Function} scm_s8vector_ref vec i | |
1025 | @deffnx {C Function} scm_u16vector_ref vec i | |
1026 | @deffnx {C Function} scm_s16vector_ref vec i | |
1027 | @deffnx {C Function} scm_u32vector_ref vec i | |
1028 | @deffnx {C Function} scm_s32vector_ref vec i | |
1029 | @deffnx {C Function} scm_u64vector_ref vec i | |
1030 | @deffnx {C Function} scm_s64vector_ref vec i | |
1031 | @deffnx {C Function} scm_f32vector_ref vec i | |
1032 | @deffnx {C Function} scm_f64vector_ref vec i | |
1033 | Return the element at index @var{i} in @var{vec}. The first element | |
1034 | in @var{vec} is index 0. | |
1035 | @end deffn | |
1036 | ||
1037 | @deffn {Scheme Procedure} uniform-vector-set! vec i value | |
1038 | @deffnx {Scheme Procedure} u8vector-set! vec i value | |
1039 | @deffnx {Scheme Procedure} s8vector-set! vec i value | |
1040 | @deffnx {Scheme Procedure} u16vector-set! vec i value | |
1041 | @deffnx {Scheme Procedure} s16vector-set! vec i value | |
1042 | @deffnx {Scheme Procedure} u32vector-set! vec i value | |
1043 | @deffnx {Scheme Procedure} s32vector-set! vec i value | |
1044 | @deffnx {Scheme Procedure} u64vector-set! vec i value | |
1045 | @deffnx {Scheme Procedure} s64vector-set! vec i value | |
1046 | @deffnx {Scheme Procedure} f32vector-set! vec i value | |
1047 | @deffnx {Scheme Procedure} f64vector-set! vec i value | |
1048 | @deffnx {C Function} scm_uniform_vector_set_x vec i value | |
1049 | @deffnx {C Function} scm_u8vector_set_x vec i value | |
1050 | @deffnx {C Function} scm_s8vector_set_x vec i value | |
1051 | @deffnx {C Function} scm_u16vector_set_x vec i value | |
1052 | @deffnx {C Function} scm_s16vector_set_x vec i value | |
1053 | @deffnx {C Function} scm_u32vector_set_x vec i value | |
1054 | @deffnx {C Function} scm_s32vector_set_x vec i value | |
1055 | @deffnx {C Function} scm_u64vector_set_x vec i value | |
1056 | @deffnx {C Function} scm_s64vector_set_x vec i value | |
1057 | @deffnx {C Function} scm_f32vector_set_x vec i value | |
1058 | @deffnx {C Function} scm_f64vector_set_x vec i value | |
1059 | Set the element at index @var{i} in @var{vec} to @var{value}. The | |
1060 | first element in @var{vec} is index 0. The return value is | |
1061 | unspecified. | |
1062 | @end deffn | |
07d83abe | 1063 | |
e6b226b9 MV |
1064 | @deffn {Scheme Procedure} uniform-vector->list vec |
1065 | @deffnx {Scheme Procedure} u8vector->list vec | |
1066 | @deffnx {Scheme Procedure} s8vector->list vec | |
1067 | @deffnx {Scheme Procedure} u16vector->list vec | |
1068 | @deffnx {Scheme Procedure} s16vector->list vec | |
1069 | @deffnx {Scheme Procedure} u32vector->list vec | |
1070 | @deffnx {Scheme Procedure} s32vector->list vec | |
1071 | @deffnx {Scheme Procedure} u64vector->list vec | |
1072 | @deffnx {Scheme Procedure} s64vector->list vec | |
1073 | @deffnx {Scheme Procedure} f32vector->list vec | |
1074 | @deffnx {Scheme Procedure} f64vector->list vec | |
1075 | @deffnx {C Function} scm_uniform_vector_to_list vec | |
1076 | @deffnx {C Function} scm_u8vector_to_list vec | |
1077 | @deffnx {C Function} scm_s8vector_to_list vec | |
1078 | @deffnx {C Function} scm_u16vector_to_list vec | |
1079 | @deffnx {C Function} scm_s16vector_to_list vec | |
1080 | @deffnx {C Function} scm_u32vector_to_list vec | |
1081 | @deffnx {C Function} scm_s32vector_to_list vec | |
1082 | @deffnx {C Function} scm_u64vector_to_list vec | |
1083 | @deffnx {C Function} scm_s64vector_to_list vec | |
1084 | @deffnx {C Function} scm_f32vector_to_list vec | |
1085 | @deffnx {C Function} scm_f64vector_to_list vec | |
1086 | Return a newly allocated list holding all elements of @var{vec}. | |
1087 | @end deffn | |
1088 | ||
1089 | @deffn {Scheme Procedure} list->u8vector lst | |
1090 | @deffnx {Scheme Procedure} list->s8vector lst | |
1091 | @deffnx {Scheme Procedure} list->u16vector lst | |
1092 | @deffnx {Scheme Procedure} list->s16vector lst | |
1093 | @deffnx {Scheme Procedure} list->u32vector lst | |
1094 | @deffnx {Scheme Procedure} list->s32vector lst | |
1095 | @deffnx {Scheme Procedure} list->u64vector lst | |
1096 | @deffnx {Scheme Procedure} list->s64vector lst | |
1097 | @deffnx {Scheme Procedure} list->f32vector lst | |
1098 | @deffnx {Scheme Procedure} list->f64vector lst | |
1099 | @deffnx {C Function} scm_list_to_u8vector lst | |
1100 | @deffnx {C Function} scm_list_to_s8vector lst | |
1101 | @deffnx {C Function} scm_list_to_u16vector lst | |
1102 | @deffnx {C Function} scm_list_to_s16vector lst | |
1103 | @deffnx {C Function} scm_list_to_u32vector lst | |
1104 | @deffnx {C Function} scm_list_to_s32vector lst | |
1105 | @deffnx {C Function} scm_list_to_u64vector lst | |
1106 | @deffnx {C Function} scm_list_to_s64vector lst | |
1107 | @deffnx {C Function} scm_list_to_f32vector lst | |
1108 | @deffnx {C Function} scm_list_to_f64vector lst | |
1109 | Return a newly allocated homogeneous numeric vector of the indicated type, | |
1110 | initialized with the elements of the list @var{lst}. | |
1111 | @end deffn | |
1112 | ||
1113 | @deftypefn {C Function} int scm_is_uniform_vector (SCM uvec) | |
1114 | Return @code{1} when @var{uvec} is a uniform vector, @code{0} otherwise. | |
1115 | @end deftypefn | |
07d83abe | 1116 | |
e6b226b9 MV |
1117 | @deftypefn {C Function} {void *} scm_uniform_vector_elements (SCM uvec) |
1118 | @deftypefnx {C Function} {scm_t_uint8 *} scm_u8vector_elements (SCM uvec) | |
1119 | @deftypefnx {C Function} {scm_t_int8 *} scm_s8vector_elements (SCM uvec) | |
1120 | @deftypefnx {C Function} {scm_t_uint16 *} scm_u16vector_elements (SCM uvec) | |
1121 | @deftypefnx {C Function} {scm_t_int16 *} scm_s16vector_elements (SCM uvec) | |
1122 | @deftypefnx {C Function} {scm_t_uint32 *} scm_u32vector_elements (SCM uvec) | |
1123 | @deftypefnx {C Function} {scm_t_int32 *} scm_s32vector_elements (SCM uvec) | |
1124 | @deftypefnx {C Function} {scm_t_uint64 *} scm_u64vector_elements (SCM uvec) | |
1125 | @deftypefnx {C Function} {scm_t_int64 *} scm_s64vector_elements (SCM uvec) | |
1126 | @deftypefnx {C Function} {float *} scm_f32vector_elements (SCM uvec) | |
1127 | @deftypefnx {C Function} {double *} scm_f64vector_elements (SCM uvec) | |
1128 | Return a pointer to the elements of a uniform vector. For each call to | |
1129 | one of these functions, you must call @code{scm_uniform_vector_release} | |
1130 | and after that call the pointer to the elements becomes invalid. | |
1131 | @end deftypefn | |
07d83abe | 1132 | |
e6b226b9 MV |
1133 | @deftypefn {C Function} void scm_uniform_vector_release (SCM uvec) |
1134 | Finish the access to the elements of a uniform vector, as exlained | |
1135 | above. | |
1136 | @end deftypefn | |
07d83abe | 1137 | |
e6b226b9 MV |
1138 | @deftypefn {C Function} size_t scm_c_uniform_vector_length (SCM uvec) |
1139 | Return the number of elements of @var{uvec} as a @code{size_t}. | |
1140 | @end deftypefn | |
07d83abe | 1141 | |
e6b226b9 MV |
1142 | @deftypefn {C Function} size_t scm_c_uniform_vector_element_size (SCM uvec) |
1143 | Return the number of bytes of one element of @var{uvec}. | |
1144 | @end deftypefn | |
07d83abe | 1145 | |
e6b226b9 MV |
1146 | @deftypefn {C Function} size_t scm_c_uniform_vector_size (SCM uvec) |
1147 | Return the number of bytes used by all elements of @var{uvec}. This is | |
1148 | just @code{scm_c_uniform_vector_length (@var{uvec}) * | |
1149 | scm_c_uniform_vector_element_size (@var{uvec})}. | |
1150 | @end deftypefn | |
07d83abe | 1151 | |
07d83abe | 1152 | |
e6b226b9 MV |
1153 | @node Bit Vectors |
1154 | @subsection Bit Vectors | |
07d83abe | 1155 | |
e6b226b9 MV |
1156 | @noindent |
1157 | Bit vectors are a specific type of uniform array: an array of booleans | |
1158 | with a single zero-based index. | |
07d83abe | 1159 | |
e6b226b9 MV |
1160 | @noindent |
1161 | They are displayed as a sequence of @code{0}s and | |
1162 | @code{1}s prefixed by @code{#*}, e.g., | |
07d83abe | 1163 | |
e6b226b9 MV |
1164 | @example |
1165 | (make-uniform-vector 8 #t #f) @result{} | |
1166 | #*00000000 | |
1167 | @end example | |
07d83abe | 1168 | |
e6b226b9 MV |
1169 | @deffn {Scheme Procedure} bit-count bool bitvector |
1170 | @deffnx {C Function} scm_bit_count (bool, bitvector) | |
1171 | Return a count of how many entries in @var{bitvector} are equal to | |
1172 | @var{bool}. For example, | |
07d83abe | 1173 | |
e6b226b9 MV |
1174 | @example |
1175 | (bit-count #f #*000111000) @result{} 6 | |
1176 | @end example | |
1177 | @end deffn | |
07d83abe | 1178 | |
e6b226b9 MV |
1179 | @deffn {Scheme Procedure} bit-position bool bitvector start |
1180 | @deffnx {C Function} scm_bit_position (bool, bitvector, start) | |
1181 | Return the index of the first occurrance of @var{bool} in | |
1182 | @var{bitvector}, starting from @var{start}. If there is no @var{bool} | |
1183 | entry between @var{start} and the end of @var{bitvector}, then return | |
1184 | @code{#f}. For example, | |
07d83abe | 1185 | |
e6b226b9 MV |
1186 | @example |
1187 | (bit-position #t #*000101 0) @result{} 3 | |
1188 | (bit-position #f #*0001111 3) @result{} #f | |
1189 | @end example | |
1190 | @end deffn | |
07d83abe | 1191 | |
e6b226b9 MV |
1192 | @deffn {Scheme Procedure} bit-invert! bitvector |
1193 | @deffnx {C Function} scm_bit_invert_x (bitvector) | |
1194 | Modify @var{bitvector} by replacing each element with its negation. | |
1195 | @end deffn | |
07d83abe | 1196 | |
e6b226b9 MV |
1197 | @deffn {Scheme Procedure} bit-set*! bitvector uvec bool |
1198 | @deffnx {C Function} scm_bit_set_star_x (bitvector, uvec, bool) | |
1199 | Set entries of @var{bitvector} to @var{bool}, with @var{uvec} | |
1200 | selecting the entries to change. The return value is unspecified. | |
07d83abe | 1201 | |
e6b226b9 MV |
1202 | If @var{uvec} is a bit vector, then those entries where it has |
1203 | @code{#t} are the ones in @var{bitvector} which are set to @var{bool}. | |
1204 | @var{uvec} and @var{bitvector} must be the same length. When | |
1205 | @var{bool} is @code{#t} it's like @var{uvec} is OR'ed into | |
1206 | @var{bitvector}. Or when @var{bool} is @code{#f} it can be seen as an | |
1207 | ANDNOT. | |
07d83abe | 1208 | |
e6b226b9 MV |
1209 | @example |
1210 | (define bv #*01000010) | |
1211 | (bit-set*! bv #*10010001 #t) | |
1212 | bv | |
1213 | @result{} #*11010011 | |
1214 | @end example | |
07d83abe | 1215 | |
e6b226b9 MV |
1216 | If @var{uvec} is a uniform vector of unsigned long integers, then |
1217 | they're indexes into @var{bitvector} which are set to @var{bool}. | |
07d83abe | 1218 | |
e6b226b9 MV |
1219 | @example |
1220 | (define bv #*01000010) | |
1221 | (bit-set*! bv #u(5 2 7) #t) | |
1222 | bv | |
1223 | @result{} #*01100111 | |
1224 | @end example | |
1225 | @end deffn | |
07d83abe | 1226 | |
e6b226b9 MV |
1227 | @deffn {Scheme Procedure} bit-count* bitvector uvec bool |
1228 | @deffnx {C Function} scm_bit_count_star (bitvector, uvec, bool) | |
1229 | Return a count of how many entries in @var{bitvector} are equal to | |
1230 | @var{bool}, with @var{uvec} selecting the entries to consider. | |
07d83abe | 1231 | |
e6b226b9 MV |
1232 | @var{uvec} is interpreted in the same way as for @code{bit-set*!} |
1233 | above. Namely, if @var{uvec} is a bit vector then entries which have | |
1234 | @code{#t} there are considered in @var{bitvector}. Or if @var{uvec} | |
1235 | is a uniform vector of unsigned long integers then it's the indexes in | |
1236 | @var{bitvector} to consider. | |
07d83abe | 1237 | |
e6b226b9 | 1238 | For example, |
07d83abe MV |
1239 | |
1240 | @example | |
e6b226b9 MV |
1241 | (bit-count* #*01110111 #*11001101 #t) @result{} 3 |
1242 | (bit-count* #*01110111 #u(7 0 4) #f) @result{} 2 | |
07d83abe | 1243 | @end example |
e6b226b9 | 1244 | @end deffn |
07d83abe | 1245 | |
e6b226b9 MV |
1246 | @node Arrays |
1247 | @subsection Arrays | |
1248 | @tpindex Arrays | |
07d83abe | 1249 | |
e6b226b9 MV |
1250 | @menu |
1251 | * Conventional Arrays:: Arrays with arbitrary data. | |
1252 | * Array Mapping:: Applying a procedure to the contents of an array. | |
1253 | * Uniform Arrays:: Arrays with data of a single type. | |
1254 | @end menu | |
07d83abe MV |
1255 | |
1256 | @node Conventional Arrays | |
1257 | @subsubsection Conventional Arrays | |
1258 | ||
1259 | @dfn{Conventional arrays} are a collection of cells organized into an | |
1260 | arbitrary number of dimensions. Each cell can hold any kind of Scheme | |
1261 | value and can be accessed in constant time by supplying an index for | |
1262 | each dimension. | |
1263 | ||
1264 | This contrasts with uniform arrays, which use memory more efficiently | |
1265 | but can hold data of only a single type. It contrasts also with lists | |
1266 | where inserting and deleting cells is more efficient, but more time is | |
1267 | usually required to access a particular cell. | |
1268 | ||
1269 | A conventional array is displayed as @code{#} followed by the @dfn{rank} | |
1270 | (number of dimensions) followed by the cells, organized into dimensions | |
1271 | using parentheses. The nesting depth of the parentheses is equal to | |
1272 | the rank. | |
1273 | ||
1274 | When an array is created, the range of each dimension must be | |
1275 | specified, e.g., to create a 2@cross{}3 array with a zero-based index: | |
1276 | ||
1277 | @example | |
1278 | (make-array 'ho 2 3) @result{} #2((ho ho ho) (ho ho ho)) | |
1279 | @end example | |
1280 | ||
1281 | The range of each dimension can also be given explicitly, e.g., another | |
1282 | way to create the same array: | |
1283 | ||
1284 | @example | |
1285 | (make-array 'ho '(0 1) '(0 2)) @result{} #2((ho ho ho) (ho ho ho)) | |
1286 | @end example | |
1287 | ||
1288 | A conventional array with one dimension based at zero is identical to | |
1289 | a vector: | |
1290 | ||
1291 | @example | |
1292 | (make-array 'ho 3) @result{} #(ho ho ho) | |
1293 | @end example | |
1294 | ||
1295 | The following procedures can be used with conventional arrays (or | |
1296 | vectors). An argument shown as @var{idx}@dots{} means one parameter | |
1297 | for each dimension in the array. Or a @var{idxlist} is a list of such | |
1298 | values, one for each dimension. | |
1299 | ||
1300 | @deffn {Scheme Procedure} array? obj [prot] | |
1301 | @deffnx {C Function} scm_array_p (obj, prot) | |
1302 | Return @code{#t} if the @var{obj} is an array, and @code{#f} if | |
1303 | not. | |
1304 | ||
1305 | The @var{prot} argument is used with uniform arrays (@pxref{Uniform | |
1306 | Arrays}). If given then the return is @code{#t} if @var{obj} is an | |
1307 | array and of that prototype. | |
1308 | @end deffn | |
1309 | ||
1310 | @deffn {Scheme Procedure} make-array initial-value bound @dots{} | |
1311 | Create and return an array that has as many dimensions as there are | |
1312 | @var{bound}s and fill it with @var{initial-value}. | |
1313 | ||
1314 | Each @var{bound} | |
1315 | may be a positive non-zero integer @var{N}, in which case the index for | |
1316 | that dimension can range from 0 through @var{N-1}; or an explicit index | |
1317 | range specifier in the form @code{(LOWER UPPER)}, where both @var{lower} | |
1318 | and @var{upper} are integers, possibly less than zero, and possibly the | |
1319 | same number (however, @var{lower} cannot be greater than @var{upper}). | |
1320 | See examples above. | |
1321 | @end deffn | |
1322 | ||
1323 | @c array-ref's type is `compiled-closure'. There's some weird stuff | |
1324 | @c going on in array.c, too. Let's call it a primitive. -twp | |
1325 | ||
1326 | @deffn {Scheme Procedure} array-ref array idx @dots{} | |
1327 | @deffnx {Scheme Procedure} uniform-vector-ref vec args | |
1328 | @deffnx {C Function} scm_uniform_vector_ref (vec, args) | |
1329 | Return the element at @code{(idx @dots{})} in @var{array}. | |
1330 | ||
1331 | @example | |
1332 | (define a (make-array 999 '(1 2) '(3 4))) | |
1333 | (array-ref a 2 4) @result{} 999 | |
1334 | @end example | |
1335 | @end deffn | |
1336 | ||
1337 | @deffn {Scheme Procedure} array-in-bounds? array idx @dots{} | |
1338 | @deffnx {C Function} scm_array_in_bounds_p (array, idxlist) | |
1339 | Return @code{#t} if the given index would be acceptable to | |
1340 | @code{array-ref}. | |
1341 | ||
1342 | @example | |
1343 | (define a (make-array #f '(1 2) '(3 4))) | |
1344 | (array-in-bounds? a 2 3) @result{} #f | |
1345 | (array-in-bounds? a 0 0) @result{} #f | |
1346 | @end example | |
1347 | @end deffn | |
1348 | ||
1349 | @c fixme: why do these sigs differ? -ttn 2001/07/19 01:14:12 | |
1350 | @deffn {Scheme Procedure} array-set! array obj idx @dots{} | |
1351 | @deffnx {Scheme Procedure} uniform-array-set1! array obj idxlist | |
1352 | @deffnx {C Function} scm_array_set_x (array, obj, idxlist) | |
1353 | Set the element at @code{(idx @dots{})} in @var{array} to @var{obj}. | |
1354 | The return value is unspecified. | |
1355 | ||
1356 | @example | |
1357 | (define a (make-array #f '(0 1) '(0 1))) | |
1358 | (array-set! a #t 1 1) | |
1359 | a @result{} #2((#f #f) (#f #t)) | |
1360 | @end example | |
1361 | @end deffn | |
1362 | ||
1363 | @deffn {Scheme Procedure} make-shared-array oldarray mapfunc bound @dots{} | |
1364 | @deffnx {C Function} scm_make_shared_array (oldarray, mapfunc, boundlist) | |
1365 | @code{make-shared-array} can be used to create shared subarrays of other | |
1366 | arrays. The @var{mapper} is a function that translates coordinates in | |
1367 | the new array into coordinates in the old array. A @var{mapper} must be | |
1368 | linear, and its range must stay within the bounds of the old array, but | |
1369 | it can be otherwise arbitrary. A simple example: | |
1370 | ||
1371 | @lisp | |
1372 | (define fred (make-array #f 8 8)) | |
1373 | (define freds-diagonal | |
1374 | (make-shared-array fred (lambda (i) (list i i)) 8)) | |
1375 | (array-set! freds-diagonal 'foo 3) | |
1376 | (array-ref fred 3 3) @result{} foo | |
1377 | (define freds-center | |
1378 | (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2)) | |
1379 | (array-ref freds-center 0 0) @result{} foo | |
1380 | @end lisp | |
1381 | @end deffn | |
1382 | ||
1383 | @deffn {Scheme Procedure} shared-array-increments array | |
1384 | @deffnx {C Function} scm_shared_array_increments (array) | |
1385 | For each dimension, return the distance between elements in the root vector. | |
1386 | @end deffn | |
1387 | ||
1388 | @deffn {Scheme Procedure} shared-array-offset array | |
1389 | @deffnx {C Function} scm_shared_array_offset (array) | |
1390 | Return the root vector index of the first element in the array. | |
1391 | @end deffn | |
1392 | ||
1393 | @deffn {Scheme Procedure} shared-array-root array | |
1394 | @deffnx {C Function} scm_shared_array_root (array) | |
1395 | Return the root vector of a shared array. | |
1396 | @end deffn | |
1397 | ||
1398 | @deffn {Scheme Procedure} transpose-array array dim1 @dots{} | |
1399 | @deffnx {C Function} scm_transpose_array (array, dimlist) | |
1400 | Return an array sharing contents with @var{array}, but with | |
1401 | dimensions arranged in a different order. There must be one | |
1402 | @var{dim} argument for each dimension of @var{array}. | |
1403 | @var{dim1}, @var{dim2}, @dots{} should be integers between 0 | |
1404 | and the rank of the array to be returned. Each integer in that | |
1405 | range must appear at least once in the argument list. | |
1406 | ||
1407 | The values of @var{dim1}, @var{dim2}, @dots{} correspond to | |
1408 | dimensions in the array to be returned, and their positions in the | |
1409 | argument list to dimensions of @var{array}. Several @var{dim}s | |
1410 | may have the same value, in which case the returned array will | |
1411 | have smaller rank than @var{array}. | |
1412 | ||
1413 | @lisp | |
1414 | (transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d)) | |
1415 | (transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d) | |
1416 | (transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{} | |
1417 | #2((a 4) (b 5) (c 6)) | |
1418 | @end lisp | |
1419 | @end deffn | |
1420 | ||
1421 | @deffn {Scheme Procedure} enclose-array array dim1 @dots{} | |
1422 | @deffnx {C Function} scm_enclose_array (array, dimlist) | |
1423 | @var{dim1}, @var{dim2} @dots{} should be nonnegative integers less than | |
1424 | the rank of @var{array}. @code{enclose-array} returns an array | |
1425 | resembling an array of shared arrays. The dimensions of each shared | |
1426 | array are the same as the @var{dim}th dimensions of the original array, | |
1427 | the dimensions of the outer array are the same as those of the original | |
1428 | array that did not match a @var{dim}. | |
1429 | ||
1430 | An enclosed array is not a general Scheme array. Its elements may not | |
1431 | be set using @code{array-set!}. Two references to the same element of | |
1432 | an enclosed array will be @code{equal?} but will not in general be | |
1433 | @code{eq?}. The value returned by @code{array-prototype} when given an | |
1434 | enclosed array is unspecified. | |
1435 | ||
1436 | For example, | |
1437 | ||
1438 | @lisp | |
1439 | (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) | |
1440 | @result{} | |
1441 | #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))> | |
1442 | ||
1443 | (enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) | |
1444 | @result{} | |
1445 | #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))> | |
1446 | @end lisp | |
1447 | @end deffn | |
1448 | ||
1449 | @deffn {Scheme Procedure} array-shape array | |
1450 | @deffnx {Scheme Procedure} array-dimensions array | |
1451 | @deffnx {C Function} scm_array_dimensions (array) | |
1452 | Return a list of the bounds for each dimenson of @var{array}. | |
1453 | ||
1454 | @code{array-shape} gives @code{(@var{lower} @var{upper})} for each | |
1455 | dimension. @code{array-dimensions} instead returns just | |
1456 | @math{@var{upper}+1} for dimensions with a 0 lower bound. Both are | |
1457 | suitable as input to @code{make-array}. | |
1458 | ||
1459 | For example, | |
1460 | ||
1461 | @example | |
1462 | (define a (make-array 'foo '(-1 3) 5)) | |
1463 | (array-shape a) @result{} ((-1 3) (0 4)) | |
1464 | (array-dimensions a) @result{} ((-1 3) 5) | |
1465 | @end example | |
1466 | @end deffn | |
1467 | ||
1468 | @deffn {Scheme Procedure} array-rank obj | |
1469 | @deffnx {C Function} scm_array_rank (obj) | |
1470 | Return the number of dimensions of an array @var{obj}, or if @var{obj} | |
1471 | is not an array then return 0. | |
1472 | @end deffn | |
1473 | ||
1474 | @deffn {Scheme Procedure} array->list array | |
1475 | @deffnx {C Function} scm_array_to_list (array) | |
1476 | Return a list consisting of all the elements, in order, of | |
1477 | @var{array}. | |
1478 | @end deffn | |
1479 | ||
1480 | @c FIXME: Describe how the order affects the copying (it matters for | |
1481 | @c shared arrays with the same underlying root vector, presumably). | |
1482 | @c | |
1483 | @deffn {Scheme Procedure} array-copy! src dst | |
1484 | @deffnx {Scheme Procedure} array-copy-in-order! src dst | |
1485 | @deffnx {C Function} scm_array_copy_x (src, dst) | |
1486 | Copy every element from vector or array @var{src} to the corresponding | |
1487 | element of @var{dst}. @var{dst} must have the same rank as @var{src}, | |
1488 | and be at least as large in each dimension. The return value is | |
1489 | unspecified. | |
1490 | @end deffn | |
1491 | ||
1492 | @deffn {Scheme Procedure} array-fill! array fill | |
1493 | @deffnx {C Function} scm_array_fill_x (array, fill) | |
1494 | Store @var{fill} in every element of @var{array}. The value returned | |
1495 | is unspecified. | |
1496 | @end deffn | |
1497 | ||
1498 | @c begin (texi-doc-string "guile" "array-equal?") | |
1499 | @deffn {Scheme Procedure} array-equal? array1 array2 @dots{} | |
1500 | Return @code{#t} if all arguments are arrays with the same shape, the | |
1501 | same type, and have corresponding elements which are either | |
1502 | @code{equal?} or @code{array-equal?}. This function differs from | |
1503 | @code{equal?} in that a one dimensional shared array may be | |
1504 | @var{array-equal?} but not @var{equal?} to a vector or uniform vector. | |
1505 | @end deffn | |
1506 | ||
1507 | @deffn {Scheme Procedure} array-contents array [strict] | |
1508 | @deffnx {C Function} scm_array_contents (array, strict) | |
1509 | If @var{array} may be @dfn{unrolled} into a one dimensional shared array | |
1510 | without changing their order (last subscript changing fastest), then | |
1511 | @code{array-contents} returns that shared array, otherwise it returns | |
1512 | @code{#f}. All arrays made by @code{make-array} and | |
1513 | @code{make-uniform-array} may be unrolled, some arrays made by | |
1514 | @code{make-shared-array} may not be. | |
1515 | ||
1516 | If the optional argument @var{strict} is provided, a shared array will | |
1517 | be returned only if its elements are stored internally contiguous in | |
1518 | memory. | |
1519 | @end deffn | |
1520 | ||
1521 | @node Array Mapping | |
1522 | @subsubsection Array Mapping | |
1523 | ||
1524 | @c FIXME: array-map! accepts no source arrays at all, and in that | |
1525 | @c case makes calls "(proc)". Is that meant to be a documented | |
1526 | @c feature? | |
1527 | @c | |
1528 | @c FIXME: array-for-each doesn't say what happens if the sources have | |
1529 | @c different index ranges. The code currently iterates over the | |
1530 | @c indices of the first and expects the others to cover those. That | |
1531 | @c at least vaguely matches array-map!, but is is meant to be a | |
1532 | @c documented feature? | |
1533 | ||
1534 | @deffn {Scheme Procedure} array-map! dst proc src1 @dots{} srcN | |
1535 | @deffnx {Scheme Procedure} array-map-in-order! dst proc src1 @dots{} srcN | |
1536 | @deffnx {C Function} scm_array_map_x (dst, proc, srclist) | |
1537 | Set each element of the @var{dst} array to values obtained from calls | |
1538 | to @var{proc}. The value returned is unspecified. | |
1539 | ||
1540 | Each call is @code{(@var{proc} @var{elem1} @dots{} @var{elemN})}, | |
1541 | where each @var{elem} is from the corresponding @var{src} array, at | |
1542 | the @var{dst} index. @code{array-map-in-order!} makes the calls in | |
1543 | row-major order, @code{array-map!} makes them in an unspecified order. | |
1544 | ||
1545 | The @var{src} arrays must have the same number of dimensions as | |
1546 | @var{dst}, and must have a range for each dimension which covers the | |
1547 | range in @var{dst}. This ensures all @var{dst} indices are valid in | |
1548 | each @var{src}. | |
1549 | @end deffn | |
1550 | ||
1551 | @deffn {Scheme Procedure} array-for-each proc src1 @dots{} srcN | |
1552 | @deffnx {C Function} scm_array_for_each (proc, src1, srclist) | |
1553 | Apply @var{proc} to each tuple of elements of @var{src1} @dots{} | |
1554 | @var{srcN}, in row-major order. The value returned is unspecified. | |
1555 | @end deffn | |
1556 | ||
1557 | @deffn {Scheme Procedure} array-index-map! dst proc | |
1558 | @deffnx {C Function} scm_array_index_map_x (dst, proc) | |
1559 | Set each element of the @var{dst} array to values returned by calls to | |
1560 | @var{proc}. The value returned is unspecified. | |
1561 | ||
1562 | Each call is @code{(@var{proc} @var{i1} @dots{} @var{iN})}, where | |
1563 | @var{i1}@dots{}@var{iN} is the destination index, one parameter for | |
1564 | each dimension. The order in which the calls are made is unspecified. | |
1565 | ||
1566 | For example, to create a @m{4\times4, 4x4} matrix representing a | |
1567 | cyclic group, | |
1568 | ||
1569 | @tex | |
1570 | \advance\leftskip by 2\lispnarrowing { | |
1571 | $\left(\matrix{% | |
1572 | 0 & 1 & 2 & 3 \cr | |
1573 | 1 & 2 & 3 & 0 \cr | |
1574 | 2 & 3 & 0 & 1 \cr | |
1575 | 3 & 0 & 1 & 2 \cr | |
1576 | }\right)$} \par | |
1577 | @end tex | |
1578 | @ifnottex | |
1579 | @example | |
1580 | / 0 1 2 3 \ | |
1581 | | 1 2 3 0 | | |
1582 | | 2 3 0 1 | | |
1583 | \ 3 0 1 2 / | |
1584 | @end example | |
1585 | @end ifnottex | |
1586 | ||
1587 | @example | |
1588 | (define a (make-array #f 4 4)) | |
1589 | (array-index-map! a (lambda (i j) | |
1590 | (modulo (+ i j) 4))) | |
1591 | @end example | |
1592 | @end deffn | |
1593 | ||
1594 | @node Uniform Arrays | |
1595 | @subsubsection Uniform Arrays | |
1596 | @tpindex Uniform Arrays | |
1597 | ||
1598 | @noindent | |
1599 | @dfn{Uniform arrays} have elements all of the | |
1600 | same type and occupy less storage than conventional | |
1601 | arrays. Uniform arrays with a single zero-based dimension | |
1602 | are also known as @dfn{uniform vectors}. The procedures in | |
1603 | this section can also be used on conventional arrays, vectors, | |
1604 | bit-vectors and strings. | |
1605 | ||
1606 | @noindent | |
1607 | When creating a uniform array, the type of data to be stored | |
1608 | is indicated with a @var{prototype} argument. The following table | |
1609 | lists the types available and example prototypes: | |
1610 | ||
1611 | @example | |
1612 | prototype type printing character | |
1613 | ||
1614 | #t boolean (bit-vector) b | |
1615 | #\a char (string) a | |
1616 | #\nul byte (integer) y | |
1617 | 's short (integer) h | |
1618 | 1 unsigned long (integer) u | |
1619 | -1 signed long (integer) e | |
1620 | 'l signed long long (integer) l | |
1621 | 1.0 float (single precision) s | |
1622 | 1/3 double (double precision float) i | |
1623 | 0+i complex (double precision) c | |
1624 | () conventional vector | |
1625 | @end example | |
1626 | ||
1627 | Note that with the introduction of exact fractions in Guile 1.8, | |
1628 | @samp{1/3} here is now a fraction, where previously such an expression | |
1629 | was a double @samp{0.333@dots{}}. For most normal usages this should | |
1630 | be source code compatible. | |
1631 | ||
1632 | Unshared uniform arrays of characters with a single zero-based dimension | |
1633 | are identical to strings: | |
1634 | ||
1635 | @example | |
1636 | (make-uniform-array #\a 3) @result{} | |
1637 | "aaa" | |
1638 | @end example | |
1639 | ||
1640 | @noindent | |
1641 | Unshared uniform arrays of booleans with a single zero-based dimension | |
1642 | are identical to @ref{Bit Vectors, bit-vectors}. | |
1643 | ||
1644 | @example | |
1645 | (make-uniform-array #t 3) @result{} | |
1646 | #*111 | |
1647 | @end example | |
1648 | ||
1649 | @noindent | |
1650 | Other uniform vectors are written in a form similar to that of vectors, | |
1651 | except that a single character from the above table is put between | |
1652 | @code{#} and @code{(}. For example, a uniform vector of signed | |
1653 | long integers is displayed in the form @code{'#e(3 5 9)}. | |
1654 | ||
1655 | @deffn {Scheme Procedure} make-uniform-array prototype bound1 bound2 @dots{} | |
1656 | Create and return a uniform array of type corresponding to | |
1657 | @var{prototype} that has as many dimensions as there are @var{bound}s | |
1658 | and fill it with @var{prototype}. | |
1659 | @end deffn | |
1660 | ||
1661 | @deffn {Scheme Procedure} array-prototype ra | |
1662 | @deffnx {C Function} scm_array_prototype (ra) | |
1663 | Return an object that would produce an array of the same type | |
1664 | as @var{array}, if used as the @var{prototype} for | |
1665 | @code{make-uniform-array}. | |
1666 | @end deffn | |
1667 | ||
1668 | @deffn {Scheme Procedure} list->uniform-array ndim prot lst | |
1669 | @deffnx {Scheme Procedure} list->uniform-vector prot lst | |
1670 | @deffnx {C Function} scm_list_to_uniform_array (ndim, prot, lst) | |
1671 | Return a uniform array of the type indicated by prototype | |
1672 | @var{prot} with elements the same as those of @var{lst}. | |
1673 | Elements must be of the appropriate type, no coercions are | |
1674 | done. | |
1675 | @end deffn | |
1676 | ||
1677 | @deffn {Scheme Procedure} uniform-vector-fill! uve fill | |
1678 | Store @var{fill} in every element of @var{uve}. The value returned is | |
1679 | unspecified. | |
1680 | @end deffn | |
1681 | ||
1682 | @deffn {Scheme Procedure} uniform-vector-length v | |
1683 | @deffnx {C Function} scm_uniform_vector_length (v) | |
1684 | Return the number of elements in @var{uve}. | |
1685 | @end deffn | |
1686 | ||
1687 | @deffn {Scheme Procedure} dimensions->uniform-array dims prot [fill] | |
1688 | @deffnx {Scheme Procedure} make-uniform-vector length prototype [fill] | |
1689 | @deffnx {C Function} scm_dimensions_to_uniform_array (dims, prot, fill) | |
1690 | Create and return a uniform array or vector of type | |
1691 | corresponding to @var{prototype} with dimensions @var{dims} or | |
1692 | length @var{length}. If @var{fill} is supplied, it's used to | |
1693 | fill the array, otherwise @var{prototype} is used. | |
1694 | @end deffn | |
1695 | ||
1696 | @c Another compiled-closure. -twp | |
1697 | ||
1698 | @deffn {Scheme Procedure} uniform-array-read! ra [port_or_fd [start [end]]] | |
1699 | @deffnx {Scheme Procedure} uniform-vector-read! uve [port-or-fdes] [start] [end] | |
1700 | @deffnx {C Function} scm_uniform_array_read_x (ra, port_or_fd, start, end) | |
1701 | Attempt to read all elements of @var{ura}, in lexicographic order, as | |
1702 | binary objects from @var{port-or-fdes}. | |
1703 | If an end of file is encountered, | |
1704 | the objects up to that point are put into @var{ura} | |
1705 | (starting at the beginning) and the remainder of the array is | |
1706 | unchanged. | |
1707 | ||
1708 | The optional arguments @var{start} and @var{end} allow | |
1709 | a specified region of a vector (or linearized array) to be read, | |
1710 | leaving the remainder of the vector unchanged. | |
1711 | ||
1712 | @code{uniform-array-read!} returns the number of objects read. | |
1713 | @var{port-or-fdes} may be omitted, in which case it defaults to the value | |
1714 | returned by @code{(current-input-port)}. | |
1715 | @end deffn | |
1716 | ||
1717 | @deffn {Scheme Procedure} uniform-array-write v [port_or_fd [start [end]]] | |
1718 | @deffnx {Scheme Procedure} uniform-vector-write uve [port-or-fdes] [start] [end] | |
1719 | @deffnx {C Function} scm_uniform_array_write (v, port_or_fd, start, end) | |
1720 | Writes all elements of @var{ura} as binary objects to | |
1721 | @var{port-or-fdes}. | |
1722 | ||
1723 | The optional arguments @var{start} | |
1724 | and @var{end} allow | |
1725 | a specified region of a vector (or linearized array) to be written. | |
1726 | ||
1727 | The number of objects actually written is returned. | |
1728 | @var{port-or-fdes} may be | |
1729 | omitted, in which case it defaults to the value returned by | |
1730 | @code{(current-output-port)}. | |
1731 | @end deffn | |
1732 | ||
e6b226b9 MV |
1733 | @node Records |
1734 | @subsection Records | |
07d83abe | 1735 | |
e6b226b9 MV |
1736 | A @dfn{record type} is a first class object representing a user-defined |
1737 | data type. A @dfn{record} is an instance of a record type. | |
07d83abe | 1738 | |
e6b226b9 MV |
1739 | @deffn {Scheme Procedure} record? obj |
1740 | Return @code{#t} if @var{obj} is a record of any type and @code{#f} | |
1741 | otherwise. | |
07d83abe | 1742 | |
e6b226b9 MV |
1743 | Note that @code{record?} may be true of any Scheme value; there is no |
1744 | promise that records are disjoint with other Scheme types. | |
1745 | @end deffn | |
07d83abe | 1746 | |
e6b226b9 MV |
1747 | @deffn {Scheme Procedure} make-record-type type-name field-names |
1748 | Return a @dfn{record-type descriptor}, a value representing a new data | |
1749 | type disjoint from all others. The @var{type-name} argument must be a | |
1750 | string, but is only used for debugging purposes (such as the printed | |
1751 | representation of a record of the new type). The @var{field-names} | |
1752 | argument is a list of symbols naming the @dfn{fields} of a record of the | |
1753 | new type. It is an error if the list contains any duplicates. It is | |
1754 | unspecified how record-type descriptors are represented. | |
07d83abe MV |
1755 | @end deffn |
1756 | ||
e6b226b9 MV |
1757 | @deffn {Scheme Procedure} record-constructor rtd [field-names] |
1758 | Return a procedure for constructing new members of the type represented | |
1759 | by @var{rtd}. The returned procedure accepts exactly as many arguments | |
1760 | as there are symbols in the given list, @var{field-names}; these are | |
1761 | used, in order, as the initial values of those fields in a new record, | |
1762 | which is returned by the constructor procedure. The values of any | |
1763 | fields not named in that list are unspecified. The @var{field-names} | |
1764 | argument defaults to the list of field names in the call to | |
1765 | @code{make-record-type} that created the type represented by @var{rtd}; | |
1766 | if the @var{field-names} argument is provided, it is an error if it | |
1767 | contains any duplicates or any symbols not in the default list. | |
1768 | @end deffn | |
07d83abe | 1769 | |
e6b226b9 MV |
1770 | @deffn {Scheme Procedure} record-predicate rtd |
1771 | Return a procedure for testing membership in the type represented by | |
1772 | @var{rtd}. The returned procedure accepts exactly one argument and | |
1773 | returns a true value if the argument is a member of the indicated record | |
1774 | type; it returns a false value otherwise. | |
07d83abe MV |
1775 | @end deffn |
1776 | ||
e6b226b9 MV |
1777 | @deffn {Scheme Procedure} record-accessor rtd field-name |
1778 | Return a procedure for reading the value of a particular field of a | |
1779 | member of the type represented by @var{rtd}. The returned procedure | |
1780 | accepts exactly one argument which must be a record of the appropriate | |
1781 | type; it returns the current value of the field named by the symbol | |
1782 | @var{field-name} in that record. The symbol @var{field-name} must be a | |
1783 | member of the list of field-names in the call to @code{make-record-type} | |
1784 | that created the type represented by @var{rtd}. | |
07d83abe MV |
1785 | @end deffn |
1786 | ||
e6b226b9 MV |
1787 | @deffn {Scheme Procedure} record-modifier rtd field-name |
1788 | Return a procedure for writing the value of a particular field of a | |
1789 | member of the type represented by @var{rtd}. The returned procedure | |
1790 | accepts exactly two arguments: first, a record of the appropriate type, | |
1791 | and second, an arbitrary Scheme value; it modifies the field named by | |
1792 | the symbol @var{field-name} in that record to contain the given value. | |
1793 | The returned value of the modifier procedure is unspecified. The symbol | |
1794 | @var{field-name} must be a member of the list of field-names in the call | |
1795 | to @code{make-record-type} that created the type represented by | |
1796 | @var{rtd}. | |
1797 | @end deffn | |
07d83abe | 1798 | |
e6b226b9 MV |
1799 | @deffn {Scheme Procedure} record-type-descriptor record |
1800 | Return a record-type descriptor representing the type of the given | |
1801 | record. That is, for example, if the returned descriptor were passed to | |
1802 | @code{record-predicate}, the resulting predicate would return a true | |
1803 | value when passed the given record. Note that it is not necessarily the | |
1804 | case that the returned descriptor is the one that was passed to | |
1805 | @code{record-constructor} in the call that created the constructor | |
1806 | procedure that created the given record. | |
1807 | @end deffn | |
1808 | ||
1809 | @deffn {Scheme Procedure} record-type-name rtd | |
1810 | Return the type-name associated with the type represented by rtd. The | |
1811 | returned value is @code{eqv?} to the @var{type-name} argument given in | |
1812 | the call to @code{make-record-type} that created the type represented by | |
1813 | @var{rtd}. | |
1814 | @end deffn | |
1815 | ||
1816 | @deffn {Scheme Procedure} record-type-fields rtd | |
1817 | Return a list of the symbols naming the fields in members of the type | |
1818 | represented by @var{rtd}. The returned value is @code{equal?} to the | |
1819 | field-names argument given in the call to @code{make-record-type} that | |
1820 | created the type represented by @var{rtd}. | |
1821 | @end deffn | |
1822 | ||
1823 | ||
1824 | @node Structures | |
1825 | @subsection Structures | |
1826 | @tpindex Structures | |
1827 | ||
1828 | [FIXME: this is pasted in from Tom Lord's original guile.texi and should | |
1829 | be reviewed] | |
1830 | ||
1831 | A @dfn{structure type} is a first class user-defined data type. A | |
1832 | @dfn{structure} is an instance of a structure type. A structure type is | |
1833 | itself a structure. | |
1834 | ||
1835 | Structures are less abstract and more general than traditional records. | |
1836 | In fact, in Guile Scheme, records are implemented using structures. | |
1837 | ||
1838 | @menu | |
1839 | * Structure Concepts:: The structure of Structures | |
1840 | * Structure Layout:: Defining the layout of structure types | |
1841 | * Structure Basics:: make-, -ref and -set! procedures for structs | |
1842 | * Vtables:: Accessing type-specific data | |
1843 | @end menu | |
1844 | ||
1845 | @node Structure Concepts | |
1846 | @subsubsection Structure Concepts | |
1847 | ||
1848 | A structure object consists of a handle, structure data, and a vtable. | |
1849 | The handle is a Scheme value which points to both the vtable and the | |
1850 | structure's data. Structure data is a dynamically allocated region of | |
1851 | memory, private to the structure, divided up into typed fields. A | |
1852 | vtable is another structure used to hold type-specific data. Multiple | |
1853 | structures can share a common vtable. | |
1854 | ||
1855 | Three concepts are key to understanding structures. | |
1856 | ||
1857 | @itemize @bullet{} | |
1858 | @item @dfn{layout specifications} | |
1859 | ||
1860 | Layout specifications determine how memory allocated to structures is | |
1861 | divided up into fields. Programmers must write a layout specification | |
1862 | whenever a new type of structure is defined. | |
1863 | ||
1864 | @item @dfn{structural accessors} | |
1865 | ||
1866 | Structure access is by field number. There is only one set of | |
1867 | accessors common to all structure objects. | |
1868 | ||
1869 | @item @dfn{vtables} | |
1870 | ||
1871 | Vtables, themselves structures, are first class representations of | |
1872 | disjoint sub-types of structures in general. In most cases, when a | |
1873 | new structure is created, programmers must specify a vtable for the | |
1874 | new structure. Each vtable has a field describing the layout of its | |
1875 | instances. Vtables can have additional, user-defined fields as well. | |
1876 | @end itemize | |
1877 | ||
1878 | ||
1879 | ||
1880 | @node Structure Layout | |
1881 | @subsubsection Structure Layout | |
1882 | ||
1883 | When a structure is created, a region of memory is allocated to hold its | |
1884 | state. The @dfn{layout} of the structure's type determines how that | |
1885 | memory is divided into fields. | |
1886 | ||
1887 | Each field has a specified type. There are only three types allowed, each | |
1888 | corresponding to a one letter code. The allowed types are: | |
1889 | ||
1890 | @itemize @bullet{} | |
1891 | @item 'u' -- unprotected | |
1892 | ||
1893 | The field holds binary data that is not GC protected. | |
1894 | ||
1895 | @item 'p' -- protected | |
1896 | ||
1897 | The field holds a Scheme value and is GC protected. | |
1898 | ||
1899 | @item 's' -- self | |
1900 | ||
1901 | The field holds a Scheme value and is GC protected. When a structure is | |
1902 | created with this type of field, the field is initialized to refer to | |
1903 | the structure's own handle. This kind of field is mainly useful when | |
1904 | mixing Scheme and C code in which the C code may need to compute a | |
1905 | structure's handle given only the address of its malloc'd data. | |
1906 | @end itemize | |
1907 | ||
1908 | ||
1909 | Each field also has an associated access protection. There are only | |
1910 | three kinds of protection, each corresponding to a one letter code. | |
1911 | The allowed protections are: | |
1912 | ||
1913 | @itemize @bullet{} | |
1914 | @item 'w' -- writable | |
1915 | ||
1916 | The field can be read and written. | |
1917 | ||
1918 | @item 'r' -- readable | |
1919 | ||
1920 | The field can be read, but not written. | |
1921 | ||
1922 | @item 'o' -- opaque | |
1923 | ||
1924 | The field can be neither read nor written. This kind | |
1925 | of protection is for fields useful only to built-in routines. | |
1926 | @end itemize | |
1927 | ||
1928 | A layout specification is described by stringing together pairs | |
1929 | of letters: one to specify a field type and one to specify a field | |
1930 | protection. For example, a traditional cons pair type object could | |
1931 | be described as: | |
07d83abe MV |
1932 | |
1933 | @example | |
e6b226b9 MV |
1934 | ; cons pairs have two writable fields of Scheme data |
1935 | "pwpw" | |
07d83abe MV |
1936 | @end example |
1937 | ||
e6b226b9 | 1938 | A pair object in which the first field is held constant could be: |
07d83abe MV |
1939 | |
1940 | @example | |
e6b226b9 | 1941 | "prpw" |
07d83abe | 1942 | @end example |
07d83abe | 1943 | |
e6b226b9 MV |
1944 | Binary fields, (fields of type "u"), hold one @dfn{word} each. The |
1945 | size of a word is a machine dependent value defined to be equal to the | |
1946 | value of the C expression: @code{sizeof (long)}. | |
07d83abe | 1947 | |
e6b226b9 MV |
1948 | The last field of a structure layout may specify a tail array. |
1949 | A tail array is indicated by capitalizing the field's protection | |
1950 | code ('W', 'R' or 'O'). A tail-array field is replaced by | |
1951 | a read-only binary data field containing an array size. The array | |
1952 | size is determined at the time the structure is created. It is followed | |
1953 | by a corresponding number of fields of the type specified for the | |
1954 | tail array. For example, a conventional Scheme vector can be | |
1955 | described as: | |
07d83abe | 1956 | |
e6b226b9 MV |
1957 | @example |
1958 | ; A vector is an arbitrary number of writable fields holding Scheme | |
1959 | ; values: | |
1960 | "pW" | |
1961 | @end example | |
1962 | ||
1963 | In the above example, field 0 contains the size of the vector and | |
1964 | fields beginning at 1 contain the vector elements. | |
1965 | ||
1966 | A kind of tagged vector (a constant tag followed by conventional | |
1967 | vector elements) might be: | |
07d83abe MV |
1968 | |
1969 | @example | |
e6b226b9 | 1970 | "prpW" |
07d83abe | 1971 | @end example |
e6b226b9 MV |
1972 | |
1973 | ||
1974 | Structure layouts are represented by specially interned symbols whose | |
1975 | name is a string of type and protection codes. To create a new | |
1976 | structure layout, use this procedure: | |
1977 | ||
1978 | @deffn {Scheme Procedure} make-struct-layout fields | |
1979 | @deffnx {C Function} scm_make_struct_layout (fields) | |
1980 | Return a new structure layout object. | |
1981 | ||
1982 | @var{fields} must be a string made up of pairs of characters | |
1983 | strung together. The first character of each pair describes a field | |
1984 | type, the second a field protection. Allowed types are 'p' for | |
1985 | GC-protected Scheme data, 'u' for unprotected binary data, and 's' for | |
1986 | a field that points to the structure itself. Allowed protections | |
1987 | are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque | |
1988 | fields. The last field protection specification may be capitalized to | |
1989 | indicate that the field is a tail-array. | |
1990 | @end deffn | |
1991 | ||
1992 | ||
1993 | ||
1994 | @node Structure Basics | |
1995 | @subsubsection Structure Basics | |
1996 | ||
1997 | This section describes the basic procedures for creating and accessing | |
1998 | structures. | |
1999 | ||
2000 | @deffn {Scheme Procedure} make-struct vtable tail_array_size . init | |
2001 | @deffnx {C Function} scm_make_struct (vtable, tail_array_size, init) | |
2002 | Create a new structure. | |
2003 | ||
2004 | @var{type} must be a vtable structure (@pxref{Vtables}). | |
2005 | ||
2006 | @var{tail-elts} must be a non-negative integer. If the layout | |
2007 | specification indicated by @var{type} includes a tail-array, | |
2008 | this is the number of elements allocated to that array. | |
2009 | ||
2010 | The @var{init1}, @dots{} are optional arguments describing how | |
2011 | successive fields of the structure should be initialized. Only fields | |
2012 | with protection 'r' or 'w' can be initialized, except for fields of | |
2013 | type 's', which are automatically initialized to point to the new | |
2014 | structure itself; fields with protection 'o' can not be initialized by | |
2015 | Scheme programs. | |
2016 | ||
2017 | If fewer optional arguments than initializable fields are supplied, | |
2018 | fields of type 'p' get default value #f while fields of type 'u' are | |
2019 | initialized to 0. | |
2020 | ||
2021 | Structs are currently the basic representation for record-like data | |
2022 | structures in Guile. The plan is to eventually replace them with a | |
2023 | new representation which will at the same time be easier to use and | |
2024 | more powerful. | |
2025 | ||
2026 | For more information, see the documentation for @code{make-vtable-vtable}. | |
2027 | @end deffn | |
2028 | ||
2029 | @deffn {Scheme Procedure} struct? x | |
2030 | @deffnx {C Function} scm_struct_p (x) | |
2031 | Return @code{#t} iff @var{x} is a structure object, else | |
2032 | @code{#f}. | |
2033 | @end deffn | |
2034 | ||
2035 | ||
2036 | @deffn {Scheme Procedure} struct-ref handle pos | |
2037 | @deffnx {Scheme Procedure} struct-set! struct n value | |
2038 | @deffnx {C Function} scm_struct_ref (handle, pos) | |
2039 | @deffnx {C Function} scm_struct_set_x (struct, n, value) | |
2040 | Access (or modify) the @var{n}th field of @var{struct}. | |
2041 | ||
2042 | If the field is of type 'p', then it can be set to an arbitrary value. | |
2043 | ||
2044 | If the field is of type 'u', then it can only be set to a non-negative | |
2045 | integer value small enough to fit in one machine word. | |
2046 | @end deffn | |
2047 | ||
2048 | ||
2049 | ||
2050 | @node Vtables | |
2051 | @subsubsection Vtables | |
2052 | ||
2053 | Vtables are structures that are used to represent structure types. Each | |
2054 | vtable contains a layout specification in field | |
2055 | @code{vtable-index-layout} -- instances of the type are laid out | |
2056 | according to that specification. Vtables contain additional fields | |
2057 | which are used only internally to libguile. The variable | |
2058 | @code{vtable-offset-user} is bound to a field number. Vtable fields | |
2059 | at that position or greater are user definable. | |
2060 | ||
2061 | @deffn {Scheme Procedure} struct-vtable handle | |
2062 | @deffnx {C Function} scm_struct_vtable (handle) | |
2063 | Return the vtable structure that describes the type of @var{struct}. | |
2064 | @end deffn | |
2065 | ||
2066 | @deffn {Scheme Procedure} struct-vtable? x | |
2067 | @deffnx {C Function} scm_struct_vtable_p (x) | |
2068 | Return @code{#t} iff @var{x} is a vtable structure. | |
2069 | @end deffn | |
2070 | ||
2071 | If you have a vtable structure, @code{V}, you can create an instance of | |
2072 | the type it describes by using @code{(make-struct V ...)}. But where | |
2073 | does @code{V} itself come from? One possibility is that @code{V} is an | |
2074 | instance of a user-defined vtable type, @code{V'}, so that @code{V} is | |
2075 | created by using @code{(make-struct V' ...)}. Another possibility is | |
2076 | that @code{V} is an instance of the type it itself describes. Vtable | |
2077 | structures of the second sort are created by this procedure: | |
2078 | ||
2079 | @deffn {Scheme Procedure} make-vtable-vtable user_fields tail_array_size . init | |
2080 | @deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_array_size, init) | |
2081 | Return a new, self-describing vtable structure. | |
2082 | ||
2083 | @var{user-fields} is a string describing user defined fields of the | |
2084 | vtable beginning at index @code{vtable-offset-user} | |
2085 | (see @code{make-struct-layout}). | |
2086 | ||
2087 | @var{tail-size} specifies the size of the tail-array (if any) of | |
2088 | this vtable. | |
2089 | ||
2090 | @var{init1}, @dots{} are the optional initializers for the fields of | |
2091 | the vtable. | |
2092 | ||
2093 | Vtables have one initializable system field---the struct printer. | |
2094 | This field comes before the user fields in the initializers passed | |
2095 | to @code{make-vtable-vtable} and @code{make-struct}, and thus works as | |
2096 | a third optional argument to @code{make-vtable-vtable} and a fourth to | |
2097 | @code{make-struct} when creating vtables: | |
2098 | ||
2099 | If the value is a procedure, it will be called instead of the standard | |
2100 | printer whenever a struct described by this vtable is printed. | |
2101 | The procedure will be called with arguments STRUCT and PORT. | |
2102 | ||
2103 | The structure of a struct is described by a vtable, so the vtable is | |
2104 | in essence the type of the struct. The vtable is itself a struct with | |
2105 | a vtable. This could go on forever if it weren't for the | |
2106 | vtable-vtables which are self-describing vtables, and thus terminate | |
2107 | the chain. | |
2108 | ||
2109 | There are several potential ways of using structs, but the standard | |
2110 | one is to use three kinds of structs, together building up a type | |
2111 | sub-system: one vtable-vtable working as the root and one or several | |
2112 | "types", each with a set of "instances". (The vtable-vtable should be | |
2113 | compared to the class <class> which is the class of itself.) | |
2114 | ||
2115 | @lisp | |
2116 | (define ball-root (make-vtable-vtable "pr" 0)) | |
2117 | ||
2118 | (define (make-ball-type ball-color) | |
2119 | (make-struct ball-root 0 | |
2120 | (make-struct-layout "pw") | |
2121 | (lambda (ball port) | |
2122 | (format port "#<a ~A ball owned by ~A>" | |
2123 | (color ball) | |
2124 | (owner ball))) | |
2125 | ball-color)) | |
2126 | (define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user)) | |
2127 | (define (owner ball) (struct-ref ball 0)) | |
2128 | ||
2129 | (define red (make-ball-type 'red)) | |
2130 | (define green (make-ball-type 'green)) | |
2131 | ||
2132 | (define (make-ball type owner) (make-struct type 0 owner)) | |
2133 | ||
2134 | (define ball (make-ball green 'Nisse)) | |
2135 | ball @result{} #<a green ball owned by Nisse> | |
2136 | @end lisp | |
2137 | @end deffn | |
2138 | ||
2139 | @deffn {Scheme Procedure} struct-vtable-name vtable | |
2140 | @deffnx {C Function} scm_struct_vtable_name (vtable) | |
2141 | Return the name of the vtable @var{vtable}. | |
2142 | @end deffn | |
2143 | ||
2144 | @deffn {Scheme Procedure} set-struct-vtable-name! vtable name | |
2145 | @deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name) | |
2146 | Set the name of the vtable @var{vtable} to @var{name}. | |
2147 | @end deffn | |
2148 | ||
2149 | @deffn {Scheme Procedure} struct-vtable-tag handle | |
2150 | @deffnx {C Function} scm_struct_vtable_tag (handle) | |
2151 | Return the vtable tag of the structure @var{handle}. | |
07d83abe MV |
2152 | @end deffn |
2153 | ||
2154 | ||
2155 | @node Dictionary Types | |
2156 | @subsection Dictionary Types | |
2157 | ||
2158 | A @dfn{dictionary} object is a data structure used to index | |
2159 | information in a user-defined way. In standard Scheme, the main | |
2160 | aggregate data types are lists and vectors. Lists are not really | |
2161 | indexed at all, and vectors are indexed only by number | |
2162 | (e.g. @code{(vector-ref foo 5)}). Often you will find it useful | |
2163 | to index your data on some other type; for example, in a library | |
2164 | catalog you might want to look up a book by the name of its | |
2165 | author. Dictionaries are used to help you organize information in | |
2166 | such a way. | |
2167 | ||
2168 | An @dfn{association list} (or @dfn{alist} for short) is a list of | |
2169 | key-value pairs. Each pair represents a single quantity or | |
2170 | object; the @code{car} of the pair is a key which is used to | |
2171 | identify the object, and the @code{cdr} is the object's value. | |
2172 | ||
2173 | A @dfn{hash table} also permits you to index objects with | |
2174 | arbitrary keys, but in a way that makes looking up any one object | |
2175 | extremely fast. A well-designed hash system makes hash table | |
2176 | lookups almost as fast as conventional array or vector references. | |
2177 | ||
2178 | Alists are popular among Lisp programmers because they use only | |
2179 | the language's primitive operations (lists, @dfn{car}, @dfn{cdr} | |
2180 | and the equality primitives). No changes to the language core are | |
2181 | necessary. Therefore, with Scheme's built-in list manipulation | |
2182 | facilities, it is very convenient to handle data stored in an | |
2183 | association list. Also, alists are highly portable and can be | |
2184 | easily implemented on even the most minimal Lisp systems. | |
2185 | ||
2186 | However, alists are inefficient, especially for storing large | |
2187 | quantities of data. Because we want Guile to be useful for large | |
2188 | software systems as well as small ones, Guile provides a rich set | |
2189 | of tools for using either association lists or hash tables. | |
2190 | ||
2191 | @node Association Lists | |
2192 | @subsection Association Lists | |
2193 | @tpindex Association Lists | |
2194 | @tpindex Alist | |
2195 | ||
2196 | @cindex Association List | |
2197 | @cindex Alist | |
2198 | @cindex Database | |
2199 | ||
2200 | An association list is a conventional data structure that is often used | |
2201 | to implement simple key-value databases. It consists of a list of | |
2202 | entries in which each entry is a pair. The @dfn{key} of each entry is | |
2203 | the @code{car} of the pair and the @dfn{value} of each entry is the | |
2204 | @code{cdr}. | |
2205 | ||
2206 | @example | |
2207 | ASSOCIATION LIST ::= '( (KEY1 . VALUE1) | |
2208 | (KEY2 . VALUE2) | |
2209 | (KEY3 . VALUE3) | |
2210 | @dots{} | |
2211 | ) | |
2212 | @end example | |
2213 | ||
2214 | @noindent | |
2215 | Association lists are also known, for short, as @dfn{alists}. | |
2216 | ||
2217 | The structure of an association list is just one example of the infinite | |
2218 | number of possible structures that can be built using pairs and lists. | |
2219 | As such, the keys and values in an association list can be manipulated | |
2220 | using the general list structure procedures @code{cons}, @code{car}, | |
2221 | @code{cdr}, @code{set-car!}, @code{set-cdr!} and so on. However, | |
2222 | because association lists are so useful, Guile also provides specific | |
2223 | procedures for manipulating them. | |
2224 | ||
2225 | @menu | |
2226 | * Alist Key Equality:: | |
2227 | * Adding or Setting Alist Entries:: | |
2228 | * Retrieving Alist Entries:: | |
2229 | * Removing Alist Entries:: | |
2230 | * Sloppy Alist Functions:: | |
2231 | * Alist Example:: | |
2232 | @end menu | |
2233 | ||
2234 | @node Alist Key Equality | |
2235 | @subsubsection Alist Key Equality | |
2236 | ||
2237 | All of Guile's dedicated association list procedures, apart from | |
2238 | @code{acons}, come in three flavours, depending on the level of equality | |
2239 | that is required to decide whether an existing key in the association | |
2240 | list is the same as the key that the procedure call uses to identify the | |
2241 | required entry. | |
2242 | ||
2243 | @itemize @bullet | |
2244 | @item | |
2245 | Procedures with @dfn{assq} in their name use @code{eq?} to determine key | |
2246 | equality. | |
2247 | ||
2248 | @item | |
2249 | Procedures with @dfn{assv} in their name use @code{eqv?} to determine | |
2250 | key equality. | |
2251 | ||
2252 | @item | |
2253 | Procedures with @dfn{assoc} in their name use @code{equal?} to | |
2254 | determine key equality. | |
2255 | @end itemize | |
2256 | ||
2257 | @code{acons} is an exception because it is used to build association | |
2258 | lists which do not require their entries' keys to be unique. | |
2259 | ||
2260 | @node Adding or Setting Alist Entries | |
2261 | @subsubsection Adding or Setting Alist Entries | |
2262 | ||
2263 | @code{acons} adds a new entry to an association list and returns the | |
2264 | combined association list. The combined alist is formed by consing the | |
2265 | new entry onto the head of the alist specified in the @code{acons} | |
2266 | procedure call. So the specified alist is not modified, but its | |
2267 | contents become shared with the tail of the combined alist that | |
2268 | @code{acons} returns. | |
2269 | ||
2270 | In the most common usage of @code{acons}, a variable holding the | |
2271 | original association list is updated with the combined alist: | |
2272 | ||
2273 | @example | |
2274 | (set! address-list (acons name address address-list)) | |
2275 | @end example | |
2276 | ||
2277 | In such cases, it doesn't matter that the old and new values of | |
2278 | @code{address-list} share some of their contents, since the old value is | |
2279 | usually no longer independently accessible. | |
2280 | ||
2281 | Note that @code{acons} adds the specified new entry regardless of | |
2282 | whether the alist may already contain entries with keys that are, in | |
2283 | some sense, the same as that of the new entry. Thus @code{acons} is | |
2284 | ideal for building alists where there is no concept of key uniqueness. | |
2285 | ||
2286 | @example | |
2287 | (set! task-list (acons 3 "pay gas bill" '())) | |
2288 | task-list | |
2289 | @result{} | |
2290 | ((3 . "pay gas bill")) | |
2291 | ||
2292 | (set! task-list (acons 3 "tidy bedroom" task-list)) | |
2293 | task-list | |
2294 | @result{} | |
2295 | ((3 . "tidy bedroom") (3 . "pay gas bill")) | |
2296 | @end example | |
2297 | ||
2298 | @code{assq-set!}, @code{assv-set!} and @code{assoc-set!} are used to add | |
2299 | or replace an entry in an association list where there @emph{is} a | |
2300 | concept of key uniqueness. If the specified association list already | |
2301 | contains an entry whose key is the same as that specified in the | |
2302 | procedure call, the existing entry is replaced by the new one. | |
2303 | Otherwise, the new entry is consed onto the head of the old association | |
2304 | list to create the combined alist. In all cases, these procedures | |
2305 | return the combined alist. | |
2306 | ||
2307 | @code{assq-set!} and friends @emph{may} destructively modify the | |
2308 | structure of the old association list in such a way that an existing | |
2309 | variable is correctly updated without having to @code{set!} it to the | |
2310 | value returned: | |
2311 | ||
2312 | @example | |
2313 | address-list | |
2314 | @result{} | |
2315 | (("mary" . "34 Elm Road") ("james" . "16 Bow Street")) | |
2316 | ||
2317 | (assoc-set! address-list "james" "1a London Road") | |
2318 | @result{} | |
2319 | (("mary" . "34 Elm Road") ("james" . "1a London Road")) | |
2320 | ||
2321 | address-list | |
2322 | @result{} | |
2323 | (("mary" . "34 Elm Road") ("james" . "1a London Road")) | |
2324 | @end example | |
2325 | ||
2326 | Or they may not: | |
2327 | ||
2328 | @example | |
2329 | (assoc-set! address-list "bob" "11 Newington Avenue") | |
2330 | @result{} | |
2331 | (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road") | |
2332 | ("james" . "1a London Road")) | |
2333 | ||
2334 | address-list | |
2335 | @result{} | |
2336 | (("mary" . "34 Elm Road") ("james" . "1a London Road")) | |
2337 | @end example | |
2338 | ||
2339 | The only safe way to update an association list variable when adding or | |
2340 | replacing an entry like this is to @code{set!} the variable to the | |
2341 | returned value: | |
2342 | ||
2343 | @example | |
2344 | (set! address-list | |
2345 | (assoc-set! address-list "bob" "11 Newington Avenue")) | |
2346 | address-list | |
2347 | @result{} | |
2348 | (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road") | |
2349 | ("james" . "1a London Road")) | |
2350 | @end example | |
2351 | ||
2352 | Because of this slight inconvenience, you may find it more convenient to | |
2353 | use hash tables to store dictionary data. If your application will not | |
2354 | be modifying the contents of an alist very often, this may not make much | |
2355 | difference to you. | |
2356 | ||
2357 | If you need to keep the old value of an association list in a form | |
2358 | independent from the list that results from modification by | |
2359 | @code{acons}, @code{assq-set!}, @code{assv-set!} or @code{assoc-set!}, | |
2360 | use @code{list-copy} to copy the old association list before modifying | |
2361 | it. | |
2362 | ||
2363 | @deffn {Scheme Procedure} acons key value alist | |
2364 | @deffnx {C Function} scm_acons (key, value, alist) | |
2365 | Add a new key-value pair to @var{alist}. A new pair is | |
2366 | created whose car is @var{key} and whose cdr is @var{value}, and the | |
2367 | pair is consed onto @var{alist}, and the new list is returned. This | |
2368 | function is @emph{not} destructive; @var{alist} is not modified. | |
2369 | @end deffn | |
2370 | ||
2371 | @deffn {Scheme Procedure} assq-set! alist key val | |
2372 | @deffnx {Scheme Procedure} assv-set! alist key value | |
2373 | @deffnx {Scheme Procedure} assoc-set! alist key value | |
2374 | @deffnx {C Function} scm_assq_set_x (alist, key, val) | |
2375 | @deffnx {C Function} scm_assv_set_x (alist, key, val) | |
2376 | @deffnx {C Function} scm_assoc_set_x (alist, key, val) | |
2377 | Reassociate @var{key} in @var{alist} with @var{value}: find any existing | |
2378 | @var{alist} entry for @var{key} and associate it with the new | |
2379 | @var{value}. If @var{alist} does not contain an entry for @var{key}, | |
2380 | add a new one. Return the (possibly new) alist. | |
2381 | ||
2382 | These functions do not attempt to verify the structure of @var{alist}, | |
2383 | and so may cause unusual results if passed an object that is not an | |
2384 | association list. | |
2385 | @end deffn | |
2386 | ||
2387 | @node Retrieving Alist Entries | |
2388 | @subsubsection Retrieving Alist Entries | |
2389 | @rnindex assq | |
2390 | @rnindex assv | |
2391 | @rnindex assoc | |
2392 | ||
2393 | @code{assq}, @code{assv} and @code{assoc} take an alist and a key as | |
2394 | arguments and return the entry for that key if an entry exists, or | |
2395 | @code{#f} if there is no entry for that key. Note that, in the cases | |
2396 | where an entry exists, these procedures return the complete entry, that | |
2397 | is @code{(KEY . VALUE)}, not just the value. | |
2398 | ||
2399 | @deffn {Scheme Procedure} assq key alist | |
2400 | @deffnx {Scheme Procedure} assv key alist | |
2401 | @deffnx {Scheme Procedure} assoc key alist | |
2402 | @deffnx {C Function} scm_assq (key, alist) | |
2403 | @deffnx {C Function} scm_assv (key, alist) | |
2404 | @deffnx {C Function} scm_assoc (key, alist) | |
2405 | Fetch the entry in @var{alist} that is associated with @var{key}. To | |
2406 | decide whether the argument @var{key} matches a particular entry in | |
2407 | @var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv} | |
2408 | uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key} | |
2409 | cannot be found in @var{alist} (according to whichever equality | |
2410 | predicate is in use), then return @code{#f}. These functions | |
2411 | return the entire alist entry found (i.e. both the key and the value). | |
2412 | @end deffn | |
2413 | ||
2414 | @code{assq-ref}, @code{assv-ref} and @code{assoc-ref}, on the other | |
2415 | hand, take an alist and a key and return @emph{just the value} for that | |
2416 | key, if an entry exists. If there is no entry for the specified key, | |
2417 | these procedures return @code{#f}. | |
2418 | ||
2419 | This creates an ambiguity: if the return value is @code{#f}, it means | |
2420 | either that there is no entry with the specified key, or that there | |
2421 | @emph{is} an entry for the specified key, with value @code{#f}. | |
2422 | Consequently, @code{assq-ref} and friends should only be used where it | |
2423 | is known that an entry exists, or where the ambiguity doesn't matter | |
2424 | for some other reason. | |
2425 | ||
2426 | @deffn {Scheme Procedure} assq-ref alist key | |
2427 | @deffnx {Scheme Procedure} assv-ref alist key | |
2428 | @deffnx {Scheme Procedure} assoc-ref alist key | |
2429 | @deffnx {C Function} scm_assq_ref (alist, key) | |
2430 | @deffnx {C Function} scm_assv_ref (alist, key) | |
2431 | @deffnx {C Function} scm_assoc_ref (alist, key) | |
2432 | Like @code{assq}, @code{assv} and @code{assoc}, except that only the | |
2433 | value associated with @var{key} in @var{alist} is returned. These | |
2434 | functions are equivalent to | |
2435 | ||
2436 | @lisp | |
2437 | (let ((ent (@var{associator} @var{key} @var{alist}))) | |
2438 | (and ent (cdr ent))) | |
2439 | @end lisp | |
2440 | ||
2441 | where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}. | |
2442 | @end deffn | |
2443 | ||
2444 | @node Removing Alist Entries | |
2445 | @subsubsection Removing Alist Entries | |
2446 | ||
2447 | To remove the element from an association list whose key matches a | |
2448 | specified key, use @code{assq-remove!}, @code{assv-remove!} or | |
2449 | @code{assoc-remove!} (depending, as usual, on the level of equality | |
2450 | required between the key that you specify and the keys in the | |
2451 | association list). | |
2452 | ||
2453 | As with @code{assq-set!} and friends, the specified alist may or may not | |
2454 | be modified destructively, and the only safe way to update a variable | |
2455 | containing the alist is to @code{set!} it to the value that | |
2456 | @code{assq-remove!} and friends return. | |
2457 | ||
2458 | @example | |
2459 | address-list | |
2460 | @result{} | |
2461 | (("bob" . "11 Newington Avenue") ("mary" . "34 Elm Road") | |
2462 | ("james" . "1a London Road")) | |
2463 | ||
2464 | (set! address-list (assoc-remove! address-list "mary")) | |
2465 | address-list | |
2466 | @result{} | |
2467 | (("bob" . "11 Newington Avenue") ("james" . "1a London Road")) | |
2468 | @end example | |
2469 | ||
2470 | Note that, when @code{assq/v/oc-remove!} is used to modify an | |
2471 | association list that has been constructed only using the corresponding | |
2472 | @code{assq/v/oc-set!}, there can be at most one matching entry in the | |
2473 | alist, so the question of multiple entries being removed in one go does | |
2474 | not arise. If @code{assq/v/oc-remove!} is applied to an association | |
2475 | list that has been constructed using @code{acons}, or an | |
2476 | @code{assq/v/oc-set!} with a different level of equality, or any mixture | |
2477 | of these, it removes only the first matching entry from the alist, even | |
2478 | if the alist might contain further matching entries. For example: | |
2479 | ||
2480 | @example | |
2481 | (define address-list '()) | |
2482 | (set! address-list (assq-set! address-list "mary" "11 Elm Street")) | |
2483 | (set! address-list (assq-set! address-list "mary" "57 Pine Drive")) | |
2484 | address-list | |
2485 | @result{} | |
2486 | (("mary" . "57 Pine Drive") ("mary" . "11 Elm Street")) | |
2487 | ||
2488 | (set! address-list (assoc-remove! address-list "mary")) | |
2489 | address-list | |
2490 | @result{} | |
2491 | (("mary" . "11 Elm Street")) | |
2492 | @end example | |
2493 | ||
2494 | In this example, the two instances of the string "mary" are not the same | |
2495 | when compared using @code{eq?}, so the two @code{assq-set!} calls add | |
2496 | two distinct entries to @code{address-list}. When compared using | |
2497 | @code{equal?}, both "mary"s in @code{address-list} are the same as the | |
2498 | "mary" in the @code{assoc-remove!} call, but @code{assoc-remove!} stops | |
2499 | after removing the first matching entry that it finds, and so one of the | |
2500 | "mary" entries is left in place. | |
2501 | ||
2502 | @deffn {Scheme Procedure} assq-remove! alist key | |
2503 | @deffnx {Scheme Procedure} assv-remove! alist key | |
2504 | @deffnx {Scheme Procedure} assoc-remove! alist key | |
2505 | @deffnx {C Function} scm_assq_remove_x (alist, key) | |
2506 | @deffnx {C Function} scm_assv_remove_x (alist, key) | |
2507 | @deffnx {C Function} scm_assoc_remove_x (alist, key) | |
2508 | Delete the first entry in @var{alist} associated with @var{key}, and return | |
2509 | the resulting alist. | |
2510 | @end deffn | |
2511 | ||
2512 | @node Sloppy Alist Functions | |
2513 | @subsubsection Sloppy Alist Functions | |
2514 | ||
2515 | @code{sloppy-assq}, @code{sloppy-assv} and @code{sloppy-assoc} behave | |
2516 | like the corresponding non-@code{sloppy-} procedures, except that they | |
2517 | return @code{#f} when the specified association list is not well-formed, | |
2518 | where the non-@code{sloppy-} versions would signal an error. | |
2519 | ||
2520 | Specifically, there are two conditions for which the non-@code{sloppy-} | |
2521 | procedures signal an error, which the @code{sloppy-} procedures handle | |
2522 | instead by returning @code{#f}. Firstly, if the specified alist as a | |
2523 | whole is not a proper list: | |
2524 | ||
2525 | @example | |
2526 | (assoc "mary" '((1 . 2) ("key" . "door") . "open sesame")) | |
2527 | @result{} | |
2528 | ERROR: In procedure assoc in expression (assoc "mary" (quote #)): | |
2529 | ERROR: Wrong type argument in position 2 (expecting association list): ((1 . 2) ("key" . "door") . "open sesame") | |
2530 | ||
2531 | (sloppy-assoc "mary" '((1 . 2) ("key" . "door") . "open sesame")) | |
2532 | @result{} | |
2533 | #f | |
2534 | @end example | |
2535 | ||
2536 | @noindent | |
2537 | Secondly, if one of the entries in the specified alist is not a pair: | |
2538 | ||
2539 | @example | |
2540 | (assoc 2 '((1 . 1) 2 (3 . 9))) | |
2541 | @result{} | |
2542 | ERROR: In procedure assoc in expression (assoc 2 (quote #)): | |
2543 | ERROR: Wrong type argument in position 2 (expecting association list): ((1 . 1) 2 (3 . 9)) | |
2544 | ||
2545 | (sloppy-assoc 2 '((1 . 1) 2 (3 . 9))) | |
2546 | @result{} | |
2547 | #f | |
2548 | @end example | |
2549 | ||
2550 | Unless you are explicitly working with badly formed association lists, | |
2551 | it is much safer to use the non-@code{sloppy-} procedures, because they | |
2552 | help to highlight coding and data errors that the @code{sloppy-} | |
2553 | versions would silently cover up. | |
2554 | ||
2555 | @deffn {Scheme Procedure} sloppy-assq key alist | |
2556 | @deffnx {C Function} scm_sloppy_assq (key, alist) | |
2557 | Behaves like @code{assq} but does not do any error checking. | |
2558 | Recommended only for use in Guile internals. | |
2559 | @end deffn | |
2560 | ||
2561 | @deffn {Scheme Procedure} sloppy-assv key alist | |
2562 | @deffnx {C Function} scm_sloppy_assv (key, alist) | |
2563 | Behaves like @code{assv} but does not do any error checking. | |
2564 | Recommended only for use in Guile internals. | |
2565 | @end deffn | |
2566 | ||
2567 | @deffn {Scheme Procedure} sloppy-assoc key alist | |
2568 | @deffnx {C Function} scm_sloppy_assoc (key, alist) | |
2569 | Behaves like @code{assoc} but does not do any error checking. | |
2570 | Recommended only for use in Guile internals. | |
2571 | @end deffn | |
2572 | ||
2573 | @node Alist Example | |
2574 | @subsubsection Alist Example | |
2575 | ||
2576 | Here is a longer example of how alists may be used in practice. | |
2577 | ||
2578 | @lisp | |
2579 | (define capitals '(("New York" . "Albany") | |
2580 | ("Oregon" . "Salem") | |
2581 | ("Florida" . "Miami"))) | |
2582 | ||
2583 | ;; What's the capital of Oregon? | |
2584 | (assoc "Oregon" capitals) @result{} ("Oregon" . "Salem") | |
2585 | (assoc-ref capitals "Oregon") @result{} "Salem" | |
2586 | ||
2587 | ;; We left out South Dakota. | |
2588 | (set! capitals | |
2589 | (assoc-set! capitals "South Dakota" "Pierre")) | |
2590 | capitals | |
2591 | @result{} (("South Dakota" . "Pierre") | |
2592 | ("New York" . "Albany") | |
2593 | ("Oregon" . "Salem") | |
2594 | ("Florida" . "Miami")) | |
2595 | ||
2596 | ;; And we got Florida wrong. | |
2597 | (set! capitals | |
2598 | (assoc-set! capitals "Florida" "Tallahassee")) | |
2599 | capitals | |
2600 | @result{} (("South Dakota" . "Pierre") | |
2601 | ("New York" . "Albany") | |
2602 | ("Oregon" . "Salem") | |
2603 | ("Florida" . "Tallahassee")) | |
2604 | ||
2605 | ;; After Oregon secedes, we can remove it. | |
2606 | (set! capitals | |
2607 | (assoc-remove! capitals "Oregon")) | |
2608 | capitals | |
2609 | @result{} (("South Dakota" . "Pierre") | |
2610 | ("New York" . "Albany") | |
2611 | ("Florida" . "Tallahassee")) | |
2612 | @end lisp | |
2613 | ||
2614 | @node Hash Tables | |
2615 | @subsection Hash Tables | |
2616 | @tpindex Hash Tables | |
2617 | ||
2618 | @c FIXME::martin: Review me! | |
2619 | ||
2620 | Hash tables are dictionaries which offer similar functionality as | |
2621 | association lists: They provide a mapping from keys to values. The | |
2622 | difference is that association lists need time linear in the size of | |
2623 | elements when searching for entries, whereas hash tables can normally | |
2624 | search in constant time. The drawback is that hash tables require a | |
2625 | little bit more memory, and that you can not use the normal list | |
2626 | procedures (@pxref{Lists}) for working with them. | |
2627 | ||
2628 | @menu | |
2629 | * Hash Table Examples:: Demonstration of hash table usage. | |
2630 | * Hash Table Reference:: Hash table procedure descriptions. | |
2631 | @end menu | |
2632 | ||
2633 | ||
2634 | @node Hash Table Examples | |
2635 | @subsubsection Hash Table Examples | |
2636 | ||
2637 | @c FIXME::martin: Review me! | |
2638 | ||
2639 | For demonstration purposes, this section gives a few usage examples of | |
2640 | some hash table procedures, together with some explanation what they do. | |
2641 | ||
2642 | First we start by creating a new hash table with 31 slots, and | |
2643 | populate it with two key/value pairs. | |
2644 | ||
2645 | @lisp | |
2646 | (define h (make-hash-table 31)) | |
2647 | ||
2648 | (hashq-create-handle! h 'foo "bar") | |
2649 | @result{} | |
2650 | (foo . "bar") | |
2651 | ||
2652 | (hashq-create-handle! h 'braz "zonk") | |
2653 | @result{} | |
2654 | (braz . "zonk") | |
2655 | ||
2656 | (hashq-create-handle! h 'frob #f) | |
2657 | @result{} | |
2658 | (frob . #f) | |
2659 | @end lisp | |
2660 | ||
2661 | You can get the value for a given key with the procedure | |
2662 | @code{hashq-ref}, but the problem with this procedure is that you | |
2663 | cannot reliably determine whether a key does exists in the table. The | |
2664 | reason is that the procedure returns @code{#f} if the key is not in | |
2665 | the table, but it will return the same value if the key is in the | |
2666 | table and just happens to have the value @code{#f}, as you can see in | |
2667 | the following examples. | |
2668 | ||
2669 | @lisp | |
2670 | (hashq-ref h 'foo) | |
2671 | @result{} | |
2672 | "bar" | |
2673 | ||
2674 | (hashq-ref h 'frob) | |
2675 | @result{} | |
2676 | #f | |
2677 | ||
2678 | (hashq-ref h 'not-there) | |
2679 | @result{} | |
2680 | #f | |
2681 | @end lisp | |
2682 | ||
2683 | Better is to use the procedure @code{hashq-get-handle}, which makes a | |
2684 | distinction between the two cases. Just like @code{assq}, this | |
2685 | procedure returns a key/value-pair on success, and @code{#f} if the | |
2686 | key is not found. | |
2687 | ||
2688 | @lisp | |
2689 | (hashq-get-handle h 'foo) | |
2690 | @result{} | |
2691 | (foo . "bar") | |
2692 | ||
2693 | (hashq-get-handle h 'not-there) | |
2694 | @result{} | |
2695 | #f | |
2696 | @end lisp | |
2697 | ||
2698 | There is no procedure for calculating the number of key/value-pairs in | |
2699 | a hash table, but @code{hash-fold} can be used for doing exactly that. | |
2700 | ||
2701 | @lisp | |
2702 | (hash-fold (lambda (key value seed) (+ 1 seed)) 0 h) | |
2703 | @result{} | |
2704 | 3 | |
2705 | @end lisp | |
2706 | ||
2707 | @node Hash Table Reference | |
2708 | @subsubsection Hash Table Reference | |
2709 | ||
2710 | @c FIXME: Describe in broad terms what happens for resizing, and what | |
2711 | @c the initial size means for this. | |
2712 | ||
2713 | Like the association list functions, the hash table functions come in | |
2714 | several varieties, according to the equality test used for the keys. | |
2715 | Plain @code{hash-} functions use @code{equal?}, @code{hashq-} | |
2716 | functions use @code{eq?}, @code{hashv-} functions use @code{eqv?}, and | |
2717 | the @code{hashx-} functions use an application supplied test. | |
2718 | ||
2719 | A single @code{make-hash-table} creates a hash table suitable for use | |
2720 | with any set of functions, but it's imperative that just one set is | |
2721 | then used consistently, or results will be unpredictable. | |
2722 | ||
2723 | @sp 1 | |
2724 | Hash tables are implemented as a vector indexed by a hash value formed | |
2725 | from the key, with an association list of key/value pairs for each | |
2726 | bucket in case distinct keys hash together. Direct access to the | |
2727 | pairs in those lists is provided by the @code{-handle-} functions. | |
2728 | ||
2729 | When the number of table entries goes above a threshold the vector is | |
2730 | increased and the entries rehashed, to prevent the bucket lists | |
2731 | becoming too long and slowing down accesses. When the number of | |
2732 | entries goes below a threshold the vector is decreased to save space. | |
2733 | ||
2734 | @sp 1 | |
2735 | For the @code{hashx-} ``extended'' routines, an application supplies a | |
2736 | @var{hash} function producing an integer index like @code{hashq} etc | |
2737 | below, and an @var{assoc} alist search function like @code{assq} etc | |
2738 | (@pxref{Retrieving Alist Entries}). Here's an example of such | |
2739 | functions implementing case-insensitive hashing of string keys, | |
2740 | ||
2741 | @example | |
2742 | (use-modules (srfi srfi-1) | |
2743 | (srfi srfi-13)) | |
2744 | ||
2745 | (define (my-hash str size) | |
2746 | (remainder (string-hash-ci str) size)) | |
2747 | (define (my-assoc str alist) | |
2748 | (find (lambda (pair) (string-ci=? str (car pair))) alist)) | |
2749 | ||
2750 | (define my-table (make-hash-table)) | |
2751 | (hashx-set! my-hash my-assoc my-table "foo" 123) | |
2752 | ||
2753 | (hashx-ref my-hash my-assoc my-table "FOO") | |
2754 | @result{} 123 | |
2755 | @end example | |
2756 | ||
2757 | In a @code{hashx-} @var{hash} function the aim is to spread keys | |
2758 | across the vector, so bucket lists don't become long. But the actual | |
2759 | values are arbitrary as long as they're in the range 0 to | |
2760 | @math{@var{size}-1}. Helpful functions for forming a hash value, in | |
2761 | addition to @code{hashq} etc below, include @code{symbol-hash} | |
2762 | (@pxref{Symbol Keys}), @code{string-hash} and @code{string-hash-ci} | |
4a3057fc | 2763 | (@pxref{String Comparison}), and @code{char-set-hash} |
5354f4ab | 2764 | (@pxref{Character Set Predicates/Comparison}). |
07d83abe MV |
2765 | |
2766 | Note that currently, unfortunately, there's no @code{hashx-remove!} | |
2767 | function, which rather limits the usefulness of the @code{hashx-} | |
2768 | routines. | |
2769 | ||
2770 | @sp 1 | |
2771 | @deffn {Scheme Procedure} make-hash-table [size] | |
2772 | Create a new hash table, with an optional minimum vector @var{size}. | |
2773 | ||
2774 | When @var{size} is given, the table vector will still grow and shrink | |
2775 | automatically, as described above, but with @var{size} as a minimum. | |
2776 | If an application knows roughly how many entries the table will hold | |
2777 | then it can use @var{size} to avoid rehashing when initial entries are | |
2778 | added. | |
2779 | @end deffn | |
2780 | ||
cdf1ad3b MV |
2781 | @deffn {Scheme Procedure} hash-table? obj |
2782 | @deffnx {C Function} scm_hash_table_p (obj) | |
2783 | Return @code{#t} if @var{obj} is a hash table. | |
2784 | @end deffn | |
2785 | ||
2786 | @deffn {Scheme Procedure} hash-clear! table | |
2787 | @deffnx {C Function} scm_hash_clear_x (table) | |
2788 | Remove all items from TABLE (without triggering a resize). | |
2789 | @end deffn | |
2790 | ||
07d83abe MV |
2791 | @deffn {Scheme Procedure} hash-ref table key [dflt] |
2792 | @deffnx {Scheme Procedure} hashq-ref table key [dflt] | |
2793 | @deffnx {Scheme Procedure} hashv-ref table key [dflt] | |
2794 | @deffnx {Scheme Procedure} hashx-ref hash assoc table key [dflt] | |
2795 | @deffnx {C Function} scm_hash_ref (table, key, dflt) | |
2796 | @deffnx {C Function} scm_hashq_ref (table, key, dflt) | |
2797 | @deffnx {C Function} scm_hashv_ref (table, key, dflt) | |
2798 | @deffnx {C Function} scm_hashx_ref (hash, assoc, table, key, dflt) | |
2799 | Lookup @var{key} in the given hash @var{table}, and return the | |
2800 | associated value. If @var{key} is not found, return @var{dflt}, or | |
2801 | @code{#f} if @var{dflt} is not given. | |
2802 | @end deffn | |
2803 | ||
2804 | @deffn {Scheme Procedure} hash-set! table key val | |
2805 | @deffnx {Scheme Procedure} hashq-set! table key val | |
2806 | @deffnx {Scheme Procedure} hashv-set! table key val | |
2807 | @deffnx {Scheme Procedure} hashx-set! hash assoc table key val | |
2808 | @deffnx {C Function} scm_hash_set_x (table, key, val) | |
2809 | @deffnx {C Function} scm_hashq_set_x (table, key, val) | |
2810 | @deffnx {C Function} scm_hashv_set_x (table, key, val) | |
2811 | @deffnx {C Function} scm_hashx_set_x (hash, assoc, table, key, val) | |
2812 | Associate @var{val} with @var{key} in the given hash @var{table}. If | |
2813 | @var{key} is already present then it's associated value is changed. | |
2814 | If it's not present then a new entry is created. | |
2815 | @end deffn | |
2816 | ||
2817 | @deffn {Scheme Procedure} hash-remove! table key | |
2818 | @deffnx {Scheme Procedure} hashq-remove! table key | |
2819 | @deffnx {Scheme Procedure} hashv-remove! table key | |
2820 | @deffnx {C Function} scm_hash_remove_x (table, key) | |
2821 | @deffnx {C Function} scm_hashq_remove_x (table, key) | |
2822 | @deffnx {C Function} scm_hashv_remove_x (table, key) | |
2823 | Remove any association for @var{key} in the given hash @var{table}. | |
2824 | If @var{key} is not in @var{table} then nothing is done. | |
2825 | @end deffn | |
2826 | ||
2827 | @deffn {Scheme Procedure} hash key size | |
2828 | @deffnx {Scheme Procedure} hashq key size | |
2829 | @deffnx {Scheme Procedure} hashv key size | |
2830 | @deffnx {C Function} scm_hash (key, size) | |
2831 | @deffnx {C Function} scm_hashq (key, size) | |
2832 | @deffnx {C Function} scm_hashv (key, size) | |
2833 | Return a hash value for @var{key}. This is a number in the range | |
2834 | @math{0} to @math{@var{size}-1}, which is suitable for use in a hash | |
2835 | table of the given @var{size}. | |
2836 | ||
2837 | Note that @code{hashq} and @code{hashv} may use internal addresses of | |
2838 | objects, so if an object is garbage collected and re-created it can | |
2839 | have a different hash value, even when the two are notionally | |
2840 | @code{eq?}. For instance with symbols, | |
2841 | ||
2842 | @example | |
2843 | (hashq 'something 123) @result{} 19 | |
2844 | (gc) | |
2845 | (hashq 'something 123) @result{} 62 | |
2846 | @end example | |
2847 | ||
2848 | In normal use this is not a problem, since an object entered into a | |
2849 | hash table won't be garbage collected until removed. It's only if | |
2850 | hashing calculations are somehow separated from normal references that | |
2851 | its lifetime needs to be considered. | |
2852 | @end deffn | |
2853 | ||
2854 | @deffn {Scheme Procedure} hash-get-handle table key | |
2855 | @deffnx {Scheme Procedure} hashq-get-handle table key | |
2856 | @deffnx {Scheme Procedure} hashv-get-handle table key | |
2857 | @deffnx {Scheme Procedure} hashx-get-handle hash assoc table key | |
2858 | @deffnx {C Function} scm_hash_get_handle (table, key) | |
2859 | @deffnx {C Function} scm_hashq_get_handle (table, key) | |
2860 | @deffnx {C Function} scm_hashv_get_handle (table, key) | |
2861 | @deffnx {C Function} scm_hashx_get_handle (hash, assoc, table, key) | |
2862 | Return the @code{(@var{key} . @var{value})} pair for @var{key} in the | |
2863 | given hash @var{table}, or @code{#f} if @var{key} is not in | |
2864 | @var{table}. | |
2865 | @end deffn | |
2866 | ||
2867 | @deffn {Scheme Procedure} hash-create-handle! table key init | |
2868 | @deffnx {Scheme Procedure} hashq-create-handle! table key init | |
2869 | @deffnx {Scheme Procedure} hashv-create-handle! table key init | |
2870 | @deffnx {Scheme Procedure} hashx-create-handle! hash assoc table key init | |
2871 | @deffnx {C Function} scm_hash_create_handle_x (table, key, init) | |
2872 | @deffnx {C Function} scm_hashq_create_handle_x (table, key, init) | |
2873 | @deffnx {C Function} scm_hashv_create_handle_x (table, key, init) | |
2874 | @deffnx {C Function} scm_hashx_create_handle_x (hash, assoc, table, key, init) | |
2875 | Return the @code{(@var{key} . @var{value})} pair for @var{key} in the | |
2876 | given hash @var{table}. If @var{key} is not in @var{table} then | |
2877 | create an entry for it with @var{init} as the value, and return that | |
2878 | pair. | |
2879 | @end deffn | |
2880 | ||
2881 | @deffn {Scheme Procedure} hash-map->list proc table | |
2882 | @deffnx {Scheme Procedure} hash-for-each proc table | |
2883 | @deffnx {C Function} scm_hash_map_to_list (proc, table) | |
2884 | @deffnx {C Function} scm_hash_for_each (proc, table) | |
2885 | Apply @var{proc} to the entries in the given hash @var{table}. Each | |
2886 | call is @code{(@var{proc} @var{key} @var{value})}. @code{hash-map->list} | |
2887 | returns a list of the results from these calls, @code{hash-for-each} | |
2888 | discards the results and returns an unspecified value. | |
2889 | ||
2890 | Calls are made over the table entries in an unspecified order, and for | |
2891 | @code{hash-map->list} the order of the values in the returned list is | |
2892 | unspecified. Results will be unpredictable if @var{table} is modified | |
2893 | while iterating. | |
2894 | ||
2895 | For example the following returns a new alist comprising all the | |
2896 | entries from @code{mytable}, in no particular order. | |
2897 | ||
2898 | @example | |
2899 | (hash-map->list cons mytable) | |
2900 | @end example | |
2901 | @end deffn | |
2902 | ||
2903 | @deffn {Scheme Procedure} hash-for-each-handle proc table | |
2904 | @deffnx {C Function} scm_hash_for_each_handle (proc, table) | |
2905 | Apply @var{proc} to the entries in the given hash @var{table}. Each | |
2906 | call is @code{(@var{proc} @var{handle})}, where @var{handle} is a | |
2907 | @code{(@var{key} . @var{value})} pair. Return an unspecified value. | |
2908 | ||
2909 | @code{hash-for-each-handle} differs from @code{hash-for-each} only in | |
2910 | the argument list of @var{proc}. | |
2911 | @end deffn | |
2912 | ||
2913 | @deffn {Scheme Procedure} hash-fold proc init table | |
2914 | @deffnx {C Function} scm_hash_fold (proc, init, table) | |
2915 | Accumulate a result by applying @var{proc} to the elements of the | |
2916 | given hash @var{table}. Each call is @code{(@var{proc} @var{key} | |
2917 | @var{value} @var{prior-result})}, where @var{key} and @var{value} are | |
2918 | from the @var{table} and @var{prior-result} is the return from the | |
2919 | previous @var{proc} call. For the first call, @var{prior-result} is | |
2920 | the given @var{init} value. | |
2921 | ||
2922 | Calls are made over the table entries in an unspecified order. | |
2923 | Results will be unpredictable if @var{table} is modified while | |
2924 | @code{hash-fold} is running. | |
2925 | ||
2926 | For example, the following returns a count of how many keys in | |
2927 | @code{mytable} are strings. | |
2928 | ||
2929 | @example | |
2930 | (hash-fold (lambda (key value prior) | |
2931 | (if (string? key) (1+ prior) prior)) | |
2932 | 0 mytable) | |
2933 | @end example | |
2934 | @end deffn | |
2935 | ||
2936 | ||
2937 | @c Local Variables: | |
2938 | @c TeX-master: "guile.texi" | |
2939 | @c End: |