Commit | Line | Data |
---|---|---|
38a93523 NJ |
1 | @page |
2 | @node Utility Functions | |
3 | @chapter General Utility Functions | |
4 | ||
239d2912 MG |
5 | @c FIXME::martin: Review me! |
6 | ||
7 | This chapter contains information about procedures which are not cleanly | |
8 | tied to a specific data type. Because of their wide range of | |
9 | applications, they are collected in a @dfn{utlity} chapter. | |
10 | ||
38a93523 NJ |
11 | @menu |
12 | * Equality:: When are two values `the same'? | |
13 | * Property Lists:: Managing metainformation about Scheme objects. | |
14 | * Primitive Properties:: A modern low-level interface to object properties. | |
15 | * Sorting:: Sort utility procedures. | |
16 | * Copying:: Copying deep structures. | |
239d2912 | 17 | * General Conversion:: Converting objects to strings. |
38a93523 NJ |
18 | @end menu |
19 | ||
20 | ||
21 | @node Equality | |
22 | @section Equality | |
23 | ||
239d2912 MG |
24 | @c FIXME::martin: Review me! |
25 | ||
26 | @cindex sameness | |
27 | @cindex equality | |
28 | ||
29 | Three different kinds of @dfn{sameness} are defined in Scheme. | |
30 | ||
31 | @itemize @bullet | |
32 | @item | |
33 | Two values can refer to exactly the same object. | |
34 | ||
35 | @item | |
36 | Two objects can have the same @dfn{value}. | |
37 | ||
38 | @item | |
39 | Two objects can be structurally equivalent. | |
40 | @end itemize | |
41 | ||
42 | The differentiation between these three kinds is important, because | |
43 | determining whether two values are the same objects is very efficient, | |
44 | while determining structural equivalence can be quite expensive | |
45 | (consider comparing two very long lists). Therefore, three different | |
46 | procedures for testing for equality are provided, which correspond to | |
47 | the three kinds of @dfn{sameness} defined above. | |
48 | ||
5c4b24e1 | 49 | @rnindex eq? |
38a93523 NJ |
50 | @deffn primitive eq? x y |
51 | Return @code{#t} iff @var{x} references the same object as @var{y}. | |
52 | @code{eq?} is similar to @code{eqv?} except that in some cases it is | |
53 | capable of discerning distinctions finer than those detectable by | |
54 | @code{eqv?}. | |
55 | @end deffn | |
56 | ||
5c4b24e1 | 57 | @rnindex eqv? |
38a93523 NJ |
58 | @deffn primitive eqv? x y |
59 | The @code{eqv?} procedure defines a useful equivalence relation on objects. | |
60 | Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be | |
61 | regarded as the same object. This relation is left slightly open to | |
62 | interpretation, but works for comparing immediate integers, characters, | |
63 | and inexact numbers. | |
64 | @end deffn | |
65 | ||
5c4b24e1 | 66 | @rnindex equal? |
38a93523 NJ |
67 | @deffn primitive equal? x y |
68 | Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent. | |
69 | @code{equal?} recursively compares the contents of pairs, | |
70 | vectors, and strings, applying @code{eqv?} on other objects such as | |
71 | numbers and symbols. A rule of thumb is that objects are generally | |
72 | @code{equal?} if they print the same. @code{equal?} may fail to | |
73 | terminate if its arguments are circular data structures. | |
74 | @end deffn | |
75 | ||
76 | ||
77 | @node Property Lists | |
78 | @section Property Lists | |
79 | ||
80 | Every object in the system can have a @dfn{property list} that may | |
81 | be used for information about that object. For example, a | |
82 | function may have a property list that includes information about | |
83 | the source file in which it is defined. | |
84 | ||
85 | Property lists are implemented as assq lists (@pxref{Association Lists}). | |
86 | ||
87 | Currently, property lists are implemented differently for procedures and | |
88 | closures than for other kinds of objects. Therefore, when manipulating | |
89 | a property list associated with a procedure object, use the | |
90 | @code{procedure} functions; otherwise, use the @code{object} functions. | |
91 | ||
38a93523 NJ |
92 | @deffn primitive object-properties obj |
93 | @deffnx primitive procedure-properties obj | |
94 | Return @var{obj}'s property list. | |
95 | @end deffn | |
96 | ||
ae9f3a15 | 97 | @deffn primitive set-object-properties! obj alist |
38a93523 NJ |
98 | @deffnx primitive set-procedure-properties! obj alist |
99 | Set @var{obj}'s property list to @var{alist}. | |
100 | @end deffn | |
101 | ||
38a93523 NJ |
102 | @deffn primitive object-property obj key |
103 | @deffnx primitive procedure-property obj key | |
104 | Return the property of @var{obj} with name @var{key}. | |
105 | @end deffn | |
106 | ||
ae9f3a15 | 107 | @deffn primitive set-object-property! obj key value |
38a93523 | 108 | @deffnx primitive set-procedure-property! obj key value |
ae9f3a15 MG |
109 | In @var{obj}'s property list, set the property named @var{key} |
110 | to @var{value}. | |
38a93523 NJ |
111 | @end deffn |
112 | ||
113 | [Interface bug: there should be a second level of interface in which | |
114 | the user provides a "property table" that is possibly private.] | |
115 | ||
116 | ||
117 | @node Primitive Properties | |
118 | @section Primitive Properties | |
119 | ||
38a93523 NJ |
120 | @deffn primitive primitive-make-property not_found_proc |
121 | Create a @dfn{property token} that can be used with | |
122 | @code{primitive-property-ref} and @code{primitive-property-set!}. | |
123 | See @code{primitive-property-ref} for the significance of | |
124 | @var{not_found_proc}. | |
125 | @end deffn | |
126 | ||
38a93523 NJ |
127 | @deffn primitive primitive-property-ref prop obj |
128 | Return the property @var{prop} of @var{obj}. When no value | |
129 | has yet been associated with @var{prop} and @var{obj}, call | |
130 | @var{not-found-proc} instead (see @code{primitive-make-property}) | |
131 | and use its return value. That value is also associated with | |
132 | @var{obj} via @code{primitive-property-set!}. When | |
133 | @var{not-found-proc} is @code{#f}, use @code{#f} as the | |
134 | default value of @var{prop}. | |
135 | @end deffn | |
136 | ||
38a93523 NJ |
137 | @deffn primitive primitive-property-set! prop obj val |
138 | Associate @var{code} with @var{prop} and @var{obj}. | |
139 | @end deffn | |
140 | ||
38a93523 NJ |
141 | @deffn primitive primitive-property-del! prop obj |
142 | Remove any value associated with @var{prop} and @var{obj}. | |
143 | @end deffn | |
144 | ||
145 | ||
146 | @node Sorting | |
147 | @section Sorting | |
148 | ||
239d2912 MG |
149 | @c FIXME::martin: Review me! |
150 | ||
151 | @cindex sorting | |
152 | @cindex sorting lists | |
153 | @cindex sorting vectors | |
154 | ||
155 | Sorting is very important in computer programs. Therefore, Guile comes | |
156 | with several sorting procedures built--in. As always, procedures with | |
157 | names ending in @code{!} are side--effecting, that means that they may | |
158 | modify their parameters in order to produce their results. | |
159 | ||
160 | The first group of procedures can be used to merge two lists (which must | |
161 | be already sorted on their own) and produce sorted lists containing | |
162 | all elements of the input lists. | |
163 | ||
164 | @deffn primitive merge alist blist less | |
165 | Take two lists @var{alist} and @var{blist} such that | |
166 | @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and | |
167 | returns a new list in which the elements of @var{alist} and | |
168 | @var{blist} have been stably interleaved so that | |
169 | @code{(sorted? (merge alist blist less?) less?)}. | |
170 | @end deffn | |
171 | ||
38a93523 NJ |
172 | @deffn primitive merge! alist blist less |
173 | Takes two lists @var{alist} and @var{blist} such that | |
174 | @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and | |
175 | returns a new list in which the elements of @var{alist} and | |
176 | @var{blist} have been stably interleaved so that | |
177 | @code{(sorted? (merge alist blist less?) less?)}. | |
178 | This is the destructive variant of @code{merge} | |
179 | Note: this does _not_ accept vectors. | |
180 | @end deffn | |
181 | ||
239d2912 MG |
182 | The following procedures can operate on sequences which are either |
183 | vectors or list. According to the given arguments, they return sorted | |
184 | vectors or lists, respectively. The first of the following procedures | |
185 | determines whether a sequence is already sorted, the other sort a given | |
186 | sequence. The variants with names starting with @code{stable-} are | |
187 | special in that they maintain a special property of the input sequences: | |
188 | If two or more elements are the same according to the comparison | |
189 | predicate, they are left in the same order as they appeared in the | |
190 | input. | |
191 | ||
192 | @deffn primitive sorted? items less | |
193 | Return @code{#t} iff @var{items} is a list or a vector such that | |
194 | for all 1 <= i <= m, the predicate @var{less} returns true when | |
195 | applied to all elements i - 1 and i | |
38a93523 NJ |
196 | @end deffn |
197 | ||
239d2912 MG |
198 | @deffn primitive sort items less |
199 | Sort the sequence @var{items}, which may be a list or a | |
200 | vector. @var{less} is used for comparing the sequence | |
201 | elements. This is not a stable sort. | |
38a93523 NJ |
202 | @end deffn |
203 | ||
38a93523 NJ |
204 | @deffn primitive sort! items less |
205 | Sort the sequence @var{items}, which may be a list or a | |
206 | vector. @var{less} is used for comparing the sequence | |
207 | elements. The sorting is destructive, that means that the | |
208 | input sequence is modified to produce the sorted result. | |
209 | This is not a stable sort. | |
210 | @end deffn | |
211 | ||
239d2912 | 212 | @deffn primitive stable-sort items less |
38a93523 | 213 | Sort the sequence @var{items}, which may be a list or a |
239d2912 MG |
214 | vector. @var{less} is used for comparing the sequence elements. |
215 | This is a stable sort. | |
38a93523 NJ |
216 | @end deffn |
217 | ||
239d2912 MG |
218 | @deffn primitive stable-sort! items less |
219 | Sort the sequence @var{items}, which may be a list or a | |
220 | vector. @var{less} is used for comparing the sequence elements. | |
221 | The sorting is destructive, that means that the input sequence | |
222 | is modified to produce the sorted result. | |
38a93523 NJ |
223 | This is a stable sort. |
224 | @end deffn | |
225 | ||
239d2912 MG |
226 | The procedures in the last group only accept lists or vectors as input, |
227 | as their names indicate. | |
228 | ||
38a93523 NJ |
229 | @deffn primitive sort-list items less |
230 | Sort the list @var{items}, using @var{less} for comparing the | |
231 | list elements. This is a stable sort. | |
232 | @end deffn | |
233 | ||
239d2912 MG |
234 | @deffn primitive sort-list! items less |
235 | Sort the list @var{items}, using @var{less} for comparing the | |
236 | list elements. The sorting is destructive, that means that the | |
237 | input list is modified to produce the sorted result. | |
38a93523 NJ |
238 | This is a stable sort. |
239 | @end deffn | |
240 | ||
239d2912 MG |
241 | @deffn primitive restricted-vector-sort! vec less startpos endpos |
242 | Sort the vector @var{vec}, using @var{less} for comparing | |
243 | the vector elements. @var{startpos} and @var{endpos} delimit | |
244 | the range of the vector which gets sorted. The return value | |
245 | is not specified. | |
38a93523 NJ |
246 | @end deffn |
247 | ||
248 | ||
249 | @node Copying | |
250 | @section Copying Deep Structures | |
251 | ||
239d2912 MG |
252 | @c FIXME::martin: Review me! |
253 | ||
254 | The procedures for copying lists (@pxref{Lists}) only produce a flat | |
255 | copy of the input list, and currently Guile does not even contain | |
256 | procedures for copying vectors. @code{copy-tree} can be used for these | |
257 | application, as it does not only copy the spine of a list, but also | |
258 | copies any pairs in the cars of the input lists. | |
259 | ||
38a93523 NJ |
260 | @deffn primitive copy-tree obj |
261 | Recursively copy the data tree that is bound to @var{obj}, and return a | |
262 | pointer to the new data structure. @code{copy-tree} recurses down the | |
263 | contents of both pairs and vectors (since both cons cells and vector | |
264 | cells may point to arbitrary objects), and stops recursing when it hits | |
265 | any other object. | |
266 | @end deffn | |
267 | ||
268 | ||
239d2912 MG |
269 | @node General Conversion |
270 | @section General String Conversion | |
271 | ||
272 | @c FIXME::martin: Review me! | |
273 | ||
274 | When debugging Scheme programs, but also for providing a human--friendly | |
275 | interface, a procedure for converting any Scheme object into string | |
276 | format is very useful. Conversion from/to strings can of course be done | |
277 | with specialized procedures when the data type of the object to convert | |
278 | is known, but with this procedure, it is often more comfortable. | |
279 | ||
280 | @code{object->string} converts an object by using a print procedure for | |
281 | writing to a string port, and then returning the resulting string. | |
282 | Converting an object back from the string is only possible if the object | |
283 | type has a read syntax and the read syntax is preserved by the printing | |
284 | procedure. | |
285 | ||
286 | @deffn primitive object->string obj [printer] | |
287 | Return a Scheme string obtained by printing @var{obj}. | |
288 | Printing function can be specified by the optional second | |
289 | argument @var{printer} (default: @code{write}). | |
290 | @end deffn | |
291 | ||
292 | ||
38a93523 NJ |
293 | @c Local Variables: |
294 | @c TeX-master: "guile.texi" | |
295 | @c End: |