Tracking Issue for argument splatting lang experiment

This is a tracking issue for the lang experiment into argument splatting, for function overloading and variadic functions (including leaving out optional arguments entirely).
The feature gate for the issue is #![feature(splat)].

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.
Discussion comments will get marked as off-topic or deleted.
Repeated discussions on the tracking issue may lead to the tracking issue getting locked.

Experiment Goals

This experiment facilitates limited forms of function overloading, variadic functions, and optional arguments, by improving the existing syntax at the call site.

Rust already has "overloading at home" via the trait system, but calls to overloaded or variadic functions look strange. The goal of this experiment is to make the call sites look like ordinary function calls, and see how that impacts FFI, coherence, and ergonomics.

Eventually, overloading might improve the usability of many near-identical standard library methods.

Experiment Non-Goals

Rust already has "named arguments at home" via argument destructuring, but calls to named argument functions need to create a struct. We could make call sites look like regular function calls (but with argument names), but that is out of scope for the initial experiment.

Steps

• Land no-op feature gate and experimental syntax, for example, fn foo(#[splat] (T, U, …))
• Land Tuple-only splatting by tupling during typechecking
  • Experiment with using the Tuple trait for FFI overloads using Crubit or similar, using a macro
    • https://github.com/rustfoundation/overloading-macros
  • Experiment with using the Tuple trait for variadic versions of stdlib functions like min() or zip()
    • https://github.com/rust-lang/rust/issues/160728
  • Land cross-crate caller/callee tests
  • Land tests that codegen is correct
  • Land tests for overloading
  • Land tests for variadics
  • Land tests for coherence edge cases
• Require splatted FnDecl and FnPtr args to be a tuple or generic in the declaration
  • Currently this is only checked when it is called
• Land coercion from splatted fn to un-splatted de-tupled fn (e.g. fn (#[splat] (A, B)) to fn (A, B))
  • Update existing coercion tests and add new ones
• Optimise by de-tupling at codegen time
  • In simple cases, the tuples are optimised away anyway, see Zulip discussion
  • Land argument passing tests
  • Land MIR tests that ensure the tuples are optimised away
  • Land codegen tests
• Start an RFC based on what's been learned

Other Tooling

Rustdoc:

• Land rustdoc splatted function argument support
• Land rustdoc splatted function pointer type support

Rustfmt:

• Land rustfmt splatted function pointer type support

Other Potential Experiments

• [ j Add a tuple pattern that splits a type into the first item and the rest of the items, like slice patterns
  • This would allow a N+1 tuple to be reduced to an N tuple, without implementing traits for each tuple arity
  • This is already possible using reflection for homogeneous tuples
• Splat an array into separate arguments of the same type
  • For variadic functions, iterator methods are already stable, but non-variadic use cases are possible
  • This might cause issues with type inference if we can choose either an array or tuple for generics. Requiring a Tuple trait bound for tuples would help, but there could still be struct/array splat ambiguity.
• For now, we won't splat tuple structs (or other structs), because field visibility becomes a huge issue. This also allows ZSTs to be conjured by turning a unit tuple into a splatted ZST argument.

Pre-Stabilization

• Document splat symbol mangling in the v0 mangling guide
  • Should splat be mangled like a regular tuple, or does it need its own special type marker
• Decide on a stabilization-suitable name (if built-in attribute form), rename from #[rustc_splat], and lang FCP breakage from stable name collisions arising from introducing a new built-in attribute (see #159428)

Unresolved Questions

Semantics

• What limits does trait coherence put on foreign function overloads (or variadic functions)?
  • If two overloads overlap, and are prevented by Rust's trait coherence, (how can we|can we at all|should we) make it possible to call those overloads?
• Can we overload on the self type? (self, &self, &mut self, self: Pin<&mut Self›, self: CRef<Self>)

Syntax & Implementation Rules

• Should splatted overloads be sealed, or can any crate add new overloads?
• Can we leave out optional arguments entirely using this feature, or is there a better way?
• What syntax should Rust use for splatting?
• Should splatting be allowed on closures, unboxed closures, or "rust-call" functions? What are the semantics?
• Which other ABIs should splatting be allowed on? "rust", "C", Windows C++ ABIs (cdecl, fastcall, thiscall, vectorcall), anything else?

Ergonomics & Diagnostics

• Will this encourage APIs with large numbers of arguments? How can (or should we) discourage that?
• How can we improve method resolution lookup failure diagnostics, so they aren't a large list of different generic tuple lengths?
• How does this impact code review, code navigation, and editor suggestions?

Future Work

• Will this eventually be useful as a replacement for the "rust-call" pseudo-ABI and related compiler features?
• If we allow overloaded functions with the same name in the same module, how will we disambiguate their symbols? (Currently, function definition symbols are just their paths, but overloaded functions have the same name.)

Sources:

• “splatting” for named arguments and function overloading
• https://github.com/rustfoundation/interop-initiative/issues/14
• Example code using existing unstable features
• #t-lang > On overloading @ 💬 - implementation strategy

Related features

• with #157987 can be used for overloading
• might replace #29625 eventually

Implementation history

See the F-splat label, and also:

• https://github.com/rust-lang/rust/pull/155223 (refactor that isn't specific to this experiment)
• https://github.com/rust-lang/rustc-demangle/pull/90
• https://github.com/rust-lang/rustc-demangle/pull/93
• https://github.com/rustfoundation/overloading-macros
• https://github.com/rustfoundation/overloading-examples and TODO: link to published blog post

Start with the unchecked items in the tracking checklist and the #![feature(splat)] experiment scope. Choose a focused area such as cross-crate tests, coercion tests, MIR/codegen tests, rustdoc, rustfmt, or mangling documentation, then inspect the related existing tests or guides named in the issue. Done means completing that specific checklist item and adding the corresponding tests or documentation.