Regarding prior discussion
I’ve seen this before somewhere, but I can’t remember where. It was described in terms of: We could re-claim namespace in std in order to “delete” deprecated items for one edition, then in a later re-use the same name for something new. Please anyone who knows, provide a link to previous discussion(s).
I don’t remember any particular syntax being proposed in previous discussion. I do remember very long discussions about how editions can’t “delete” anything and why-would-you-need-this and how-does-this-look-in-the-documentation and whatnot. This is besides the point because I’m having a different example in mind. Maybe the point about documentation still applies.
Let’s not think too much about deprecating anything, or about reclaiming names from deprecated items in order to use them for something entirely unrelated. Sure that may be possible with the proposal, too, but can be discussed separately when it’s needed.
Context
I was reminded today of the fact that Vec::retain has the wrong type signature and it’s a known issue for over 6 years now. It will remain an issue for the next decades if we do nothing about it.
current signature
impl<T> Vec<T> {
pub fn retain<F>(&mut self, mut f: F)
where
F: FnMut(&T) -> bool,
{ … }
}
correct signature
impl<T> Vec<T> {
pub fn retain<F>(&mut self, mut f: F)
where
F: FnMut(&mut T) -> bool,
{ … }
}
Changing this signature is unfortunately a breaking change. There doesn’t seem to be any good way around it either, otherwise we’d have a fix for it by now. Indeed, the best proposal right now seems to be to just add another method™ with the proposed name retain_mut. But it would be dissatisfying to have two different methods for doing the same thing; deprecating retain for retain_mut seems weird, too; retain is a much nicer name. Etc… So let’s try discussing an edition-based approach.
I’m not imagining that this could happen in edition2021, but my hope is that we can rectify the situation within 3 years time when an edition2024 would (/might) come.
Changing name resolution based on edition isn’t new either. The 2021 edition changed the meaning of .into_iter() on an array-typed variable. Admitted, that’s method resolution, technically, but I think it goes into the same direction: avoid breakage of a small-but-technically-breaking change with the help of editions.
Feature Idea
Allow definition of multiple items with the same name but applicable to different editions. Syntax example for what’s written in the standard library
// in the standard library
impl<T> Vec<T> {
pub fn edition2021#retain<F>(&mut self, mut f: F)
where
F: FnMut(&T) -> bool,
{ … }
pub fn retain<F>(&mut self, mut f: F)
where
F: FnMut(&mut T) -> bool,
{ … }
}
The definition of such items is only allowed in the standard library. One of the set of items with the same name (but different prefix) must be prefix-free.
However using them works in user crates, too, as follows
// some crate; the edition of this code is edition2021
fn main() {
let mut foo = vec![1, 2, 3, 4];
foo.retain(|&i| {
i % 2 == 0
});
let mut bar = vec![1, 2, 3, 4];
bar.edition2024#retain(|&mut i| {
i % 2 == 0
});
}
// another crate; the edition of this code is edition2024
fn main() {
let mut foo1 = vec![1, 2, 3, 4];
foo1.edition2015#retain(|&i| {
i % 2 == 0
});
let mut foo2 = vec![1, 2, 3, 4];
foo2.edition2018#retain(|&i| {
i % 2 == 0
});
let mut foo3 = vec![1, 2, 3, 4];
foo3.edition2021#retain(|&i| {
i % 2 == 0
});
let mut bar1 = vec![1, 2, 3, 4];
bar1.retain(|&mut i| {
i % 2 == 0
});
let mut bar2 = vec![1, 2, 3, 4];
bar2.edition2024#retain(|&mut i| {
i % 2 == 0
});
}
The idea here is that typically you wouldn’t want to use these edition… prefixes. However when upgrading to a new edition, any mention of an item like retain that changes meaning in the upcoming edition would get a editionDDDD#-prefix by cargo fix --edition.
This proposed syntax uses the newly reserved foo#bar identifier syntax from edition 2021. The already reserved prefixes of the form editionDDDD (where DDDD is the date of an existing edition) get a meaning with this feature proposal. One could also use crater runs to determine if any pre-2021 edition crates would break from reserving all the editionDDDD prefixes (where DDDD is a 4-digit number) to get support throughout all rust editions.
More details
If the standard library defines
editionN#foo { definition1 }
editionM#foo { definition2 }
foo { definition3 }
(where N < M) then for an edition X, writing editionX#foo resolves to
definition1, ifX≤Ndefinition2, ifN<X≤Mdefinition3, ifM<X
Writing foo in a crate that’s on edition X is the same as writing editionX#foo.
Writing editionX#foo only works if X is an edition that already exists and is stabilized; however, X may be higher than the edition that the crate writing editionX#foo is on if the crate is not on the latest stable edition yet.
We could also allow edition_next#foo for an upcoming edition (it might be worth using a shorter prefix than “edition_next”). This way, a stably usable new retain implementation could be offered via edition_next#retain once this feature idea has been implemented and stabilized. Once an upcoming edition like edition2024 is released, cargo fix --edition would replace any usage of edition_next#foo on edition 2021 with edition2024#foo, then the edition could be upgraded, then the post-upgrade cargo fix --edition would remove the prefix. I guess, we’d also want something like edition_next_after_2021#foo for using the newly stable foo in an older edition than 2021. Presumably, once 2024 ist released, this one could be replaced by edition2024#foo in older code as-well by ordinary cargo fix.
The standard library will make sure to define all the edition2024#foo items before edition 2024 is released/stabilized.
Macros
In order not to break macros that use paths like std::vec::Vec::retain, when this path is resolved, the edition of the code that the token retain comes from counts.
When upgrading code containing macros to a new edition, it’s not clear how to detect names in macros being used for such items. Maybe macro_rules macros might just get edition-warnings pointing out any identifier retain appearing with the definition; or successful edition upgrading of crates with macros must rely on sufficient test cases being present so that there’s an actual some usage in a path to an edition-dependent item that can be traced back to the ident token from the macro. Automatic fixing for procedural macros seems off-limits, but sufficiently-tested proc-macros could generate edition-upgrade warnings as well (that would need to be manually fixed).
use and pub use
When re-exporting a module that contains edition dependent names, e.g. path::to:m::edition2021#foo and path::to:m::edition2024#foo both exist, and you’re doing any of
use path::to:m;
use path::to:m as n;
pub use path::to:m;
pub use path::to:m as n;
then all the versions of foo enter the new scope, you can use m::edition2021#foo or n::edition2021#foo, etc. Similar for glob-imports,
use path::to::m::*;
fn main() {
edition2021#foo();
edition2024#foo();
}
If you import the item itself, then only a single version is imported, so you can do
use path::to::m::foo;
fn main() {
foo(); // works
// edition2024#foo(); doesn’t work!
}
// this code is on edition `2021`
use path::to::m::foo;
// the above is equivalent to
use path::to::m::edition2021#foo as foo;
// or
use path::to::m::{edition2021#foo as foo};
// the latter two versions will keep working in future editions
And cargo fix --edition would add the edition-prefixes together with the corresponding as … to the use statements, accordingly. I haven’t thought through the implications of how to do this in macros.
std-internal re-exports of items could do something like
mod m {
fn editionN#foo() {}
fn editionM#foo() {}
fn foo() {}
}
pub use m::{editionN#foo, editionM#foo, foo};
// or equivalently
pub use m::{editionN#foo as editionN#foo, editionM#foo as editionM#foo, foo as foo};
but for user crates, edition-prefixes on the RHS of the as (or without an as) aren’t allowed. I haven’t thought through the backwards-compatibility implications of this rule for macros.
Possible extension
We could also allow “removing” items entirely for some editions. The definition in the standard library could look like
from_edition2018_to_edition2021#foo { definition1 }
from_edition2027#foo { definition2 }
this way, foo (without prefix) wouldn’t be defined at all in editions 2015 and 2024. Similarly, explicit edition2015#foo or edition2027#foo wouldn’t work either. The previous example
editionN#foo { definition1 }
editionM#foo { definition2 }
foo { definition3 }
would be equivalent to
from_edition2015_to_editionN#foo { definition1 }
from_editionA_to_editionM#foo { definition2 }
from_editionB#foo { definition3 }
where A is the edition right after N, and B is the edition right after M. In general, editionX#foo-definitions translate to from_editionC_to_editionX#foo definitions that are as large as possible without producing overlap. If overlap cannot be avoided even with maximally short translations, then the set of definitions is rejected (compilation error).
There’s no to_editionDDDD#foo, because that’s essentially what editionDDDD#foo-definitions are supposed to mean. The extension that items could be removed also drops the requirement that one of the items must be prefix-free.
All of the above in “Possible extension” so far only addresses the definition site, i.e. the standard library.
Onto the user’s side. Names that fall into the “gaps” don’t exist at all. E.g. by marking an old deprecated trait method as follows
trait Foo {
fn edition2021#foobar(&self) {/* with default impl */}
}
// note how this only works when we have dropped
// the requirement that one of the items must be prefix-free
when third-party crates offer an extension-trait
trait FooExt: Foo {
fn foobar(&self);
}
then foo.foobar() calls can successfully resolve to FooExt::foobar in code on edition 2024 or later. This way, not only the standard library but also external crates can benefit from “reclaimed namespace” like that. (On 2021-or-older-edition code, the call must be disambiguated FooExt::foobar(&foo).)
I want to repeat that this idea of “reclaiming namespace” is only part of a possible extension of the main proposal and not the main intended use-case that I’d like to discuss for now.