9.1 General
Buoy permits multiple Functions and Subs to share the same name, provided that each declaration is distinguishable by its parameter list.
When a routine is invoked, the compiler determines which declaration is intended by applying the overload resolution rules defined in this chapter.
Overload resolution is performed entirely at compile time.
9.2 Candidate Set
Given a routine invocation, the compiler first constructs the candidate set.
The candidate set consists of every visible Function or Sub having the specified name and which is eligible for invocation in the current context.
Declarations that are inaccessible or otherwise unavailable are excluded.
9.3 Applicability
A candidate is applicable if each supplied argument can be matched with a corresponding parameter.
The compiler considers:
- the number of arguments
- parameter types
- optional parameters
- named arguments, where supported
- generic type inference
- implicit conversions
Candidates that fail to satisfy these requirements are discarded.
9.4 Best Match
If more than one applicable candidate remains, the compiler determines which candidate most closely matches the supplied arguments.
Preference is given to candidates requiring fewer or less significant conversions.
If a single best candidate exists, that declaration is selected.
9.5 Ambiguity
If more than one applicable candidate is equally suitable, the invocation is ambiguous.
An ambiguous invocation is a compile-time error.
The programmer may resolve the ambiguity by:
- supplying additional type information
- explicitly specifying generic type arguments
- introducing an explicit conversion
- selecting a different overload
9.6 Generic Routines
Generic Functions and Subs participate in overload resolution.
Before comparing candidates, the compiler attempts to infer generic type arguments from the supplied arguments.
A candidate for which type inference fails is not considered applicable.
If more than one generic specialization is applicable, the normal overload resolution rules apply.
9.7 Functions and Subs
Functions and Subs occupy distinct semantic roles.
A Function invocation is valid only where a value is required.
A Sub invocation is valid only as a statement.
Accordingly, overload resolution never substitutes a Sub for a Function, nor a Function for a Sub.
9.8 Accessibility
Only declarations visible at the invocation point participate in overload resolution.
Hidden or inaccessible declarations are ignored.
9.9 Compile-Time Determination
Routine selection is completed before program execution.
The selected declaration remains fixed for that invocation.
Runtime behaviour does not influence overload selection except where explicitly specified by later language features.
9.10 Summary
Overload resolution enables related routines to share a common name while preserving compile-time type safety.
The compiler selects a single declaration using the argument list, parameter types, type inference, and the rules defined in this chapter.