summaryrefslogtreecommitdiff
path: root/doc/scheme-utility.texi
blob: 2bf1dfd0d605764896585a98b1f522cb972b5f50 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
@page
@node Utility Functions
@chapter General Utility Functions

@menu
* Equality::                    When are two values `the same'?
* Property Lists::              Managing metainformation about Scheme objects.
* Primitive Properties::        A modern low-level interface to object properties.
* Sorting::                     Sort utility procedures.
* Copying::                     Copying deep structures.
@end menu


@node Equality
@section Equality
@r5index eq?
@r5index eqv?
@r5index equal?

@c docstring begin (texi-doc-string "guile" "eq?")
@deffn primitive eq? x y
Return @code{#t} iff @var{x} references the same object as @var{y}.
@code{eq?} is similar to @code{eqv?} except that in some cases it is
capable of discerning distinctions finer than those detectable by
@code{eqv?}.
@end deffn

@c docstring begin (texi-doc-string "guile" "eqv?")
@deffn primitive eqv? x y
The @code{eqv?} procedure defines a useful equivalence relation on objects.
Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be
regarded as the same object.  This relation is left slightly open to
interpretation, but works for comparing immediate integers, characters,
and inexact numbers.
@end deffn

@c docstring begin (texi-doc-string "guile" "equal?")
@deffn primitive equal? x y
Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent.
@code{equal?} recursively compares the contents of pairs,
vectors, and strings, applying @code{eqv?} on other objects such as
numbers and symbols.  A rule of thumb is that objects are generally
@code{equal?}  if they print the same.  @code{equal?} may fail to
terminate if its arguments are circular data structures.
@end deffn


@node Property Lists
@section Property Lists

Every object in the system can have a @dfn{property list} that may
be used for information about that object.  For example, a
function may have a property list that includes information about
the source file in which it is defined.

Property lists are implemented as assq lists (@pxref{Association Lists}).

Currently, property lists are implemented differently for procedures and
closures than for other kinds of objects.  Therefore, when manipulating
a property list associated with a procedure object, use the
@code{procedure} functions; otherwise, use the @code{object} functions.

@c docstring begin (texi-doc-string "guile" "object-properties")
@deffn primitive object-properties obj
@deffnx primitive procedure-properties obj
Return @var{obj}'s property list.
@end deffn

@c ARGFIXME alist/plist
@c docstring begin (texi-doc-string "guile" "set-object-properties!")
@deffn primitive set-object-properties! obj plist
@deffnx primitive set-procedure-properties! obj alist
Set @var{obj}'s property list to @var{alist}.
@end deffn

@c docstring begin (texi-doc-string "guile" "object-property")
@deffn primitive object-property obj key
@deffnx primitive procedure-property obj key
Return the property of @var{obj} with name @var{key}.
@end deffn

@c ARGFIXME val/value
@c docstring begin (texi-doc-string "guile" "set-object-property!")
@deffn primitive set-object-property! obj key val
@deffnx primitive set-procedure-property! obj key value
In @var{obj}'s property list, set the property named @var{key} to
@var{value}.
@end deffn

[Interface bug:  there should be a second level of interface in which
the user provides a "property table" that is possibly private.]


@node Primitive Properties
@section Primitive Properties

@c docstring begin (texi-doc-string "guile" "primitive-make-property")
@deffn primitive primitive-make-property not_found_proc
Create a @dfn{property token} that can be used with
@code{primitive-property-ref} and @code{primitive-property-set!}.
See @code{primitive-property-ref} for the significance of
@var{not_found_proc}.
@end deffn

@c docstring begin (texi-doc-string "guile" "primitive-property-ref")
@deffn primitive primitive-property-ref prop obj
Return the property @var{prop} of @var{obj}.  When no value
has yet been associated with @var{prop} and @var{obj}, call
@var{not-found-proc} instead (see @code{primitive-make-property})
and use its return value.  That value is also associated with
@var{obj} via @code{primitive-property-set!}.  When
@var{not-found-proc} is @code{#f}, use @code{#f} as the
default value of @var{prop}.
@end deffn

@c docstring begin (texi-doc-string "guile" "primitive-property-set!")
@deffn primitive primitive-property-set! prop obj val
Associate @var{code} with @var{prop} and @var{obj}.
@end deffn

@c docstring begin (texi-doc-string "guile" "primitive-property-del!")
@deffn primitive primitive-property-del! prop obj
Remove any value associated with @var{prop} and @var{obj}.
@end deffn


@node Sorting
@section Sorting

@c docstring begin (texi-doc-string "guile" "merge!")
@deffn primitive merge! alist blist less
Takes two lists @var{alist} and @var{blist} such that
@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
returns a new list in which the elements of @var{alist} and
@var{blist} have been stably interleaved so that
 @code{(sorted? (merge alist blist less?) less?)}.
This is the destructive variant of @code{merge}
Note:  this does _not_ accept vectors.
@end deffn

@c docstring begin (texi-doc-string "guile" "merge")
@deffn primitive merge alist blist less
@end deffn

@c docstring begin (texi-doc-string "guile" "restricted-vector-sort!")
@deffn primitive restricted-vector-sort! vec less startpos endpos
Sort the vector @var{vec}, using @var{less} for comparing
the vector elements.  @var{startpos} and @var{endpos} delimit
the range of the vector which gets sorted.  The return value
is not specified.
@end deffn

@c docstring begin (texi-doc-string "guile" "sort!")
@deffn primitive sort! items less
Sort the sequence @var{items}, which may be a list or a
vector.  @var{less} is used for comparing the sequence
elements.  The sorting is destructive, that means that the
input sequence is modified to produce the sorted result.
This is not a stable sort.
@end deffn

@c docstring begin (texi-doc-string "guile" "sort")
@deffn primitive sort items less
Sort the sequence @var{items}, which may be a list or a
vector.  @var{less} is used for comparing the sequence
elements.  This is not a stable sort.
@end deffn

@c docstring begin (texi-doc-string "guile" "sort-list!")
@deffn primitive sort-list! items less
Sort the list @var{items}, using @var{less} for comparing the
list elements. The sorting is destructive, that means that the
input list is modified to produce the sorted result.
This is a stable sort.
@end deffn

@c docstring begin (texi-doc-string "guile" "sort-list")
@deffn primitive sort-list items less
Sort the list @var{items}, using @var{less} for comparing the
list elements. This is a stable sort.
@end deffn

@c docstring begin (texi-doc-string "guile" "sorted?")
@deffn primitive sorted? items less
Return @code{#t} iff @var{items} is a list or a vector such that
for all 1 <= i <= m, the predicate @var{less} returns true when
applied to all elements i - 1 and i
@end deffn

@c docstring begin (texi-doc-string "guile" "stable-sort!")
@deffn primitive stable-sort! items less
Sort the sequence @var{items}, which may be a list or a
vector. @var{less} is used for comparing the sequence elements.
The sorting is destructive, that means that the input sequence
is modified to produce the sorted result.
This is a stable sort.
@end deffn

@c docstring begin (texi-doc-string "guile" "stable-sort")
@deffn primitive stable-sort items less
Sort the sequence @var{items}, which may be a list or a
vector. @var{less} is used for comparing the sequence elements.
This is a stable sort.
@end deffn


@node Copying
@section Copying Deep Structures

@c docstring begin (texi-doc-string "guile" "copy-tree")
@deffn primitive copy-tree obj
Recursively copy the data tree that is bound to @var{obj}, and return a
pointer to the new data structure.  @code{copy-tree} recurses down the
contents of both pairs and vectors (since both cons cells and vector
cells may point to arbitrary objects), and stops recursing when it hits
any other object.
@end deffn


@c Local Variables:
@c TeX-master: "guile.texi"
@c End: