Tracking Issue for array_methods

[LukasKalbertodt]

This is a tracking issue for a couple of basic methods on arrays. The feature gate for the issue is #![feature(array_methods)]. Currently, this includes the following methods:

• as_slice, as_mut_slice Add [T; N]::as_[mut_]slice #76120
• each_ref, each_mut Add [T; N]::each_ref and [T; N]::each_mut #75490

Note: these methods were all collected under the same array_methods feature name as I suspect many (often small) methods to be added to array in the near future. Creating a new feature and tracking issue for each seems overkill. We can still split off some methods into dedicated features later, if required.

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also uses 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.

Steps

• Decide what set of methods to stabilize in the first round
• Change feature names of all methods that are not yet stabilized to something specific
• Adjust documentation (see instructions on rustc-dev-guide)
• Stabilization PR (see instructions on rustc-dev-guide)

Unresolved Questions

• Use the names each_ref and each_mut or change it to something else? Alternatives: each_as_ref/each_as_mut, as_refs/as_mut_refs. See PR Add [T; N]::each_ref and [T; N]::each_mut #75490 for the name discussion.

[LukasKalbertodt]

Just for the protocol, I plan to add the following methods in the near future:

• cloned, copied and unzip: blocked by figuring out how we best add additional impl blocks for arrays (e.g. [&T; N] where T: Clone)
• zip: waiting for add array::FillError similar to array::IntoIter #75717 or Add 'core::array::from_fn' and 'core::array::try_from_fn' #75644 to get merged; otherwise this method would add duplicate code already added in Added [T; N]::zip() #79451

(discussions about the usefulness of those method should be had in the dedicated PR threads and not here)

[usbalbin]

@LukasKalbertodt I have opened PR #79451 for zip, saw your comment just now.

[rossmacarthur]

With regards to stabilization I think as_slice, as_mut_slice could be stabilized first.

I think they are much more useful than the others in this tracking issue. These are already common methods for existing data types so it's not a new API.

I sometimes find myself running into cases where Deref coercion doesn't work and I need this. Currently I'm using &arr[..] which doesn't really communicate well why it is needed.

For example

// io::Read does something like this
trait Trait {}
impl Trait for &[u8] {}
impl<T: Trait + ?Sized> Trait for &mut T {}

fn takes_trait(t: impl Trait) {}

fn main() {
    let mut arr = [0, 1, 2, 3];
    
    // currently
    takes_trait(&mut &arr[..]);
    
    // with `.as_slice()` its nice and clear
    takes_trait(&mut arr.as_slice());
    
    // can't use deref coercion in this case
    takes_trait(&mut &arr);
    //          ^^^^^^^^^ the trait `Trait` is not implemented for `&[u8; 4]`
}

[LukasKalbertodt]

I agree with @rossmacarthur and would like to propose stabilizing as_slice and as_mut_slice. These methods exist on many other types throughout std (e.g. Vec) and I can't think of a reason to wait with stabilization. I can't see how the name or semantics would still change. And I'm pretty sure we want those methods.

[jhpratt]

Partial stabilization is up: #88353

[jplatte]

Hm, I didn't think too much about it when posting the last reply. I guess you're right about Iterator::as_ref and the longer names are.. Longer. The current solution definitely isn't bad!

[Aaron1011]

Are there any further objections over the current names, or are these ready to stabilize?

[Zenithsiz]

Can these be made const fns? Or are we still missing features to allow these to become const fns?

[KamilaBorowska]

Can these be made const fns? Or are we still missing features to allow these to become const fns?

Technically each_ref can be made a const fn (it can be implemented on stable), however it would require complicating the method noticeably, and that probably wouldn't be worth it at this point.

For instance, with array_macro crate (to show that it's possible, obviously standard library shouldn't be using it), it's possible to implement it like this:

const fn each_ref<T, const N: usize>(arr: &[T; N]) -> [&T; N] {
    array![i => &arr[i]; N]
}

[dead-claudia]

Curious why provide each_ref and each_mut methods, and not just providing by-ref equivalents to all 4 of the self-consuming array methods.

