General Utility Functions
*************************

Equality
========

 -- primitive: eq? x y
     Return #t iff X references the same object as Y. eq? is similar to eqv? except that in some cases it is capable of discerning distinctions finer than those detectable by eqv?.

 -- primitive: eqv? x y
     The eqv? procedure defines a useful equivalence relation on objects. Briefly, it returns #t if X and 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.

 -- primitive: equal? x y
     Return #t iff X and Y are recursively eqv? equivalent. equal? recursively compares the contents of pairs, vectors, and strings, applying eqv? on other objects such as numbers and symbols.  A rule of thumb is that objects are generally equal?  if they print the same.  equal? may fail to terminate if its arguments are circular data structures.

Property Lists
==============

Every object in the system can have a 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 (see 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 procedure functions; otherwise, use the object functions.

 -- primitive: object-properties obj
 -- primitive: procedure-properties obj
     Return OBJ's property list.

 -- primitive: set-object-properties! obj alist
 -- primitive: set-procedure-properties! obj alist
     Set OBJ's property list to ALIST.

 -- primitive: object-property obj key
 -- primitive: procedure-property obj key
     Return the property of OBJ with name KEY.

 -- primitive: set-object-property! obj key value
 -- primitive: set-procedure-property! obj key value
     In OBJ's property list, set the property named KEY to VALUE.

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

Primitive Properties
====================

 -- primitive: primitive-make-property not_found_proc
     Create a property token that can be used with primitive-property-ref and primitive-property-set!. See primitive-property-ref for the significance of NOT_FOUND_PROC.

 -- primitive: primitive-property-ref prop obj
     Return the property PROP of OBJ.  When no value has yet been associated with PROP and OBJ, call NOT-FOUND-PROC instead (see primitive-make-property) and use its return value.  That value is also associated with OBJ via primitive-property-set!.  When NOT-FOUND-PROC is #f, use #f as the default value of PROP.

 -- primitive: primitive-property-set! prop obj val
     Associate CODE with PROP and OBJ.

 -- primitive: primitive-property-del! prop obj
     Remove any value associated with PROP and OBJ.

Sorting
=======

 -- primitive: merge! alist blist less
     Takes two lists ALIST and BLIST such that (sorted? alist less?) and (sorted? blist less?) and returns a new list in which the elements of ALIST and BLIST have been stably interleaved so that (sorted? (merge alist blist less?) less?). This is the destructive variant of merge Note:  this does _not_ accept vectors.

 -- primitive: merge alist blist less

 -- primitive: restricted-vector-sort! vec less startpos endpos
     Sort the vector VEC, using LESS for comparing the vector elements.  STARTPOS and ENDPOS delimit the range of the vector which gets sorted.  The return value is not specified.

 -- primitive: sort! items less
     Sort the sequence ITEMS, which may be a list or a vector.  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.

 -- primitive: sort items less
     Sort the sequence ITEMS, which may be a list or a vector.  LESS is used for comparing the sequence elements.  This is not a stable sort.

 -- primitive: sort-list! items less
     Sort the list ITEMS, using 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.

 -- primitive: sort-list items less
     Sort the list ITEMS, using LESS for comparing the list elements. This is a stable sort.

 -- primitive: sorted? items less
     Return #t iff ITEMS is a list or a vector such that for all 1 <= i <= m, the predicate LESS returns true when applied to all elements i - 1 and i

 -- primitive: stable-sort! items less
     Sort the sequence ITEMS, which may be a list or a vector. 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.

 -- primitive: stable-sort items less
     Sort the sequence ITEMS, which may be a list or a vector. LESS is used for comparing the sequence elements. This is a stable sort.

Copying Deep Structures
=======================

 -- primitive: copy-tree obj
     Recursively copy the data tree that is bound to OBJ, and return a pointer to the new data structure.  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.