Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
b242715b | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009 |
07d83abe MV |
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. | |
61eed960 | 25 | * Uniform Numeric Vectors:: Vectors with elements of a single numeric type. |
e6b226b9 | 26 | * Bit Vectors:: Vectors of bits. |
61eed960 | 27 | * Generalized Vectors:: Treating all vector-like things uniformly. |
e6b226b9 | 28 | * Arrays:: Matrices, etc. |
07d83abe MV |
29 | * Records:: |
30 | * Structures:: | |
07d83abe MV |
31 | * Dictionary Types:: About dictionary types in general. |
32 | * Association Lists:: List-based dictionaries. | |
33 | * Hash Tables:: Table-based dictionaries. | |
34 | @end menu | |
35 | ||
36 | ||
37 | @node Pairs | |
38 | @subsection Pairs | |
39 | @tpindex Pairs | |
40 | ||
41 | Pairs are used to combine two Scheme objects into one compound object. | |
42 | Hence the name: A pair stores a pair of objects. | |
43 | ||
44 | The data type @dfn{pair} is extremely important in Scheme, just like in | |
45 | any other Lisp dialect. The reason is that pairs are not only used to | |
46 | make two values available as one object, but that pairs are used for | |
47 | constructing lists of values. Because lists are so important in Scheme, | |
48 | they are described in a section of their own (@pxref{Lists}). | |
49 | ||
50 | Pairs can literally get entered in source code or at the REPL, in the | |
51 | so-called @dfn{dotted list} syntax. This syntax consists of an opening | |
52 | parentheses, the first element of the pair, a dot, the second element | |
53 | and a closing parentheses. The following example shows how a pair | |
54 | consisting of the two numbers 1 and 2, and a pair containing the symbols | |
55 | @code{foo} and @code{bar} can be entered. It is very important to write | |
56 | the whitespace before and after the dot, because otherwise the Scheme | |
57 | parser would not be able to figure out where to split the tokens. | |
58 | ||
59 | @lisp | |
60 | (1 . 2) | |
61 | (foo . bar) | |
62 | @end lisp | |
63 | ||
64 | But beware, if you want to try out these examples, you have to | |
65 | @dfn{quote} the expressions. More information about quotation is | |
51ee57a4 KR |
66 | available in the section @ref{Expression Syntax}. The correct way |
67 | to try these examples is as follows. | |
07d83abe MV |
68 | |
69 | @lisp | |
70 | '(1 . 2) | |
71 | @result{} | |
72 | (1 . 2) | |
73 | '(foo . bar) | |
74 | @result{} | |
75 | (foo . bar) | |
76 | @end lisp | |
77 | ||
78 | A new pair is made by calling the procedure @code{cons} with two | |
79 | arguments. Then the argument values are stored into a newly allocated | |
80 | pair, and the pair is returned. The name @code{cons} stands for | |
81 | "construct". Use the procedure @code{pair?} to test whether a | |
82 | given Scheme object is a pair or not. | |
83 | ||
84 | @rnindex cons | |
85 | @deffn {Scheme Procedure} cons x y | |
86 | @deffnx {C Function} scm_cons (x, y) | |
87 | Return a newly allocated pair whose car is @var{x} and whose | |
88 | cdr is @var{y}. The pair is guaranteed to be different (in the | |
89 | sense of @code{eq?}) from every previously existing object. | |
90 | @end deffn | |
91 | ||
92 | @rnindex pair? | |
93 | @deffn {Scheme Procedure} pair? x | |
94 | @deffnx {C Function} scm_pair_p (x) | |
95 | Return @code{#t} if @var{x} is a pair; otherwise return | |
96 | @code{#f}. | |
97 | @end deffn | |
98 | ||
7f4c83e3 MV |
99 | @deftypefn {C Function} int scm_is_pair (SCM x) |
100 | Return 1 when @var{x} is a pair; otherwise return 0. | |
101 | @end deftypefn | |
102 | ||
07d83abe MV |
103 | The two parts of a pair are traditionally called @dfn{car} and |
104 | @dfn{cdr}. They can be retrieved with procedures of the same name | |
105 | (@code{car} and @code{cdr}), and can be modified with the procedures | |
106 | @code{set-car!} and @code{set-cdr!}. Since a very common operation in | |
35f957b2 MV |
107 | Scheme programs is to access the car of a car of a pair, or the car of |
108 | the cdr of a pair, etc., the procedures called @code{caar}, | |
109 | @code{cadr} and so on are also predefined. | |
07d83abe MV |
110 | |
111 | @rnindex car | |
112 | @rnindex cdr | |
113 | @deffn {Scheme Procedure} car pair | |
114 | @deffnx {Scheme Procedure} cdr pair | |
7f4c83e3 MV |
115 | @deffnx {C Function} scm_car (pair) |
116 | @deffnx {C Function} scm_cdr (pair) | |
07d83abe MV |
117 | Return the car or the cdr of @var{pair}, respectively. |
118 | @end deffn | |
119 | ||
35f957b2 MV |
120 | @deftypefn {C Macro} SCM SCM_CAR (SCM pair) |
121 | @deftypefnx {C Macro} SCM SCM_CDR (SCM pair) | |
122 | These two macros are the fastest way to access the car or cdr of a | |
123 | pair; they can be thought of as compiling into a single memory | |
124 | reference. | |
125 | ||
126 | These macros do no checking at all. The argument @var{pair} must be a | |
127 | valid pair. | |
128 | @end deftypefn | |
129 | ||
7f4c83e3 MV |
130 | @deffn {Scheme Procedure} cddr pair |
131 | @deffnx {Scheme Procedure} cdar pair | |
132 | @deffnx {Scheme Procedure} cadr pair | |
133 | @deffnx {Scheme Procedure} caar pair | |
134 | @deffnx {Scheme Procedure} cdddr pair | |
135 | @deffnx {Scheme Procedure} cddar pair | |
136 | @deffnx {Scheme Procedure} cdadr pair | |
137 | @deffnx {Scheme Procedure} cdaar pair | |
138 | @deffnx {Scheme Procedure} caddr pair | |
139 | @deffnx {Scheme Procedure} cadar pair | |
140 | @deffnx {Scheme Procedure} caadr pair | |
141 | @deffnx {Scheme Procedure} caaar pair | |
07d83abe | 142 | @deffnx {Scheme Procedure} cddddr pair |
7f4c83e3 MV |
143 | @deffnx {Scheme Procedure} cdddar pair |
144 | @deffnx {Scheme Procedure} cddadr pair | |
145 | @deffnx {Scheme Procedure} cddaar pair | |
146 | @deffnx {Scheme Procedure} cdaddr pair | |
147 | @deffnx {Scheme Procedure} cdadar pair | |
148 | @deffnx {Scheme Procedure} cdaadr pair | |
149 | @deffnx {Scheme Procedure} cdaaar pair | |
150 | @deffnx {Scheme Procedure} cadddr pair | |
151 | @deffnx {Scheme Procedure} caddar pair | |
152 | @deffnx {Scheme Procedure} cadadr pair | |
153 | @deffnx {Scheme Procedure} cadaar pair | |
154 | @deffnx {Scheme Procedure} caaddr pair | |
155 | @deffnx {Scheme Procedure} caadar pair | |
156 | @deffnx {Scheme Procedure} caaadr pair | |
157 | @deffnx {Scheme Procedure} caaaar pair | |
158 | @deffnx {C Function} scm_cddr (pair) | |
159 | @deffnx {C Function} scm_cdar (pair) | |
160 | @deffnx {C Function} scm_cadr (pair) | |
161 | @deffnx {C Function} scm_caar (pair) | |
162 | @deffnx {C Function} scm_cdddr (pair) | |
163 | @deffnx {C Function} scm_cddar (pair) | |
164 | @deffnx {C Function} scm_cdadr (pair) | |
165 | @deffnx {C Function} scm_cdaar (pair) | |
166 | @deffnx {C Function} scm_caddr (pair) | |
167 | @deffnx {C Function} scm_cadar (pair) | |
168 | @deffnx {C Function} scm_caadr (pair) | |
169 | @deffnx {C Function} scm_caaar (pair) | |
170 | @deffnx {C Function} scm_cddddr (pair) | |
171 | @deffnx {C Function} scm_cdddar (pair) | |
172 | @deffnx {C Function} scm_cddadr (pair) | |
173 | @deffnx {C Function} scm_cddaar (pair) | |
174 | @deffnx {C Function} scm_cdaddr (pair) | |
175 | @deffnx {C Function} scm_cdadar (pair) | |
176 | @deffnx {C Function} scm_cdaadr (pair) | |
177 | @deffnx {C Function} scm_cdaaar (pair) | |
178 | @deffnx {C Function} scm_cadddr (pair) | |
179 | @deffnx {C Function} scm_caddar (pair) | |
180 | @deffnx {C Function} scm_cadadr (pair) | |
181 | @deffnx {C Function} scm_cadaar (pair) | |
182 | @deffnx {C Function} scm_caaddr (pair) | |
183 | @deffnx {C Function} scm_caadar (pair) | |
184 | @deffnx {C Function} scm_caaadr (pair) | |
185 | @deffnx {C Function} scm_caaaar (pair) | |
07d83abe MV |
186 | These procedures are compositions of @code{car} and @code{cdr}, where |
187 | for example @code{caddr} could be defined by | |
188 | ||
189 | @lisp | |
190 | (define caddr (lambda (x) (car (cdr (cdr x))))) | |
191 | @end lisp | |
23f2b9a3 KR |
192 | |
193 | @code{cadr}, @code{caddr} and @code{cadddr} pick out the second, third | |
194 | or fourth elements of a list, respectively. SRFI-1 provides the same | |
195 | under the names @code{second}, @code{third} and @code{fourth} | |
196 | (@pxref{SRFI-1 Selectors}). | |
07d83abe MV |
197 | @end deffn |
198 | ||
199 | @rnindex set-car! | |
200 | @deffn {Scheme Procedure} set-car! pair value | |
201 | @deffnx {C Function} scm_set_car_x (pair, value) | |
202 | Stores @var{value} in the car field of @var{pair}. The value returned | |
203 | by @code{set-car!} is unspecified. | |
204 | @end deffn | |
205 | ||
206 | @rnindex set-cdr! | |
207 | @deffn {Scheme Procedure} set-cdr! pair value | |
208 | @deffnx {C Function} scm_set_cdr_x (pair, value) | |
209 | Stores @var{value} in the cdr field of @var{pair}. The value returned | |
210 | by @code{set-cdr!} is unspecified. | |
211 | @end deffn | |
212 | ||
213 | ||
214 | @node Lists | |
215 | @subsection Lists | |
216 | @tpindex Lists | |
217 | ||
218 | A very important data type in Scheme---as well as in all other Lisp | |
219 | dialects---is the data type @dfn{list}.@footnote{Strictly speaking, | |
220 | Scheme does not have a real datatype @dfn{list}. Lists are made up of | |
221 | @dfn{chained pairs}, and only exist by definition---a list is a chain | |
222 | of pairs which looks like a list.} | |
223 | ||
224 | This is the short definition of what a list is: | |
225 | ||
226 | @itemize @bullet | |
227 | @item | |
228 | Either the empty list @code{()}, | |
229 | ||
230 | @item | |
231 | or a pair which has a list in its cdr. | |
232 | @end itemize | |
233 | ||
234 | @c FIXME::martin: Describe the pair chaining in more detail. | |
235 | ||
236 | @c FIXME::martin: What is a proper, what an improper list? | |
237 | @c What is a circular list? | |
238 | ||
239 | @c FIXME::martin: Maybe steal some graphics from the Elisp reference | |
240 | @c manual? | |
241 | ||
242 | @menu | |
243 | * List Syntax:: Writing literal lists. | |
244 | * List Predicates:: Testing lists. | |
245 | * List Constructors:: Creating new lists. | |
246 | * List Selection:: Selecting from lists, getting their length. | |
247 | * Append/Reverse:: Appending and reversing lists. | |
248 | * List Modification:: Modifying existing lists. | |
249 | * List Searching:: Searching for list elements | |
250 | * List Mapping:: Applying procedures to lists. | |
251 | @end menu | |
252 | ||
253 | @node List Syntax | |
254 | @subsubsection List Read Syntax | |
255 | ||
256 | The syntax for lists is an opening parentheses, then all the elements of | |
257 | the list (separated by whitespace) and finally a closing | |
258 | parentheses.@footnote{Note that there is no separation character between | |
259 | the list elements, like a comma or a semicolon.}. | |
260 | ||
261 | @lisp | |
262 | (1 2 3) ; @r{a list of the numbers 1, 2 and 3} | |
263 | ("foo" bar 3.1415) ; @r{a string, a symbol and a real number} | |
264 | () ; @r{the empty list} | |
265 | @end lisp | |
266 | ||
267 | The last example needs a bit more explanation. A list with no elements, | |
268 | called the @dfn{empty list}, is special in some ways. It is used for | |
269 | terminating lists by storing it into the cdr of the last pair that makes | |
270 | up a list. An example will clear that up: | |
271 | ||
272 | @lisp | |
273 | (car '(1)) | |
274 | @result{} | |
275 | 1 | |
276 | (cdr '(1)) | |
277 | @result{} | |
278 | () | |
279 | @end lisp | |
280 | ||
51ee57a4 KR |
281 | This example also shows that lists have to be quoted when written |
282 | (@pxref{Expression Syntax}), because they would otherwise be | |
283 | mistakingly taken as procedure applications (@pxref{Simple | |
284 | Invocation}). | |
07d83abe MV |
285 | |
286 | ||
287 | @node List Predicates | |
288 | @subsubsection List Predicates | |
289 | ||
290 | Often it is useful to test whether a given Scheme object is a list or | |
291 | not. List-processing procedures could use this information to test | |
292 | whether their input is valid, or they could do different things | |
293 | depending on the datatype of their arguments. | |
294 | ||
295 | @rnindex list? | |
296 | @deffn {Scheme Procedure} list? x | |
297 | @deffnx {C Function} scm_list_p (x) | |
298 | Return @code{#t} iff @var{x} is a proper list, else @code{#f}. | |
299 | @end deffn | |
300 | ||
301 | The predicate @code{null?} is often used in list-processing code to | |
302 | tell whether a given list has run out of elements. That is, a loop | |
303 | somehow deals with the elements of a list until the list satisfies | |
304 | @code{null?}. Then, the algorithm terminates. | |
305 | ||
306 | @rnindex null? | |
307 | @deffn {Scheme Procedure} null? x | |
308 | @deffnx {C Function} scm_null_p (x) | |
309 | Return @code{#t} iff @var{x} is the empty list, else @code{#f}. | |
310 | @end deffn | |
311 | ||
7f4c83e3 MV |
312 | @deftypefn {C Function} int scm_is_null (SCM x) |
313 | Return 1 when @var{x} is the empty list; otherwise return 0. | |
314 | @end deftypefn | |
315 | ||
316 | ||
07d83abe MV |
317 | @node List Constructors |
318 | @subsubsection List Constructors | |
319 | ||
320 | This section describes the procedures for constructing new lists. | |
321 | @code{list} simply returns a list where the elements are the arguments, | |
322 | @code{cons*} is similar, but the last argument is stored in the cdr of | |
323 | the last pair of the list. | |
324 | ||
325 | @c C Function scm_list(rest) used to be documented here, but it's a | |
326 | @c no-op since it does nothing but return the list the caller must | |
327 | @c have already created. | |
328 | @c | |
329 | @deffn {Scheme Procedure} list elem1 @dots{} elemN | |
330 | @deffnx {C Function} scm_list_1 (elem1) | |
331 | @deffnx {C Function} scm_list_2 (elem1, elem2) | |
332 | @deffnx {C Function} scm_list_3 (elem1, elem2, elem3) | |
333 | @deffnx {C Function} scm_list_4 (elem1, elem2, elem3, elem4) | |
334 | @deffnx {C Function} scm_list_5 (elem1, elem2, elem3, elem4, elem5) | |
335 | @deffnx {C Function} scm_list_n (elem1, @dots{}, elemN, @nicode{SCM_UNDEFINED}) | |
336 | @rnindex list | |
337 | Return a new list containing elements @var{elem1} to @var{elemN}. | |
338 | ||
339 | @code{scm_list_n} takes a variable number of arguments, terminated by | |
340 | the special @code{SCM_UNDEFINED}. That final @code{SCM_UNDEFINED} is | |
341 | not included in the list. None of @var{elem1} to @var{elemN} can | |
342 | themselves be @code{SCM_UNDEFINED}, or @code{scm_list_n} will | |
343 | terminate at that point. | |
344 | @end deffn | |
345 | ||
346 | @c C Function scm_cons_star(arg1,rest) used to be documented here, | |
347 | @c but it's not really a useful interface, since it expects the | |
348 | @c caller to have already consed up all but the first argument | |
349 | @c already. | |
350 | @c | |
351 | @deffn {Scheme Procedure} cons* arg1 arg2 @dots{} | |
352 | Like @code{list}, but the last arg provides the tail of the | |
353 | constructed list, returning @code{(cons @var{arg1} (cons | |
354 | @var{arg2} (cons @dots{} @var{argn})))}. Requires at least one | |
355 | argument. If given one argument, that argument is returned as | |
356 | result. This function is called @code{list*} in some other | |
357 | Schemes and in Common LISP. | |
358 | @end deffn | |
359 | ||
360 | @deffn {Scheme Procedure} list-copy lst | |
361 | @deffnx {C Function} scm_list_copy (lst) | |
362 | Return a (newly-created) copy of @var{lst}. | |
363 | @end deffn | |
364 | ||
365 | @deffn {Scheme Procedure} make-list n [init] | |
366 | Create a list containing of @var{n} elements, where each element is | |
367 | initialized to @var{init}. @var{init} defaults to the empty list | |
368 | @code{()} if not given. | |
369 | @end deffn | |
370 | ||
371 | Note that @code{list-copy} only makes a copy of the pairs which make up | |
372 | the spine of the lists. The list elements are not copied, which means | |
373 | that modifying the elements of the new list also modifies the elements | |
374 | of the old list. On the other hand, applying procedures like | |
375 | @code{set-cdr!} or @code{delv!} to the new list will not alter the old | |
376 | list. If you also need to copy the list elements (making a deep copy), | |
377 | use the procedure @code{copy-tree} (@pxref{Copying}). | |
378 | ||
379 | @node List Selection | |
380 | @subsubsection List Selection | |
381 | ||
382 | These procedures are used to get some information about a list, or to | |
383 | retrieve one or more elements of a list. | |
384 | ||
385 | @rnindex length | |
386 | @deffn {Scheme Procedure} length lst | |
387 | @deffnx {C Function} scm_length (lst) | |
388 | Return the number of elements in list @var{lst}. | |
389 | @end deffn | |
390 | ||
391 | @deffn {Scheme Procedure} last-pair lst | |
392 | @deffnx {C Function} scm_last_pair (lst) | |
cdf1ad3b | 393 | Return the last pair in @var{lst}, signalling an error if |
07d83abe MV |
394 | @var{lst} is circular. |
395 | @end deffn | |
396 | ||
397 | @rnindex list-ref | |
398 | @deffn {Scheme Procedure} list-ref list k | |
399 | @deffnx {C Function} scm_list_ref (list, k) | |
400 | Return the @var{k}th element from @var{list}. | |
401 | @end deffn | |
402 | ||
403 | @rnindex list-tail | |
404 | @deffn {Scheme Procedure} list-tail lst k | |
405 | @deffnx {Scheme Procedure} list-cdr-ref lst k | |
406 | @deffnx {C Function} scm_list_tail (lst, k) | |
407 | Return the "tail" of @var{lst} beginning with its @var{k}th element. | |
408 | The first element of the list is considered to be element 0. | |
409 | ||
410 | @code{list-tail} and @code{list-cdr-ref} are identical. It may help to | |
411 | think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list, | |
412 | or returning the results of cdring @var{k} times down @var{lst}. | |
413 | @end deffn | |
414 | ||
415 | @deffn {Scheme Procedure} list-head lst k | |
416 | @deffnx {C Function} scm_list_head (lst, k) | |
417 | Copy the first @var{k} elements from @var{lst} into a new list, and | |
418 | return it. | |
419 | @end deffn | |
420 | ||
421 | @node Append/Reverse | |
422 | @subsubsection Append and Reverse | |
423 | ||
424 | @code{append} and @code{append!} are used to concatenate two or more | |
425 | lists in order to form a new list. @code{reverse} and @code{reverse!} | |
426 | return lists with the same elements as their arguments, but in reverse | |
427 | order. The procedure variants with an @code{!} directly modify the | |
428 | pairs which form the list, whereas the other procedures create new | |
429 | pairs. This is why you should be careful when using the side-effecting | |
430 | variants. | |
431 | ||
432 | @rnindex append | |
433 | @deffn {Scheme Procedure} append lst1 @dots{} lstN | |
434 | @deffnx {Scheme Procedure} append! lst1 @dots{} lstN | |
435 | @deffnx {C Function} scm_append (lstlst) | |
436 | @deffnx {C Function} scm_append_x (lstlst) | |
437 | Return a list comprising all the elements of lists @var{lst1} to | |
438 | @var{lstN}. | |
439 | ||
440 | @lisp | |
441 | (append '(x) '(y)) @result{} (x y) | |
442 | (append '(a) '(b c d)) @result{} (a b c d) | |
443 | (append '(a (b)) '((c))) @result{} (a (b) (c)) | |
444 | @end lisp | |
445 | ||
446 | The last argument @var{lstN} may actually be any object; an improper | |
447 | list results if the last argument is not a proper list. | |
448 | ||
449 | @lisp | |
450 | (append '(a b) '(c . d)) @result{} (a b c . d) | |
451 | (append '() 'a) @result{} a | |
452 | @end lisp | |
453 | ||
454 | @code{append} doesn't modify the given lists, but the return may share | |
455 | structure with the final @var{lstN}. @code{append!} modifies the | |
456 | given lists to form its return. | |
457 | ||
458 | For @code{scm_append} and @code{scm_append_x}, @var{lstlst} is a list | |
459 | of the list operands @var{lst1} @dots{} @var{lstN}. That @var{lstlst} | |
460 | itself is not modified or used in the return. | |
461 | @end deffn | |
462 | ||
463 | @rnindex reverse | |
464 | @deffn {Scheme Procedure} reverse lst | |
465 | @deffnx {Scheme Procedure} reverse! lst [newtail] | |
466 | @deffnx {C Function} scm_reverse (lst) | |
467 | @deffnx {C Function} scm_reverse_x (lst, newtail) | |
468 | Return a list comprising the elements of @var{lst}, in reverse order. | |
469 | ||
470 | @code{reverse} constructs a new list, @code{reverse!} modifies | |
471 | @var{lst} in constructing its return. | |
472 | ||
473 | For @code{reverse!}, the optional @var{newtail} is appended to to the | |
474 | result. @var{newtail} isn't reversed, it simply becomes the list | |
475 | tail. For @code{scm_reverse_x}, the @var{newtail} parameter is | |
476 | mandatory, but can be @code{SCM_EOL} if no further tail is required. | |
477 | @end deffn | |
478 | ||
479 | @node List Modification | |
480 | @subsubsection List Modification | |
481 | ||
482 | The following procedures modify an existing list, either by changing | |
483 | elements of the list, or by changing the list structure itself. | |
484 | ||
485 | @deffn {Scheme Procedure} list-set! list k val | |
486 | @deffnx {C Function} scm_list_set_x (list, k, val) | |
487 | Set the @var{k}th element of @var{list} to @var{val}. | |
488 | @end deffn | |
489 | ||
490 | @deffn {Scheme Procedure} list-cdr-set! list k val | |
491 | @deffnx {C Function} scm_list_cdr_set_x (list, k, val) | |
492 | Set the @var{k}th cdr of @var{list} to @var{val}. | |
493 | @end deffn | |
494 | ||
495 | @deffn {Scheme Procedure} delq item lst | |
496 | @deffnx {C Function} scm_delq (item, lst) | |
497 | Return a newly-created copy of @var{lst} with elements | |
498 | @code{eq?} to @var{item} removed. This procedure mirrors | |
499 | @code{memq}: @code{delq} compares elements of @var{lst} against | |
500 | @var{item} with @code{eq?}. | |
501 | @end deffn | |
502 | ||
503 | @deffn {Scheme Procedure} delv item lst | |
504 | @deffnx {C Function} scm_delv (item, lst) | |
505 | Return a newly-created copy of @var{lst} with elements | |
23f2b9a3 | 506 | @code{eqv?} to @var{item} removed. This procedure mirrors |
07d83abe MV |
507 | @code{memv}: @code{delv} compares elements of @var{lst} against |
508 | @var{item} with @code{eqv?}. | |
509 | @end deffn | |
510 | ||
511 | @deffn {Scheme Procedure} delete item lst | |
512 | @deffnx {C Function} scm_delete (item, lst) | |
513 | Return a newly-created copy of @var{lst} with elements | |
23f2b9a3 | 514 | @code{equal?} to @var{item} removed. This procedure mirrors |
07d83abe MV |
515 | @code{member}: @code{delete} compares elements of @var{lst} |
516 | against @var{item} with @code{equal?}. | |
23f2b9a3 KR |
517 | |
518 | See also SRFI-1 which has an extended @code{delete} (@ref{SRFI-1 | |
519 | Deleting}), and also an @code{lset-difference} which can delete | |
520 | multiple @var{item}s in one call (@ref{SRFI-1 Set Operations}). | |
07d83abe MV |
521 | @end deffn |
522 | ||
523 | @deffn {Scheme Procedure} delq! item lst | |
524 | @deffnx {Scheme Procedure} delv! item lst | |
525 | @deffnx {Scheme Procedure} delete! item lst | |
526 | @deffnx {C Function} scm_delq_x (item, lst) | |
527 | @deffnx {C Function} scm_delv_x (item, lst) | |
528 | @deffnx {C Function} scm_delete_x (item, lst) | |
529 | These procedures are destructive versions of @code{delq}, @code{delv} | |
530 | and @code{delete}: they modify the pointers in the existing @var{lst} | |
531 | rather than creating a new list. Caveat evaluator: Like other | |
532 | destructive list functions, these functions cannot modify the binding of | |
533 | @var{lst}, and so cannot be used to delete the first element of | |
534 | @var{lst} destructively. | |
535 | @end deffn | |
536 | ||
537 | @deffn {Scheme Procedure} delq1! item lst | |
538 | @deffnx {C Function} scm_delq1_x (item, lst) | |
539 | Like @code{delq!}, but only deletes the first occurrence of | |
540 | @var{item} from @var{lst}. Tests for equality using | |
541 | @code{eq?}. See also @code{delv1!} and @code{delete1!}. | |
542 | @end deffn | |
543 | ||
544 | @deffn {Scheme Procedure} delv1! item lst | |
545 | @deffnx {C Function} scm_delv1_x (item, lst) | |
546 | Like @code{delv!}, but only deletes the first occurrence of | |
547 | @var{item} from @var{lst}. Tests for equality using | |
548 | @code{eqv?}. See also @code{delq1!} and @code{delete1!}. | |
549 | @end deffn | |
550 | ||
551 | @deffn {Scheme Procedure} delete1! item lst | |
552 | @deffnx {C Function} scm_delete1_x (item, lst) | |
553 | Like @code{delete!}, but only deletes the first occurrence of | |
554 | @var{item} from @var{lst}. Tests for equality using | |
555 | @code{equal?}. See also @code{delq1!} and @code{delv1!}. | |
556 | @end deffn | |
557 | ||
558 | @deffn {Scheme Procedure} filter pred lst | |
559 | @deffnx {Scheme Procedure} filter! pred lst | |
560 | Return a list containing all elements from @var{lst} which satisfy the | |
561 | predicate @var{pred}. The elements in the result list have the same | |
562 | order as in @var{lst}. The order in which @var{pred} is applied to | |
563 | the list elements is not specified. | |
564 | ||
d8e49e6b KR |
565 | @code{filter} does not change @var{lst}, but the result may share a |
566 | tail with it. @code{filter!} may modify @var{lst} to construct its | |
567 | return. | |
07d83abe MV |
568 | @end deffn |
569 | ||
570 | @node List Searching | |
571 | @subsubsection List Searching | |
572 | ||
573 | The following procedures search lists for particular elements. They use | |
574 | different comparison predicates for comparing list elements with the | |
575 | object to be searched. When they fail, they return @code{#f}, otherwise | |
576 | they return the sublist whose car is equal to the search object, where | |
577 | equality depends on the equality predicate used. | |
578 | ||
579 | @rnindex memq | |
580 | @deffn {Scheme Procedure} memq x lst | |
581 | @deffnx {C Function} scm_memq (x, lst) | |
582 | Return the first sublist of @var{lst} whose car is @code{eq?} | |
583 | to @var{x} where the sublists of @var{lst} are the non-empty | |
584 | lists returned by @code{(list-tail @var{lst} @var{k})} for | |
585 | @var{k} less than the length of @var{lst}. If @var{x} does not | |
586 | occur in @var{lst}, then @code{#f} (not the empty list) is | |
587 | returned. | |
588 | @end deffn | |
589 | ||
590 | @rnindex memv | |
591 | @deffn {Scheme Procedure} memv x lst | |
592 | @deffnx {C Function} scm_memv (x, lst) | |
593 | Return the first sublist of @var{lst} whose car is @code{eqv?} | |
594 | to @var{x} where the sublists of @var{lst} are the non-empty | |
595 | lists returned by @code{(list-tail @var{lst} @var{k})} for | |
596 | @var{k} less than the length of @var{lst}. If @var{x} does not | |
597 | occur in @var{lst}, then @code{#f} (not the empty list) is | |
598 | returned. | |
599 | @end deffn | |
600 | ||
601 | @rnindex member | |
602 | @deffn {Scheme Procedure} member x lst | |
603 | @deffnx {C Function} scm_member (x, lst) | |
604 | Return the first sublist of @var{lst} whose car is | |
605 | @code{equal?} to @var{x} where the sublists of @var{lst} are | |
606 | the non-empty lists returned by @code{(list-tail @var{lst} | |
607 | @var{k})} for @var{k} less than the length of @var{lst}. If | |
608 | @var{x} does not occur in @var{lst}, then @code{#f} (not the | |
609 | empty list) is returned. | |
23f2b9a3 KR |
610 | |
611 | See also SRFI-1 which has an extended @code{member} function | |
612 | (@ref{SRFI-1 Searching}). | |
07d83abe MV |
613 | @end deffn |
614 | ||
615 | ||
616 | @node List Mapping | |
617 | @subsubsection List Mapping | |
618 | ||
619 | List processing is very convenient in Scheme because the process of | |
620 | iterating over the elements of a list can be highly abstracted. The | |
621 | procedures in this section are the most basic iterating procedures for | |
622 | lists. They take a procedure and one or more lists as arguments, and | |
623 | apply the procedure to each element of the list. They differ in their | |
624 | return value. | |
625 | ||
626 | @rnindex map | |
627 | @c begin (texi-doc-string "guile" "map") | |
628 | @deffn {Scheme Procedure} map proc arg1 arg2 @dots{} | |
629 | @deffnx {Scheme Procedure} map-in-order proc arg1 arg2 @dots{} | |
630 | @deffnx {C Function} scm_map (proc, arg1, args) | |
631 | Apply @var{proc} to each element of the list @var{arg1} (if only two | |
632 | arguments are given), or to the corresponding elements of the argument | |
633 | lists (if more than two arguments are given). The result(s) of the | |
634 | procedure applications are saved and returned in a list. For | |
635 | @code{map}, the order of procedure applications is not specified, | |
636 | @code{map-in-order} applies the procedure from left to right to the list | |
637 | elements. | |
638 | @end deffn | |
639 | ||
640 | @rnindex for-each | |
641 | @c begin (texi-doc-string "guile" "for-each") | |
642 | @deffn {Scheme Procedure} for-each proc arg1 arg2 @dots{} | |
643 | Like @code{map}, but the procedure is always applied from left to right, | |
644 | and the result(s) of the procedure applications are thrown away. The | |
645 | return value is not specified. | |
646 | @end deffn | |
647 | ||
23f2b9a3 KR |
648 | See also SRFI-1 which extends these functions to take lists of unequal |
649 | lengths (@ref{SRFI-1 Fold and Map}). | |
07d83abe MV |
650 | |
651 | @node Vectors | |
652 | @subsection Vectors | |
653 | @tpindex Vectors | |
654 | ||
655 | Vectors are sequences of Scheme objects. Unlike lists, the length of a | |
656 | vector, once the vector is created, cannot be changed. The advantage of | |
657 | vectors over lists is that the time required to access one element of a vector | |
658 | given its @dfn{position} (synonymous with @dfn{index}), a zero-origin number, | |
659 | is constant, whereas lists have an access time linear to the position of the | |
660 | accessed element in the list. | |
661 | ||
e6b226b9 MV |
662 | Vectors can contain any kind of Scheme object; it is even possible to |
663 | have different types of objects in the same vector. For vectors | |
664 | containing vectors, you may wish to use arrays, instead. Note, too, | |
52d28fc2 MV |
665 | that vectors are the special case of one dimensional non-uniform arrays |
666 | and that most array procedures operate happily on vectors | |
01e6d0ec MV |
667 | (@pxref{Arrays}). |
668 | ||
07d83abe MV |
669 | @menu |
670 | * Vector Syntax:: Read syntax for vectors. | |
671 | * Vector Creation:: Dynamic vector creation and validation. | |
672 | * Vector Accessors:: Accessing and modifying vector contents. | |
52d28fc2 | 673 | * Vector Accessing from C:: Ways to work with vectors from C. |
07d83abe MV |
674 | @end menu |
675 | ||
676 | ||
677 | @node Vector Syntax | |
678 | @subsubsection Read Syntax for Vectors | |
679 | ||
680 | Vectors can literally be entered in source code, just like strings, | |
681 | characters or some of the other data types. The read syntax for vectors | |
682 | is as follows: A sharp sign (@code{#}), followed by an opening | |
683 | parentheses, all elements of the vector in their respective read syntax, | |
684 | and finally a closing parentheses. The following are examples of the | |
685 | read syntax for vectors; where the first vector only contains numbers | |
686 | and the second three different object types: a string, a symbol and a | |
687 | number in hexadecimal notation. | |
688 | ||
689 | @lisp | |
690 | #(1 2 3) | |
691 | #("Hello" foo #xdeadbeef) | |
692 | @end lisp | |
693 | ||
52d28fc2 | 694 | Like lists, vectors have to be quoted: |
07d83abe MV |
695 | |
696 | @lisp | |
697 | '#(a b c) @result{} #(a b c) | |
698 | @end lisp | |
699 | ||
700 | @node Vector Creation | |
701 | @subsubsection Dynamic Vector Creation and Validation | |
702 | ||
703 | Instead of creating a vector implicitly by using the read syntax just | |
704 | described, you can create a vector dynamically by calling one of the | |
705 | @code{vector} and @code{list->vector} primitives with the list of Scheme | |
706 | values that you want to place into a vector. The size of the vector | |
707 | thus created is determined implicitly by the number of arguments given. | |
708 | ||
709 | @rnindex vector | |
710 | @rnindex list->vector | |
711 | @deffn {Scheme Procedure} vector . l | |
712 | @deffnx {Scheme Procedure} list->vector l | |
713 | @deffnx {C Function} scm_vector (l) | |
714 | Return a newly allocated vector composed of the | |
715 | given arguments. Analogous to @code{list}. | |
716 | ||
717 | @lisp | |
718 | (vector 'a 'b 'c) @result{} #(a b c) | |
719 | @end lisp | |
720 | @end deffn | |
721 | ||
07d83abe MV |
722 | The inverse operation is @code{vector->list}: |
723 | ||
724 | @rnindex vector->list | |
725 | @deffn {Scheme Procedure} vector->list v | |
726 | @deffnx {C Function} scm_vector_to_list (v) | |
727 | Return a newly allocated list composed of the elements of @var{v}. | |
728 | ||
729 | @lisp | |
730 | (vector->list '#(dah dah didah)) @result{} (dah dah didah) | |
731 | (list->vector '(dididit dah)) @result{} #(dididit dah) | |
732 | @end lisp | |
733 | @end deffn | |
734 | ||
735 | To allocate a vector with an explicitly specified size, use | |
736 | @code{make-vector}. With this primitive you can also specify an initial | |
737 | value for the vector elements (the same value for all elements, that | |
738 | is): | |
739 | ||
740 | @rnindex make-vector | |
61eed960 MV |
741 | @deffn {Scheme Procedure} make-vector len [fill] |
742 | @deffnx {C Function} scm_make_vector (len, fill) | |
743 | Return a newly allocated vector of @var{len} elements. If a | |
07d83abe MV |
744 | second argument is given, then each position is initialized to |
745 | @var{fill}. Otherwise the initial contents of each position is | |
746 | unspecified. | |
747 | @end deffn | |
748 | ||
61eed960 MV |
749 | @deftypefn {C Function} SCM scm_c_make_vector (size_t k, SCM fill) |
750 | Like @code{scm_make_vector}, but the length is given as a @code{size_t}. | |
751 | @end deftypefn | |
752 | ||
07d83abe MV |
753 | To check whether an arbitrary Scheme value @emph{is} a vector, use the |
754 | @code{vector?} primitive: | |
755 | ||
756 | @rnindex vector? | |
757 | @deffn {Scheme Procedure} vector? obj | |
758 | @deffnx {C Function} scm_vector_p (obj) | |
759 | Return @code{#t} if @var{obj} is a vector, otherwise return | |
760 | @code{#f}. | |
761 | @end deffn | |
762 | ||
61eed960 MV |
763 | @deftypefn {C Function} int scm_is_vector (SCM obj) |
764 | Return non-zero when @var{obj} is a vector, otherwise return | |
765 | @code{zero}. | |
766 | @end deftypefn | |
07d83abe MV |
767 | |
768 | @node Vector Accessors | |
769 | @subsubsection Accessing and Modifying Vector Contents | |
770 | ||
771 | @code{vector-length} and @code{vector-ref} return information about a | |
772 | given vector, respectively its size and the elements that are contained | |
773 | in the vector. | |
774 | ||
775 | @rnindex vector-length | |
776 | @deffn {Scheme Procedure} vector-length vector | |
777 | @deffnx {C Function} scm_vector_length vector | |
778 | Return the number of elements in @var{vector} as an exact integer. | |
779 | @end deffn | |
780 | ||
61eed960 MV |
781 | @deftypefn {C Function} size_t scm_c_vector_length (SCM v) |
782 | Return the number of elements in @var{vector} as a @code{size_t}. | |
783 | @end deftypefn | |
784 | ||
07d83abe MV |
785 | @rnindex vector-ref |
786 | @deffn {Scheme Procedure} vector-ref vector k | |
787 | @deffnx {C Function} scm_vector_ref vector k | |
788 | Return the contents of position @var{k} of @var{vector}. | |
789 | @var{k} must be a valid index of @var{vector}. | |
790 | @lisp | |
791 | (vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8 | |
792 | (vector-ref '#(1 1 2 3 5 8 13 21) | |
793 | (let ((i (round (* 2 (acos -1))))) | |
794 | (if (inexact? i) | |
795 | (inexact->exact i) | |
796 | i))) @result{} 13 | |
797 | @end lisp | |
798 | @end deffn | |
799 | ||
61eed960 | 800 | @deftypefn {C Function} SCM scm_c_vector_ref (SCM v, size_t k) |
52d28fc2 | 801 | Return the contents of position @var{k} (a @code{size_t}) of |
61eed960 MV |
802 | @var{vector}. |
803 | @end deftypefn | |
804 | ||
07d83abe MV |
805 | A vector created by one of the dynamic vector constructor procedures |
806 | (@pxref{Vector Creation}) can be modified using the following | |
807 | procedures. | |
808 | ||
809 | @emph{NOTE:} According to R5RS, it is an error to use any of these | |
810 | procedures on a literally read vector, because such vectors should be | |
811 | considered as constants. Currently, however, Guile does not detect this | |
812 | error. | |
813 | ||
814 | @rnindex vector-set! | |
815 | @deffn {Scheme Procedure} vector-set! vector k obj | |
816 | @deffnx {C Function} scm_vector_set_x vector k obj | |
817 | Store @var{obj} in position @var{k} of @var{vector}. | |
818 | @var{k} must be a valid index of @var{vector}. | |
819 | The value returned by @samp{vector-set!} is unspecified. | |
820 | @lisp | |
821 | (let ((vec (vector 0 '(2 2 2 2) "Anna"))) | |
822 | (vector-set! vec 1 '("Sue" "Sue")) | |
823 | vec) @result{} #(0 ("Sue" "Sue") "Anna") | |
824 | @end lisp | |
825 | @end deffn | |
826 | ||
de26705f | 827 | @deftypefn {C Function} void scm_c_vector_set_x (SCM v, size_t k, SCM obj) |
61eed960 MV |
828 | Store @var{obj} in position @var{k} (a @code{size_t}) of @var{v}. |
829 | @end deftypefn | |
830 | ||
07d83abe MV |
831 | @rnindex vector-fill! |
832 | @deffn {Scheme Procedure} vector-fill! v fill | |
833 | @deffnx {C Function} scm_vector_fill_x (v, fill) | |
834 | Store @var{fill} in every position of @var{vector}. The value | |
835 | returned by @code{vector-fill!} is unspecified. | |
836 | @end deffn | |
837 | ||
673ba2da MV |
838 | @deffn {Scheme Procedure} vector-copy vec |
839 | @deffnx {C Function} scm_vector_copy (vec) | |
840 | Return a copy of @var{vec}. | |
841 | @end deffn | |
842 | ||
07d83abe MV |
843 | @deffn {Scheme Procedure} vector-move-left! vec1 start1 end1 vec2 start2 |
844 | @deffnx {C Function} scm_vector_move_left_x (vec1, start1, end1, vec2, start2) | |
845 | Copy elements from @var{vec1}, positions @var{start1} to @var{end1}, | |
846 | to @var{vec2} starting at position @var{start2}. @var{start1} and | |
847 | @var{start2} are inclusive indices; @var{end1} is exclusive. | |
848 | ||
849 | @code{vector-move-left!} copies elements in leftmost order. | |
850 | Therefore, in the case where @var{vec1} and @var{vec2} refer to the | |
851 | same vector, @code{vector-move-left!} is usually appropriate when | |
852 | @var{start1} is greater than @var{start2}. | |
853 | @end deffn | |
854 | ||
855 | @deffn {Scheme Procedure} vector-move-right! vec1 start1 end1 vec2 start2 | |
856 | @deffnx {C Function} scm_vector_move_right_x (vec1, start1, end1, vec2, start2) | |
857 | Copy elements from @var{vec1}, positions @var{start1} to @var{end1}, | |
858 | to @var{vec2} starting at position @var{start2}. @var{start1} and | |
859 | @var{start2} are inclusive indices; @var{end1} is exclusive. | |
860 | ||
861 | @code{vector-move-right!} copies elements in rightmost order. | |
862 | Therefore, in the case where @var{vec1} and @var{vec2} refer to the | |
863 | same vector, @code{vector-move-right!} is usually appropriate when | |
864 | @var{start1} is less than @var{start2}. | |
865 | @end deffn | |
866 | ||
52d28fc2 MV |
867 | @node Vector Accessing from C |
868 | @subsubsection Vector Accessing from C | |
01e6d0ec | 869 | |
52d28fc2 MV |
870 | A vector can be read and modified from C with the functions |
871 | @code{scm_c_vector_ref} and @code{scm_c_vector_set_x}, for example. In | |
872 | addition to these functions, there are two more ways to access vectors | |
873 | from C that might be more efficient in certain situations: you can | |
874 | restrict yourself to @dfn{simple vectors} and then use the very fast | |
875 | @emph{simple vector macros}; or you can use the very general framework | |
876 | for accessing all kinds of arrays (@pxref{Accessing Arrays from C}), | |
877 | which is more verbose, but can deal efficiently with all kinds of | |
86ccc354 MV |
878 | vectors (and arrays). For vectors, you can use the |
879 | @code{scm_vector_elements} and @code{scm_vector_writable_elements} | |
880 | functions as shortcuts. | |
52d28fc2 MV |
881 | |
882 | @deftypefn {C Function} int scm_is_simple_vector (SCM obj) | |
883 | Return non-zero if @var{obj} is a simple vector, else return zero. A | |
884 | simple vector is a vector that can be used with the @code{SCM_SIMPLE_*} | |
885 | macros below. | |
01e6d0ec | 886 | |
52d28fc2 MV |
887 | The following functions are guaranteed to return simple vectors: |
888 | @code{scm_make_vector}, @code{scm_c_make_vector}, @code{scm_vector}, | |
889 | @code{scm_list_to_vector}. | |
01e6d0ec MV |
890 | @end deftypefn |
891 | ||
52d28fc2 MV |
892 | @deftypefn {C Macro} size_t SCM_SIMPLE_VECTOR_LENGTH (SCM vec) |
893 | Evaluates to the length of the simple vector @var{vec}. No type | |
894 | checking is done. | |
01e6d0ec MV |
895 | @end deftypefn |
896 | ||
52d28fc2 MV |
897 | @deftypefn {C Macro} SCM SCM_SIMPLE_VECTOR_REF (SCM vec, size_t idx) |
898 | Evaluates to the element at position @var{idx} in the simple vector | |
899 | @var{vec}. No type or range checking is done. | |
900 | @end deftypefn | |
01e6d0ec | 901 | |
1b09b607 | 902 | @deftypefn {C Macro} void SCM_SIMPLE_VECTOR_SET (SCM vec, size_t idx, SCM val) |
52d28fc2 MV |
903 | Sets the element at position @var{idx} in the simple vector |
904 | @var{vec} to @var{val}. No type or range checking is done. | |
01e6d0ec MV |
905 | @end deftypefn |
906 | ||
d1f9e107 | 907 | @deftypefn {C Function} {const SCM *} scm_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp) |
52d28fc2 MV |
908 |