Tuple-Based Variadic Generics

text/0000-variadic-generics.md

@@ -0,0 +1,222 @@
+- Feature Name: `variadic_generics`
+- Start Date: 2017-2-22
+- RFC PR: (leave this empty)
+- Rust Issue: (leave this empty)
+
+# Summary
+[summary]: #summary
+
+This RFC proposes the addition of several features to support variadic generics:
+- An intrinsic `Tuple` trait implemented exclusively by tuples
+- `...T` syntax for tuple types where `T: Tuple`
+- `let (head, ...tail) = tuple;` pattern-matching syntax for tuples
+- `let tuple = (head, ...tail);` syntax for joining an element with a tuple
+
+# Motivation
+[motivation]: #motivation
+
+Variadic generics are a powerful and useful tool commonly requested by Rust
+users (see
+[#376](https://github.com/rust-lang/rfcs/issues/376) and
+[#1921](https://github.com/rust-lang/rfcs/pull/1921)). They allow
+programmers to abstract over non-homogeneous collections, and they make it
+possible to implement functions which accept arguments of varying length and
+type.
+
+Rust has a demonstrable need for variadic generics.
+
+In Rust's own standard library, there are a number of traits which have
+been repeatedly implemented for tuples of varying size up to length 12 using
+macros. This approach has several downsides:
+- It presents arbitrary restrictions on tuples of size 13+.
+- It increases the size of the generated code, resulting in slow compile times.
+- It complicates documentation
+(see the list of trait implementations in
+[this documentation](https://doc.rust-lang.org/std/primitive.tuple.html)).
+
+These arbitrary tuple-length restrictions, manual tuple macros, and confusing
+documentation all combine to increase Rust's learning curve.
+
+Furthermore, community library authors are required to implement similar
+macro-based approaches in order to implement traits for tuples. In the `Diesel`
+crate, it was discovered that replacing macro-generated tuple implementations
+with a structurally-recursive implementation (such as the one proposed here)
+resulted in a 50% decrease in the amount of code generated and a 70% decrease
+in compile times ([link](https://github.com/diesel-rs/diesel/pull/747)). This
+demonstrates that Rust's lack of variadic generics is resulting in a subpar
+edit-compile-debug cycle for at least one prominent, high-quality crate.
+
+The solution proposed here would resolve the limitations above by making it
+possible to implement traits for tuples of arbitrary length. This change would
+make Rust libraries easier to understand and improve the edit-compile-debug
+cycle when using variadic code.
+
+
+# Detailed design
+[design]: #detailed-design
+
+## The `Tuple` Trait
+The following would be implemented by all tuple types:
+```rust
+trait Tuple {
+    type AsRefs<'a>: Tuple + 'a;
+    type AsMuts<'a>: Tuple + 'a;
+    fn elements_as_refs<'a>(&'a self) -> Self::AsRefs<'a>;
+    fn elements_as_mut<'a>(&'a mut self) -> Self::AsMuts<'a>;
+}
+```
+
+The types `AsRefs` and `AsMuts` are the corresponding tuples of references to
+each element in the original tuple. For example,
+`(A, B, C)::AsRefs = (&A, &B, &C)` and
+`(A, B, C)::AsMuts = (&mut A, &mut B, &mut C)`
+
+The `Tuple` trait should only be implemented for tuples and marked with the
+`#[fundamental]` attribute described in
+[the coherence RFC](https://github.com/rust-lang/rfcs/blob/master/text/1023-rebalancing-coherence.md).
+This would allow coherence and type-checking to be extended to assume that no
+implementations of `Tuple` will be added. This enables an increased level of
+negative reasoning making it easier to write blanket implementations of traits
+for tuples.
+
+## The `...T` Type Syntax
+This syntax would allow for expansion of tuple types into a list of types.
+For example, `(A, B, C)` could be represented as `(A, ...(B, C))` or
+`(...(A, B), C)`. This allows users to express type lists of varying arity.
+
+## The `...x` Pattern-Matching Syntax
+This syntax allows for splitting apart the head and tail of a tuple. For
+example, `let (head, ...tail) = (1, 2, 3);` moves the head value, `1`, into
+`head`, and the tail value, `(2, 3)`, into `tail`. Similarly, the last element
+of a tuple could be matched out using `let (...front, last) = (1, 2, 3);`.
+
+## The `...x` Joining Syntax
+This syntax allows pushing an element onto a tuple. It is the natural inverse
+of the pattern-matching operation above. For example,
+`let tuple = (1, ...(2, 3));` would result in `tuple` having a value of
+`(1, 2, 3)`.
+
+## An Example
+
+Using the tools defined above, it is possible to implement `TupleMap`, a
+trait which can apply a mapping function over all elements of a tuple:
+
+```rust
+trait TupleMap<F>: Tuple {
+    type Out: Tuple;
+    fn map(self, f: F) -> Self::Out;
+}
+
+impl<F> TupleMap<F> for () {
+    type Out = ();
+    fn map(self, _: F) {}
+}
+
+impl<Head, Tail, F, R> TupleMap<F> for (Head, ...Tail)
+    where
+    F: Fn(Head) -> R,
+    Tail: TupleMap<F>,
+{
+    type Out = (R, ...<Tail as TupleMap<F>>::Out);
+
+    fn map(self, f: F) -> Self::Out {
+        let (head, ...tail) = self;
+        (f(head), ...tail.map(f))
+    }
+}
+```
+
+This example is derived from
+[a playground example by @eddyb](https://play.rust-lang.org/?gist=8fd29c83271f3e8744a3f618786ca1de&version=nightly&backtrace=0)
+that provided inspiration for this RFC.
+
+The example demonstrates the concise, expressive code enabled
+by this RFC. In order to implement a trait for tuples of any length, all
+that was necessary was to implement the trait for `()` and `(Head, ...Tail)`.
+
+# How We Teach This
+[teach]: #teach
+
+The `...X` syntax can be thought of as a simple syntax expansion. A good mental
+tool is to think of `...` as simply dropping the parenthesis around a tuple, e.g.
+`...(A, B, C)` expanding to `A, B, C`.
+
+This allows for operations that were previously impossible, such as appending
+to the front or tail of a tuple using `(new_head, ...tuple)` or
+`(...tuple, new_last)`, or even `(new_head, ...tuple, new_tail)`.
+
+When teaching this new syntax, it is important to note that the proposed system
+allows for more complicated matching than traditional `Cons`-lists. For example,
+it is possible to match on `(...Front, Last)` in addition to the familiar
+`(Head, ...Tail)`-style matching.
+
+The exact mechanisms used to teach this should be determined after getting more
+experience with how Rustaceans learn. After all, Rust users are a diverse crowd,
+so the "best" way to teach one person might not work as well for another. There
+will need to be some investigation into which explanations are more
+suitable to a general audience.
+
+As for the `(head, ...tail)` joining syntax, this should be explained as
+taking each part of the tail (e.g. `(2, 3, 4)`) and inlining or un-"tupling"
+them (e.g. `2, 3, 4`). This is nicely symmetrical with the `(head, ...tail)`
+pattern-matching syntax.
+
+The `Tuple` trait is a bit of an oddity. It is probably best not to go too
+far into the weeds when explaining it to new users. The extra coherence
+benefits will likely go unnoticed by new users, as they allow for more
+advanced features and wouldn't result in an error where one didn't exist
+before. The obvious exception is when trying to implement the `Tuple` trait.
+Attempts to implement `Tuple` should resort in a relevant error message,
+such as "The `Tuple` trait cannot be implemented for custom types."
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+As with any additions to the language, this RFC would increase the number
+of features present in Rust, potentially resulting increased complexity
+of the language.
+
+There is also some unfortunate overlap between the proposed `(head, ...tail)`
+syntax and the current inclusive range syntax. There will need to be some
+discussion as to how best to overcome this. One possible path could be to
+use `tail...` instead, as it's not obvious that `x...` is distinct from
+`x..` in a useful way (inclusive vs. exclusive range to infinity).
+
+# Alternatives
+[alternatives]: #alternatives
+
+- Do nothing.
+- Implement one of the other variadic designs, such as
+[#1582](https://github.com/rust-lang/rfcs/pull/1582) or
+[#1921](https://github.com/rust-lang/rfcs/pull/1921)
+- Include explicit `Head`, `Tail`, and `Cons<T>` associated types in the `Tuple`
+trait. This could allow the above syntax to be implemented purely as sugar.
+However, this approach introduces a lot of additional complexity. One of the
+complications is that such a trait couldn't be implemented for `()`, so
+there would have to be separate `Cons` and `Split` traits, rather than one
+unified `Tuple`.
+- Allow partial borrows or tuple reference splitting. Previous proposals have
+included a transformation from `&(Head, Tail...)` to `(&Head, &Tail...)`.
+However, this would require that every tuple `(Head, Tail...)` actually
+contain a sub-tuple `tail...`. This would get in the way of desirable
+field-reordering optimizations.
+In order to avoid this restriction, this proposal includes a transformation
+from `&(A, B, C)` to a tuple containing references to all the individual types:
+`(&A, &B, &C)`. Iteration over tuples is then performed by-value (where the
+values are references).
+
+# Unresolved questions
+[unresolved]: #unresolved-questions
+
+- It might be useful in the future to expand on the locations where `...Type`
+can be used. Potential extensions to this RFC could allow `...Type` in
+non-tuple generics or in function argument types, like
+`fn foo<Args>(args: ...Args)`.
+This would allow functions and traits to use variadic generics without
+explicit tuples. This could enable things like the proposed `foo[i, j]` syntax
+using`Index<usize, usize>`.
+- Should the `Tuple` trait use separate `TupleRef<'a>` and `TupleMut<'b>` traits
+to avoid dependency on ATCs? It seems nicer to have them all together in one
+trait, but it might not be worth the resulting feature-stacking mess.
+
+