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