Implement IntoIterator for [&[mut]] Box<[T; N], A>

[WaffleLapkin]

Revival of #124108

[bors]

☔ The latest upstream changes (presumably #136572) made this pull request unmergeable. Please resolve the merge conflicts.

[WaffleLapkin]

@scottmcm anything I can do to move this forward?

[Mark-Simulacrum]

I guess this also needs rebasing + FCP, maybe starting with the FCP makes sense since it's not obvious to me this is worth it (especially if it needs an edition change...)

View changes since this review

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[WaffleLapkin]

@Mark-Simulacrum I don't think this requires edition handling or FCP, as per the FCP on the previous attempt at doing this:

• Add Box<[T; N]>: IntoIterator without any method dispatch hacks #124108 (comment)
• Add Box<[T; N]>: IntoIterator without any method dispatch hacks #124108 (comment)

@rustbot review

[WaffleLapkin]

I've also removed the complicated unsafe impl for now, making the BoxedArrayIntoIter a wrapper around vec::IntoIter. I'll add back the more complicated impl in a follow-up.

[Mark-Simulacrum]

I don't think this requires edition handling or FCP, as per the FCP on the previous attempt at doing this:

I think we do need FCP or at least libs-api meeting nomination to re-confirm that the >1 year old FCP from 2024 is still valid. Maybe a Crater run. This is a breaking change and there was some post-initial-FCP discussion on whether we should do the unsizing impl (#124108 (comment)). Making two breaking changes here feels unfortunate so we should decide upfront which we want, even if we think the change is otherwise reasonable.

I guess the current version of this PR proposes neither option and instead has a dedicated new iterator type (BoxedArrayIntoIter). I think that's entirely net-new surface area, right? It also means we're missing a chunk of impls (e.g., DoubleEndedIterator) that we'd get 'for free' with vec::IntoIter.

View changes since this review

[WaffleLapkin]

(for the libs-api nomination)

API changes

Negative impls

This PR adds the following negative impls (we promise that those types will never implement Iterator, this shouldn't be controversial) (this is required for the IntoIterator impls added, more below):

impl<T, const N: usize> !Iterator for [T; N] {}
impl<I, const N: usize, A: Allocator> !Iterator for Box<[I; N], A> {}
impl<'a, const N: usize, I, A: Allocator> !Iterator for &'a Box<[I; N], A> {}
impl<'a, const N: usize, I, A: Allocator> !Iterator for &'a mut Box<[I; N], A> {}

IntoIterator impls

It also adds the following IntoIterator impls:

impl<'a, T, const N: usize, A: Allocator> IntoIterator for &'a Box<[T; N], A> {
    type IntoIter = slice::Iter<'a, T>;
    type Item = &'a T;
}

impl<'a, T, const N: usize, A: Allocator> IntoIterator for &'a mut Box<[T; N], A> {
    type IntoIter = slice::IterMut<'a, T>;
    type Item = &'a mut T;
}

impl<T, const N: usize, A: Allocator> IntoIterator for Box<[T; N], A> {
    type IntoIter = BoxedArrayIntoIter<T, N, A>;
    type Item = T;
}

BoxedArrayIntoIter

And the following type with its impls (note: everything is insta-stable):

/// A by-value `Box<[T; N]>` iterator.
pub struct BoxedArrayIntoIter<T, const N: usize, A: Allocator = Global> { ... }

impl<T, const N: usize, A: Allocator> BoxedArrayIntoIter<T, N, A> {
    /// Returns an immutable slice of all elements that have not been yielded
    /// yet.
    pub fn as_slice(&self) -> &[T] { ... }

    /// Returns a mutable slice of all elements that have not been yielded yet.
    pub fn as_mut_slice(&mut self) -> &mut [T] { ... }
}

impl<T, const N: usize, A: Allocator> Iterator for BoxedArrayIntoIter<T, N, A> {
    type Item = T;
    ...
}

impl<T, const N: usize, A: Allocator> DoubleEndedIterator for BoxedArrayIntoIter<T, N, A> { ... }

impl<T, const N: usize, A: Allocator> ExactSizeIterator for BoxedArrayIntoIter<T, N, A> { ... }

impl<T, const N: usize, A: Allocator> FusedIterator for BoxedArrayIntoIter<T, N, A> {}

unsafe impl<T, const N: usize, A: Allocator> TrustedLen for BoxedArrayIntoIter<T, N, A> {}

impl<T: Clone, const N: usize, A: Clone + Allocator> Clone for BoxedArrayIntoIter<T, N, A> { ... }

impl<T: fmt::Debug, const N: usize, A: Allocator> fmt::Debug for BoxedArrayIntoIter<T, N, A> { ... }

Breakage analysis

	Box<[T; N]>	&Box<[T; N]>	&mut Box<[T; N]>
for loop	✅ compile error -> T	✅ compile error -> &T	✅ compile error -> &mut T
.into_iter() (edition >= 2021)	⚠️ array::IntoIter->BoxedArrayIntoIter (T->T)	☢️ array::IntoIter->slice::Iter (T->&T)	☢️ array::IntoIter->slice::IterMut (T->&mut T)
.into_iter() (edition < 2021)	☢️ slice::Iter->BoxedArrayIntoIter (&T->T)	✅ slice::Iter (Item = &T) (unchanged)	☢️ slice::Iter->slice::IterMut (&T->&mut T)

Notes:

• for loop / <_>::into_iter(box) used to be a compilation error; no breakage here
• on edition >= 2021, .into_iter() used to be extremely inefficient, as it would move out the whole array and put it unto the stack
  • on edition >= 2021, .into_iter() on a reference to a box requires T: Copy
• The emoji I used: ✅ - no breakage, ⚠️ - only iterator type changes, not the item (very unlikely to break something), ☢️ - both change

[WaffleLapkin]

If the .into_iter() changes seem like a problem we can

1. Run crater on this PR to check if there is any actual breakage
2. Add a hack similarly to the one we added when implementing IntoIterator for arrays -- make .into_iter() resolve to the old thing before the next edition

[WaffleLapkin]

I guess the current version of this PR proposes neither option and instead has a dedicated new iterator type (BoxedArrayIntoIter). I think that's entirely net-new surface area, right? It also means we're missing a chunk of impls (e.g., DoubleEndedIterator) that we'd get 'for free' with vec::IntoIter.

No, we aren't missing any impls, since I added all of them :)

Also, this PR is compatible with the unsizing idea, with that you would have:

struct AllocatedContinuousIntoIter<T: ?Sized, A: Allocator = Global> { ... } // name bikeshedable

type vec::IntoIter<T, A: Allocator> = AllocatedContinuousIntoIter<[T], A>;
type box::BoxedArrayIntoIter<T, const N: usize, A: Allocator> = AllocatedContinuousIntoIter<[T; N], A>;

Note that vec::IntoIter and box::BoxedArrayIntoIter still normalize to different types, just like in this PR. So we will be able to do this in a follow up.

I.e. one of two follow ups is possible:

1. Making BoxedArrayIntoIter use custom iterator impls, rather than wrapping vec::IntoIter as it does in this PR
2. Making vec::IntoIter more generic, so it can support both use cases (unsizing idea)

[Amanieu]

@rfcbot merge libs-api

[rust-rfcbot]

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

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @the8472

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.