doc/scheme-utility.texi

   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
  17 @rnindex eq?
  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
  26 @rnindex eqv?
  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
  36 @rnindex equal?
  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
  69 @c docstring begin (texi-doc-string "guile" "set-object-properties!")
  70 @deffn primitive set-object-properties! obj alist
  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
  81 @c docstring begin (texi-doc-string "guile" "set-object-property!")
  82 @deffn primitive set-object-property! obj key value
  83 @deffnx primitive set-procedure-property! obj key value
  84 In @var{obj}'s property list, set the property named @var{key}
  85 to @var{value}.
  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: