11.5 Object Hashing

The MIT/GNU Scheme object-hashing facility provides a mechanism for generating a unique hash number for an arbitrary object. This hash number, unlike an object’s address, is unchanged by garbage collection. The object-hashing facility is used in the generation of the written representation for many objects (see Custom Output), but it can be used for anything that needs a stable identifier for an arbitrary object.

All of these procedures accept an optional argument called hasher which contains the object-integer associations. If given, this argument must be an object hasher as constructed by make-object-hasher (see below). If not given, a default hasher is used.

procedure: hash-object object [hasher]

obsolete procedure: hash object [hasher]

obsolete procedure: object-hash object [hasher]

hash-object associates an exact non-negative integer with object and returns that integer. If hash-object was previously called with object as its argument, the integer returned is the same as was returned by the previous call. hash-object guarantees that distinct objects (in the sense of eqv?) are associated with distinct integers.

procedure: unhash-object k [hasher]

obsolete procedure: unhash k [hasher]

obsolete procedure: object-unhash k [hasher]

unhash-object takes an exact non-negative integer k and returns the object associated with that integer. If there is no object associated with k, or if the object previously associated with k has been reclaimed by the garbage collector, an error of type condition-type:bad-range-argument is signalled. In other words, if hash-object previously returned k for some object, and that object has not been reclaimed, it is the value of the call to unhash-object.

An object that is passed to hash-object as an argument is not protected from being reclaimed by the garbage collector. If all other references to that object are eliminated, the object will be reclaimed. Subsequently calling unhash-object with the hash number of the (now reclaimed) object will signal an error.

(define x (cons 0 0))           ⇒  unspecified
(hash-object x)                 ⇒  77
(eqv? (hash-object x)
      (hash-object x))          ⇒  #t
(define x 0)                    ⇒  unspecified
(gc-flip)                       ;force a garbage collection
(unhash-object 77)              error→

procedure: object-hashed? object [hasher]

This predicate is true iff object has an associated hash number.

procedure: valid-object-hash? k [hasher]

obsolete procedure: valid-hash-number? k [hasher]

This predicate is true iff k is the hash number associated with some object.

Finally, this procedure makes new object hashers:

procedure: make-object-hasher

obsolete procedure: hash-table/make

This procedure creates and returns a new, empty object hasher that is suitable for use as the optional hasher argument to the above procedures. The returned hasher contains no associations.