Tracking Issue for Iterator::array_chunks

Feature gate: #![feature(iter_array_chunks)]

This is a tracking issue for Iterator::array_chunks, an iterator adapter that allows to group elements of an iterator.

Public API

// trait Iterator

fn array_chunks<const N: usize>(self) -> ArrayChunks<Self, N>
where
    Self: Sized,self);

// core::iter

pub struct ArrayChunks<I: Iterator, const N: usize> { ... }

impl<I, const N: usize> ArrayChunks<I, N> {
    pub fn into_remainder(self) -> Option<array::IntoIter<I::Item, N>>;
}

impl<I: Iterator, const N: usize> Iterator for ArrayChunks<I, N> {
    type Item = [I::Item; N];
}

impl<I: DoubleEndedIterator + ExactSizeIterator, const N: usize> DoubleEndedIterator for ArrayChunks<I, N> {}
impl<I: FusedIterator, const N: usize> FusedIterator for ArrayChunks<I, N> {}
impl<I: ExactSizeIterator, const N: usize> ExactSizeIterator for ArrayChunks<I, N> {}

Steps / History

Implementation: Add Iterator::array_chunks (take N+1) #100026
unwrap ret ty of iter::ArrayChunks::into_remainder #149127
Final comment period (FCP)¹
Stabilization PR

Unresolved Questions

Should DoubleEndedIterator be implemented?
- Is there a use-case for this?
- In order to yield the same items either way we require ExactSizeIterator
- Note that .rev().array_chunks() and .array_chunks().rev() are different
- If we decide to keep DoubleEndedIterator implementation should be improved
  - For example, maybe there should be Iterator::next_chunk_back like there is for forward
- Is the unwrap_err_unchecked in next_back_remainder sound, despite not using TrustedLen? (I didn't block the original PR on this because it goes through take, which I think we can trust, but I'd like someone smarter than me to think about it and confirm.)
Should this be a type error for N != 0? (See also this same question in [T]::as_chunks.)
What's the tradeoff between the item type being array::IntoIter<T, N> and the current one where the items are [T; N] and there's a remainder? ([T]::array_chunks has this question too and is unstable.)

https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

What's the tradeoff between the item type being array::IntoIter<T, N> and the current one where the items are [T; N] and there's a remainder?

It is definitely valuable to have a guaranteed, fixed length in the happy path. It aids vectorization and known-length specialization. It could even help in-place iteration in shapes like vec.into_iter().array_chunks().map(...).flatten().collect().

Might be good to align the naming of this function with Iterator::next_chunk, i.e. either

Iterator::chunks
Iterator::next_chunk

Or

Iterator::array_chunks
Iterator::next_array_chunk (or Iterator::next_array)?

I think I'd vote for Iterator::chunks since arrays are a pretty clear fit for what this function accomplishes and array_chunks is a bit unwieldy.

It seems good to follow the same naming conventions as slice::array_chunks #74985 where possible?

I think that the name Iterator::array_chunks is fine, but not great. The simple present tense of the verb 'to chunk' (i.e. Iterator::chunk) could better indicate the action portion of organizing separate smaller units into single larger units. This should also avoid overriding the meaning of the plural noun 'chunks' as defined by Itertools::chunks (#104969 (comment)). As for following the naming convention of slice::array_chunks (#74985), it is also a nightly-only experimental API, so now should be a perfect time to change both as the above reasoning for using chunk applies there as well.

An interesting unresolved question was brought up in #116000, should ArrayChunks::into_remainder return Option?

I do not see the point of artificially converting an empty slice into a None, which needs to be unwrapped on use. Or semantically, it's not that the remainder is undefined, it just happens to be empty.

Do you think we could move towards stabilizing this now? looking at the concerns regarding the implementation of next_back_remainder, i looked a bit but i couldnt figure out any way to override take, and Take<I>.next_chunk wont call I::next_chunk, so im decently sure its sound, and the type error for N != 0 seems to have been resolved (as [T]::as_chunks is stable), and i think we definitely do want a real array. next_chunk_back doesnt really seem like a huge blocker, given it would need to be implemented for several other iterators too? with as_chunks stabilized and array_windows approved i feel like its only natural to stabilize Iterator::array_chunks.

One question that comes to mind looking at the API is why into_remainder returns an option? Couldn't it just return array::IntoIter<I::Item, N>, which is empty in case there is no remainder? (see also previous comments mentioning this and #116000)

If there is a reason for the option, the documentation should explicitly say when the method returns Some or None.

@rustbot

For the proposed signature change (#149127), and to consider stabilization or other blockers:

@rustbot label +I-libs-api-nominated

Rollup merge of rust-lang#149127 - bend-n:iter_array_chunks_into_rema…

Unrolled build for #149127

One question that comes to mind looking at the API is why into_remainder returns an option? Couldn't it just return array::IntoIter<I::Item, N>, which is empty in case there is no remainder? (see also previous comments mentioning this and #116000)

If there is a reason for the option, the documentation should explicitly say when the method returns Some or None.

In terms of usability, there's value in easily knowing it's empty so you can write a conditional rather than a loop. "if there's a remainder" can be easier than "unconditionally process the remainder, which might be empty", especially if there's some work you need to do before or after iterating over the remainder.

that wasnt actually the behavior of the Option though? also, its a array::IntoIter specifically so you can just as_slice it and do things with that.

We discussed this during a libs-api meeting.

A major obstacle to stabilization is that this builds on next_chunk (#98326) which is also unstable and in its current API shape is likely not good for performance (vectorization, small N) of iterators consisting of nested adapters. And it also blows up stack space for large N.

That one likely needs an API redesign to become a lower-level API (e.g. by taking maybeuninit buffers) or compiler optimizations to make enums holding arrays have a more efficient return ABI.

Rollup merge of rust-lang#149127 - bend-n:iter_array_chunks_into_rema…

Shouldn't this be similar to array_windows in terms of performance and stack use concerns? Or why was it possible to stabilize that recently and not this?

Well no, array_windows is a method on a slice, the counterpart to that would be as_chunks, which is stable. array_chunks is a method on iterator, which works on Iterator::next_chunk, instead of just on a slice.

Oh didn't know about that, my bad, stupid comment, thanks! 😄

Navigation Menu

Repository navigation

Tracking Issue for `Iterator::array_chunks` #100450

Public API

Steps / History

Unresolved Questions

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Tracking Issue for Iterator::array_chunks #100450

Description

Public API

Steps / History

Unresolved Questions

Footnotes

Activity

the8472 commented on Aug 13, 2022

rossmacarthur commented on Nov 1, 2022

camelid commented on Nov 20, 2022

adamse commented on Dec 3, 2022

andria-dev commented on Dec 12, 2023

GnomedDev commented on Feb 20, 2024

ronnodas commented on Feb 21, 2024

bend-n commented on Nov 18, 2025

WaffleLapkin commented on Nov 20, 2025

tgross35 commented on Nov 20, 2025

joshtriplett commented on Nov 25, 2025

bend-n commented on Nov 25, 2025

the8472 commented on Nov 27, 2025

Philogy commented on Mar 11, 2026

bend-n commented on Mar 11, 2026

Philogy commented on Mar 11, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Tracking Issue for `Iterator::array_chunks` #100450