New Issue: What requirements do we want on the user-defined hash() return type / value?

19285, "bradcray", "What requirements do we want on the user-defined hash() return type / value?", "2022-02-21T19:04:09Z"

In PR #19266, I updated our user-defined hash function documentation to
improve the description of what's required to define one and found myself noting
that there wasn't any indication of what return type(s) is/are expected. I ended
up writing int or uint because the code that makes the call here is:

    const hash = x.hash();
    return (hash & max(int)): int;

such that either type would work fine (though, for that matter, any other integer type
we support today would as well).

This makes me wonder whether we should:

  1. Tighten or loosen what integer types are expected
    (a) require it to be int (since it seems we ignore the high bit anyway and int is the most convenient integral type in Chapel) but document that it should be non-negative or will be treated in the above way
    (b) require it to be uint (since most existing cases are) but document that the uppermost bit is ignored
    (c) permit it to be either as the docs suggest today
    (d) permit it to be any integral type as the implementation seems to permit today

  2. Say more about what integer values are expected/viable? (e.g., bit 63 is ignored?)

  3. Have a bounds-check for hash functions that return a non-zero in bit 63 to catch potential mistakes / unintended collisions?