Skip to content

Commit

Permalink
Rollup merge of rust-lang#84590 - est31:array_into_iter, r=nikomatsakis
Browse files Browse the repository at this point in the history
Point out that behavior might be switched on 2015 and 2018 too one day

Reword documentation to make it clear that behaviour can be switched on older editions too, one day in the future. It doesn't *have* to be switched, but I think it's good to have it as an option and re-evaluate it a few months/years down the line when e.g. the crates that showed up in crater were broken by different changes in the language already.

cc rust-lang#25725, rust-lang#65819, rust-lang#66145, rust-lang#84147 , and rust-lang#84133 (comment)
  • Loading branch information
jackh726 authored Apr 29, 2021
2 parents 8f956a3 + a352336 commit 17ab74e
Showing 1 changed file with 47 additions and 2 deletions.
49 changes: 47 additions & 2 deletions library/std/src/primitive_docs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -553,8 +553,10 @@ mod prim_pointer {}
/// # Editions
///
/// Prior to Rust 1.53, arrays did not implement `IntoIterator` by value, so the method call
/// `array.into_iter()` auto-referenced into a slice iterator. That behavior is preserved in the
/// 2015 and 2018 editions of Rust for compatability, ignoring `IntoIterator` by value.
/// `array.into_iter()` auto-referenced into a slice iterator. Right now, the old behavior
/// is preserved in the 2015 and 2018 editions of Rust for compatibility, ignoring
/// `IntoIterator` by value. In the future, the behavior on the 2015 and 2018 edition
/// might be made consistent to the behavior of later editions.
///
#[cfg_attr(bootstrap, doc = "```rust,edition2018,ignore")]
#[cfg_attr(not(bootstrap), doc = "```rust,edition2018")]
Expand Down Expand Up @@ -601,6 +603,49 @@ mod prim_pointer {}
/// }
/// ```
///
/// Future language versions might start treating the `array.into_iter()`
/// syntax on editions 2015 and 2018 the same as on edition 2021. So code using
/// those older editions should still be written with this change in mind, to
/// prevent breakage in the future. The safest way to accomplish this is to
/// avoid the `into_iter` syntax on those editions. If an edition update is not
/// viable/desired, there are multiple alternatives:
/// * use `iter`, equivalent to the old behavior, creating references
/// * use [`array::IntoIter`], equivalent to the post-2021 behavior (Rust 1.51+)
/// * replace `for ... in array.into_iter() {` with `for ... in array {`,
/// equivalent to the post-2021 behavior (Rust 1.53+)
///
#[cfg_attr(bootstrap, doc = "```rust,edition2018,ignore")]
#[cfg_attr(not(bootstrap), doc = "```rust,edition2018")]
/// use std::array::IntoIter;
///
/// let array: [i32; 3] = [0; 3];
///
/// // This iterates by reference:
/// for item in array.iter() {
/// let x: &i32 = item;
/// println!("{}", x);
/// }
///
/// // This iterates by value:
/// for item in IntoIter::new(array) {
/// let x: i32 = item;
/// println!("{}", x);
/// }
///
/// // This iterates by value:
/// for item in array {
/// let x: i32 = item;
/// println!("{}", x);
/// }
///
/// // IntoIter can also start a chain.
/// // This iterates by value:
/// for item in IntoIter::new(array).enumerate() {
/// let (i, x): (usize, i32) = item;
/// println!("array[{}] = {}", i, x);
/// }
/// ```
///
/// [slice]: prim@slice
/// [`Debug`]: fmt::Debug
/// [`Hash`]: hash::Hash
Expand Down

0 comments on commit 17ab74e

Please sign in to comment.