Commit | Line | Data |
---|---|---|
38a93523 NJ |
1 | @page |
2 | @node Utility Functions | |
3 | @chapter General Utility Functions | |
4 | ||
5 | @menu | |
6 | * Equality:: When are two values `the same'? | |
7 | * Property Lists:: Managing metainformation about Scheme objects. | |
8 | * Primitive Properties:: A modern low-level interface to object properties. | |
9 | * Sorting:: Sort utility procedures. | |
10 | * Copying:: Copying deep structures. | |
11 | @end menu | |
12 | ||
13 | ||
14 | @node Equality | |
15 | @section Equality | |
16 | ||
5c4b24e1 | 17 | @rnindex eq? |
38a93523 NJ |
18 | @c docstring begin (texi-doc-string "guile" "eq?") |
19 | @deffn primitive eq? x y | |
20 | Return @code{#t} iff @var{x} references the same object as @var{y}. | |
21 | @code{eq?} is similar to @code{eqv?} except that in some cases it is | |
22 | capable of discerning distinctions finer than those detectable by | |
23 | @code{eqv?}. | |
24 | @end deffn | |
25 | ||
5c4b24e1 | 26 | @rnindex eqv? |
38a93523 NJ |
27 | @c docstring begin (texi-doc-string "guile" "eqv?") |
28 | @deffn primitive eqv? x y | |
29 | The @code{eqv?} procedure defines a useful equivalence relation on objects. | |
30 | Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be | |
31 | regarded as the same object. This relation is left slightly open to | |
32 | interpretation, but works for comparing immediate integers, characters, | |
33 | and inexact numbers. | |
34 | @end deffn | |
35 | ||
5c4b24e1 | 36 | @rnindex equal? |
38a93523 NJ |
37 | @c docstring begin (texi-doc-string "guile" "equal?") |
38 | @deffn primitive equal? x y | |
39 | Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent. | |
40 | @code{equal?} recursively compares the contents of pairs, | |
41 | vectors, and strings, applying @code{eqv?} on other objects such as | |
42 | numbers and symbols. A rule of thumb is that objects are generally | |
43 | @code{equal?} if they print the same. @code{equal?} may fail to | |
44 | terminate if its arguments are circular data structures. | |
45 | @end deffn | |
46 | ||
47 | ||
48 | @node Property Lists | |
49 | @section Property Lists | |
50 | ||
51 | Every object in the system can have a @dfn{property list} that may | |
52 | be used for information about that object. For example, a | |
53 | function may have a property list that includes information about | |
54 | the source file in which it is defined. | |
55 | ||
56 | Property lists are implemented as assq lists (@pxref{Association Lists}). | |
57 | ||
58 | Currently, property lists are implemented differently for procedures and | |
59 | closures than for other kinds of objects. Therefore, when manipulating | |
60 | a property list associated with a procedure object, use the | |
61 | @code{procedure} functions; otherwise, use the @code{object} functions. | |
62 | ||
63 | @c docstring begin (texi-doc-string "guile" "object-properties") | |
64 | @deffn primitive object-properties obj | |
65 | @deffnx primitive procedure-properties obj | |
66 | Return @var{obj}'s property list. | |
67 | @end deffn | |
68 | ||
38a93523 | 69 | @c docstring begin (texi-doc-string "guile" "set-object-properties!") |
ae9f3a15 | 70 | @deffn primitive set-object-properties! obj alist |
38a93523 NJ |
71 | @deffnx primitive set-procedure-properties! obj alist |
72 | Set @var{obj}'s property list to @var{alist}. | |
73 | @end deffn | |
74 | ||
75 | @c docstring begin (texi-doc-string "guile" "object-property") | |
76 | @deffn primitive object-property obj key | |
77 | @deffnx primitive procedure-property obj key | |
78 | Return the property of @var{obj} with name @var{key}. | |
79 | @end deffn | |
80 | ||
38a93523 | 81 | @c docstring begin (texi-doc-string "guile" "set-object-property!") |
ae9f3a15 | 82 | @deffn primitive set-object-property! obj key value |
38a93523 | 83 | @deffnx primitive set-procedure-property! obj key value |
ae9f3a15 MG |
84 | In @var{obj}'s property list, set the property named @var{key} |
85 | to @var{value}. | |
38a93523 NJ |
86 | @end deffn |
87 | ||
88 | [Interface bug: there should be a second level of interface in which | |
89 | the user provides a "property table" that is possibly private.] | |
90 | ||
91 | ||
92 | @node Primitive Properties | |
93 | @section Primitive Properties | |
94 | ||
95 | @c docstring begin (texi-doc-string "guile" "primitive-make-property") | |
96 | @deffn primitive primitive-make-property not_found_proc | |
97 | Create a @dfn{property token} that can be used with | |
98 | @code{primitive-property-ref} and @code{primitive-property-set!}. | |
99 | See @code{primitive-property-ref} for the significance of | |
100 | @var{not_found_proc}. | |
101 | @end deffn | |
102 | ||
103 | @c docstring begin (texi-doc-string "guile" "primitive-property-ref") | |
104 | @deffn primitive primitive-property-ref prop obj | |
105 | Return the property @var{prop} of @var{obj}. When no value | |
106 | has yet been associated with @var{prop} and @var{obj}, call | |
107 | @var{not-found-proc} instead (see @code{primitive-make-property}) | |
108 | and use its return value. That value is also associated with | |
109 | @var{obj} via @code{primitive-property-set!}. When | |
110 | @var{not-found-proc} is @code{#f}, use @code{#f} as the | |
111 | default value of @var{prop}. | |
112 | @end deffn | |
113 | ||
114 | @c docstring begin (texi-doc-string "guile" "primitive-property-set!") | |
115 | @deffn primitive primitive-property-set! prop obj val | |
116 | Associate @var{code} with @var{prop} and @var{obj}. | |
117 | @end deffn | |
118 | ||
119 | @c docstring begin (texi-doc-string "guile" "primitive-property-del!") | |
120 | @deffn primitive primitive-property-del! prop obj | |
121 | Remove any value associated with @var{prop} and @var{obj}. | |
122 | @end deffn | |
123 | ||
124 | ||
125 | @node Sorting | |
126 | @section Sorting | |
127 | ||
128 | @c docstring begin (texi-doc-string "guile" "merge!") | |
129 | @deffn primitive merge! alist blist less | |
130 | Takes two lists @var{alist} and @var{blist} such that | |
131 | @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and | |
132 | returns a new list in which the elements of @var{alist} and | |
133 | @var{blist} have been stably interleaved so that | |
134 | @code{(sorted? (merge alist blist less?) less?)}. | |
135 | This is the destructive variant of @code{merge} | |
136 | Note: this does _not_ accept vectors. | |
137 | @end deffn | |
138 | ||
139 | @c docstring begin (texi-doc-string "guile" "merge") | |
140 | @deffn primitive merge alist blist less | |
141 | @end deffn | |
142 | ||
143 | @c docstring begin (texi-doc-string "guile" "restricted-vector-sort!") | |
144 | @deffn primitive restricted-vector-sort! vec less startpos endpos | |
145 | Sort the vector @var{vec}, using @var{less} for comparing | |
146 | the vector elements. @var{startpos} and @var{endpos} delimit | |
147 | the range of the vector which gets sorted. The return value | |
148 | is not specified. | |
149 | @end deffn | |
150 | ||
151 | @c docstring begin (texi-doc-string "guile" "sort!") | |
152 | @deffn primitive sort! items less | |
153 | Sort the sequence @var{items}, which may be a list or a | |
154 | vector. @var{less} is used for comparing the sequence | |
155 | elements. The sorting is destructive, that means that the | |
156 | input sequence is modified to produce the sorted result. | |
157 | This is not a stable sort. | |
158 | @end deffn | |
159 | ||
160 | @c docstring begin (texi-doc-string "guile" "sort") | |
161 | @deffn primitive sort items less | |
162 | Sort the sequence @var{items}, which may be a list or a | |
163 | vector. @var{less} is used for comparing the sequence | |
164 | elements. This is not a stable sort. | |
165 | @end deffn | |
166 | ||
167 | @c docstring begin (texi-doc-string "guile" "sort-list!") | |
168 | @deffn primitive sort-list! items less | |
169 | Sort the list @var{items}, using @var{less} for comparing the | |
170 | list elements. The sorting is destructive, that means that the | |
171 | input list is modified to produce the sorted result. | |
172 | This is a stable sort. | |
173 | @end deffn | |
174 | ||
175 | @c docstring begin (texi-doc-string "guile" "sort-list") | |
176 | @deffn primitive sort-list items less | |
177 | Sort the list @var{items}, using @var{less} for comparing the | |
178 | list elements. This is a stable sort. | |
179 | @end deffn | |
180 | ||
181 | @c docstring begin (texi-doc-string "guile" "sorted?") | |
182 | @deffn primitive sorted? items less | |
183 | Return @code{#t} iff @var{items} is a list or a vector such that | |
184 | for all 1 <= i <= m, the predicate @var{less} returns true when | |
185 | applied to all elements i - 1 and i | |
186 | @end deffn | |
187 | ||
188 | @c docstring begin (texi-doc-string "guile" "stable-sort!") | |
189 | @deffn primitive stable-sort! items less | |
190 | Sort the sequence @var{items}, which may be a list or a | |
191 | vector. @var{less} is used for comparing the sequence elements. | |
192 | The sorting is destructive, that means that the input sequence | |
193 | is modified to produce the sorted result. | |
194 | This is a stable sort. | |
195 | @end deffn | |
196 | ||
197 | @c docstring begin (texi-doc-string "guile" "stable-sort") | |
198 | @deffn primitive stable-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 elements. | |
201 | This is a stable sort. | |
202 | @end deffn | |
203 | ||
204 | ||
205 | @node Copying | |
206 | @section Copying Deep Structures | |
207 | ||
208 | @c docstring begin (texi-doc-string "guile" "copy-tree") | |
209 | @deffn primitive copy-tree obj | |
210 | Recursively copy the data tree that is bound to @var{obj}, and return a | |
211 | pointer to the new data structure. @code{copy-tree} recurses down the | |
212 | contents of both pairs and vectors (since both cons cells and vector | |
213 | cells may point to arbitrary objects), and stops recursing when it hits | |
214 | any other object. | |
215 | @end deffn | |
216 | ||
217 | ||
218 | @c Local Variables: | |
219 | @c TeX-master: "guile.texi" | |
220 | @c End: |