### 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 useful in conjunction with hash tables, but it may be used for other things as well. In particular, it is used in the generation of the written representation for many objects (see Custom Output).

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

procedure: hash object [table]

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

procedure: unhash k [table]

  `unhash` 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` previously returned k for some object, and that object has not been reclaimed, it is the value of the call to `unhash`.

An object that is passed to `hash` 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` with the hash number of the (now reclaimed) object will signal an error.

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

procedure: object-hashed? object [table]

  This predicate is true if object has an associated hash number. Otherwise it is false.

procedure: valid-hash-number? k [table]

  This predicate is true if k is the hash number associated with some object. Otherwise it is false.

The following two procedures provide a lower-level interface to the object-hashing mechanism.

procedure: object-hash object [table [insert?]]

  `object-hash` is like `hash`, except that it accepts an additional optional argument, insert?. If insert? is supplied and is `#f`, `object-hash` will return an integer for object only if there is already an association in the table; otherwise, it will return `#f`. If insert? is not supplied, or is not `#f`, `object-hash` always returns an integer, creating an association in the table if necessary.

  `object-hash` additionally treats `#f` differently than does `hash`. Calling `object-hash` with `#f` as its argument will return an integer that, when passed to `unhash`, will signal an error rather than returning `#f`. Likewise, `valid-hash-number?` will return `#f` for this integer.

procedure: object-unhash k [table]

  `object-unhash` is like `unhash`, except that when k is not associated with any object or was previously associated with an object that has been reclaimed, `object-unhash` returns `#f`. This means that there is an ambiguity in the value returned by `object-unhash`: if `#f` is returned, there is no way to tell if k is associated with `#f` or is not associated with any object at all.

Finally, this procedure makes new object-hash tables:

procedure: hash-table/make

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