Overloading resolution

In a call p(args) the routine p that matches best is selected. If multiple routines match equally well, the ambiguity is reported during semantic analysis.

Every arg in args needs to match. There are multiple different categories how an argument can match. Let f be the formal parameter’s type and a the type of the argument.

  1. Exact match: a and f are of the same type.
  2. Literal match: a is an integer literal of value v and f is a signed or unsigned integer type and v is in f’s range. Or: a is a floating point literal of value v and f is a floating point type and v is in f’s range.
  3. Generic match: f is a generic type and a matches, for instance a is int and f is a generic (constrained) parameter type (like in [T] or [T: int|char].
  4. Subrange or subtype match: a is a range[T] and T matches f exactly. Or: a is a subtype of f.
  5. Integral conversion match: a is convertible to f and f and a is some integer or floating point type.
  6. Conversion match: a is convertible to f, possibly via a user defined converter.

These matching categories have a priority: An exact match is better than a literal match and that is better than a generic match etc. In the following count(p, m) counts the number of matches of the matching category m for the routine p.

A routine p matches better than a routine q if the following algorithm returns true:

  1. for each matching category m in ["exact match", "literal match",
  2.                                 "generic match", "subtype match",
  3.                                 "integral match", "conversion match"]:
  4.   if count(p, m) > count(q, m): return true
  5.   elif count(p, m) == count(q, m):
  6.     discard "continue with next category m"
  7.   else:
  8.     return false
  9. return "ambiguous"

Some examples:

  1. proc takesInt(x: int) = echo "int"
  2. proc takesInt[T](x: T) = echo "T"
  3. proc takesInt(x: int16) = echo "int16"
  5. takesInt(4) # "int"
  6. var x: int32
  7. takesInt(x) # "T"
  8. var y: int16
  9. takesInt(y) # "int16"
  10. var z: range[0..4] = 0
  11. takesInt(z) # "T"

If this algorithm returns “ambiguous” further disambiguation is performed: If the argument a matches both the parameter type f of p and g of q via a subtyping relation, the inheritance depth is taken into account:

  1. type
  2.   A = object of RootObj
  3.   B = object of A
  4.   C = object of B
  6. proc p(obj: A) =
  7.   echo "A"
  9. proc p(obj: B) =
  10.   echo "B"
  12. var c = C()
  13. # not ambiguous, calls 'B', not 'A' since B is a subtype of A
  14. # but not vice versa:
  15. p(c)
  17. proc pp(obj: A, obj2: B) = echo "A B"
  18. proc pp(obj: B, obj2: A) = echo "B A"
  20. # but this is ambiguous:
  21. pp(c, c)

Likewise for generic matches the most specialized generic type (that still matches) is preferred:

  1. proc gen[T](x: ref ref T) = echo "ref ref T"
  2. proc gen[T](x: ref T) = echo "ref T"
  3. proc gen[T](x: T) = echo "T"
  5. var ri: ref int
  6. gen(ri) # "ref T"