Function overload resolution is vague and incomplete

[dlangBugzillaToGithub]

Bolpat reported this on 2024-08-06T17:08:34Z

Transferred from https://issues.dlang.org/show_bug.cgi?id=24697

Description

Relevant section: https://dlang.org/spec/function.html#function-overloading

- It is unclear what is meant by implicit conversions and if all implicit conversions are equal.
- It is unclear what is meant by a qualifier conversion (does it include lvalue to rvalue conversion? What about @safe to @system conversion?)
- It is even unclear what exactly an exact match is (again, is lvalue to rvalue conversion an exact match)
- It is unclear what “(including any this reference)” means exactly.
- It is not stated if function attributes (on the called function) affect overload resolution

- “Literals do not match `ref` or `out` parameters.” Is not incorrect, but misleading. In general, rvalues are not literals, and it’s them who can’t bind to `ref` and `out`.

- “`scope` parameter storage class does not affect function overloading.” (Bad grammar.) Okay, what about other parameter storage classes? There are `auto` (for `auto ref`), `final` (can indeed be ignored), `in`, `lazy`, `out`, `ref`, `return`, and `scope`, also user-defined ones. The effect of each of them (except `final`) must be specified.

- The `-preview=rvaluerefparam` preview switch is not accounted for.
- The `-preview=in` switch is not accounted for.

There are the following implicit conversions:
- integral conversion from a smaller-range type to a bigger one.
- derived class to base class/interface
- alias this
- lvalue to rvalue
- rvalue to lvalue (for `in` under preview)
- Weakening of attributes for function pointer and delegate types
- qualifier conversions

It may in fact be desirable to vet each of those individually and first judge then explain in the spec whether they fall into match level 2 or 3. E.g. it seems value category is considered by DMD akin to a qualifier, i.e. lvalue to rvalue conversion is not considered an implicit conversion.

Under the `in` preview, overload resolution is affected by whether the argument is bound by reference. IMO, matching against `in` should not depend on that.

Possibly, lvalue to rvalue conversion deserves its own matching level.