On Tue, Sep 8, 2015 at 5:47 AM, John Cowan <xxxxxx@mercury.ccil.org> wrote:
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.

Aha!  Yes, text would be better.  Imagine a blind person trying using a reader, for example.
 
> 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.

I suppose.  I have a hard time thinking of a case where the as-arguments version would be meaningfully better than the as-a-list version.
 
>   (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.

I prefer the latter.  The hash-table-delete! variant seems made for deleting constant keys, but deleting more than once at a time is rare, and can easily be accomplished by passing a list, which is more flexible.
 
> 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.

The wording is confusing, though.  Perhaps break down the cases more explicitly.
 
>   (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.

I recommend rewording this one, too.