Arthur A. Gleckler scripsit:

> 1. I don't understand this:
>
>   (hash-table-set! *hash-table* ( *key value* ) ...)
>
> In particular, I don't understand the inner parentheses.  Is this a macro?

No, it's a function, and they are meta-parentheses, which is why they
not in code font.  In hindsight, that was too subtle a distinction, so
I'll redo this for the next draft using words to explain the alternating
arguments.

> 2.  What's the reasoning for having some procedures take multiple keys as
> separate arguments and others take them together as a list?

Well, sometimes you have them one way and sometimes you have them
the other way when you are setting up a hash table.

>   (hash-table-set-entries! *hash-table keys-list values-list*)
>
>   (hash-table-delete! *hash-table key* ...)
>
>   (hash-table-delete-keys! *hash-table keys-list*)
> The former doesn't seem useful, and having both makes the API confusing.

The first, as the Sources section notes, is the hash analogue of pairlis,
which has been around in Lisp for a long time.  A more modern equivalent
would be zip when used to construct a-lists.

Having both deletes is probably overkill, but I'm not clear which is
better.  Guidance would be useful.

> 3. In this description:
>
>   (hash-table-extend!/default *hash-table key default*)
>
> "Effectively invokes hash-table-ref/default with the given arguments and
> returns what it returns. If *key* was not found in *hash-table*, its
> association is set to the result being returned. Must execute in expected
> amortized constant time."
>
> Doesn't it set the association's value to *default* in that case?

Yes.  The descriptions are equivalent, though.

>   (hash-table-replace! *hash-table key* [ *failure* [ *success* ] ])

This basically replaces an existing value with the result of calling
*success*, which is kinda pointless if *success* is omitted, since it's
the identity function.  I have to rethink this.

>   (hash-table-replace!/default *hash-table key* *default*)

This one replaces an existing value with *default*.
In both -replace! and -replace!/default, nothing happens if the key
is not found.

> 4. The word "hash-table" appears immediately above the section header
> "Copying and conversion," apparently by accident.

I'll flush it.

--
John Cowan          http://www.ccil.org/~cowan        xxxxxx@ccil.org
A rose by any other name may smell as sweet, but if you called it
an onion you'd get cooks very confused.          --RMS