• .map(self, f) -> .map_ref(&self, f), .map_mut(&mut self, f)
• .try_map(self, f) -> .try_map_ref(&self, f), .try_map_mut(&mut self, f)
• .zip(self, other) -> .zip_ref(&self, &other)/.zip_mut(&mut self, &mut other)
• .transpose(self) -> .transpose_ref(&self)/.transpose_mut(&mut self)

This would avoid intermediate arrays of almost-always-pointless references, would save a method call in almost all cases, and likely be easier to optimize for. Also, .transpose_{ref,mut} has direct precedent elsewhere - all the assume_init methods for MaybeUninit also carry *_ref and *_mut variants.

[workingjubilee]

Noteworthy: zip_array was also recalled for generating intermediate references.

[pierzchalski]

@LukasKalbertodt Is there anything specific blocking stabilization of each_ref and each_mut? I notice we haven't gotten consensus on the names, but also no one seems to have a very strong opinion afaics?

[LukasKalbertodt]

@pierzchalski There is an open PR that stabilizes these methods as is. It seems like the current names are generally accepted now.

In the PR there are no objections, but @dead-claudia raised an objection in this thread above. I would disagree though: having three versions of every method makes for a really bloated and awkward API. Yes, it's not uncommon in Rust to have these three versions of the same method, but usually only if there isn't a better way. In the MaybeUninit example, I'm not entirely sure why this specific API was chosen, but I don't think it's possible to add some foo_ref method to replace bar.assume_init_ref() with bar.foo_ref().assume_init(). And also: there, it's just one method with three versions.

Regarding optimization: yep, I heard that array methods tend to optimize non-optimally in some cases. That's unfortunate of course. But this is just a consequences of how the optimization pipeline works right now; the API does not inherently make proper optimizations impossible! Many people have proposed some kind of constant length iterator with lazy evaluation, but I have no idea if there is any progress on that. Thus, I personally don't think these are arguments against each_ref and each_mut. And I hope the linked PR will be merged soon.

[dtolnay]

@rust-lang/libs-api:
@rfcbot fcp merge

impl [T; N] {
    pub fn each_ref(&self) -> [&T; N];
    pub fn each_mut(&mut self) -> [&mut T; N];
}

I suggested this naming in #75490 (review) and provided further rationale for it in #75490 (review). I continue to think these are good names. The naming discussion above has reached a stopping point without any traction behind any better set of names, in my opinion.

Aside from naming, a point to consider was whether these functions are amenable enough to optimization. See #76118 (comment) with a response in #76118 (comment).

In #80094 (comment) we removed pub fn zip<U>(self, [U; N]) -> [(T, U); N] because [(T, U); N] is not the end product anyone wanted; it would always have been followed up with a map in practice, suggesting some kind of iterator-based zip and chunk/collect would be more suitable.

Is [&T; N] / [&mut T; N] a different situation? Currently the documentation identifies only map as the motivation.

let strings = ["Ferris".to_string(), "♥".to_string(), "Rust".to_string()];
let is_ascii = strings.each_ref().map(|s| s.is_ascii());
assert_eq!(is_ascii, [true, false, true]);

// We can still access the original array: it has not been moved.

But notice that &[&T] is a construct that is relatively more common in APIs than [(T, U); N], so at least each_ref might find a use there. Stuff like:

rust/compiler/rustc_lint/src/context.rs

Line 209 in d7229c4

pub fn register_lints(&mut self, lints: &[&'static Lint]) {

rust/compiler/rustc_codegen_llvm/src/builder.rs

Line 224 in d7229c4

args: &[&'ll Value],

rust/compiler/rustc_codegen_llvm/src/common.rs

Line 97 in d7229c4

pub fn const_array(&self, ty: &'ll Type, elts: &[&'ll Value]) -> &'ll Value {

Alternatives: something like strings.iter().map(|s| s.is_ascii()).array_chunks::<3>().next().unwrap().

[rfcbot]

Team member @dtolnay has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[pravic]

Any news about this?

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.