Rollup merge of rust-lang#87609 - LukasKalbertodt:improve-array-map-d…

…ocs, r=m-ou-se

Add docs about performance and `Iterator::map` to `[T; N]::map`

This suboptimal code gen for some usages of array::map got a bit of
attention by multiple people throughout the community. Some cases:

- rust-lang#75243 (comment)
- rust-lang#75243 (comment)
- https://www.reddit.com/r/rust/comments/oeqqf7/unexpected_high_stack_usage/

My *guess* is that this gets the attention it gets because in JavaScript
(and potentially other languages), a `map` function on arrays is very
commonly used since in those languages, arrays basically take the role
of Rust's iterator. I considered explicitly naming JavaScript in the
first paragraph I added, but I couldn't find precedence of mentioning
other languages in standard library doc, so I didn't add it.

When array::map was stabilized, we still wanted to add docs, but that
somehow did not happen in time. So here we are. Not sure if this sounds
crazy but maybe it is worth considering beta backporting this? Only if
it's not a lot of work, of course! But yeah, stabilized array::map is
already in beta and if this problem is really as big as it sometimes seems,
might be worth having the docs in place when 1.55 is released.

CC ``@CryZe``

r? ``@m-ou-se`` (since you were involved in that discussion and the stabilization)

library/core/src/array/mod.rs

@@ -293,6 +293,28 @@ impl<T, const N: usize> [T; N] {
     /// Returns an array of the same size as `self`, with function `f` applied to each element
     /// in order.
     ///
+    /// If you don't necessarily need a new fixed-size array, consider using
+    /// [`Iterator::map`] instead.
+    ///
+    ///
+    /// # Note on performance and stack usage
+    ///
+    /// Unfortunately, usages of this method are currently not always optimized
+    /// as well as they could be. This mainly concerns large arrays, as mapping
+    /// over small arrays seem to be optimized just fine. Also note that in
+    /// debug mode (i.e. without any optimizations), this method can use a lot
+    /// of stack space (a few times the size of the array or more).
+    ///
+    /// Therefore, in performance-critical code, try to avoid using this method
+    /// on large arrays or check the emitted code. Also try to avoid chained
+    /// maps (e.g. `arr.map(...).map(...)`).
+    ///
+    /// In many cases, you can instead use [`Iterator::map`] by calling `.iter()`
+    /// or `.into_iter()` on your array. `[T; N]::map` is only necessary if you
+    /// really need a new array of the same size as the result. Rust's lazy
+    /// iterators tend to get optimized very well.
+    ///
+    ///
     /// # Examples
     ///
     /// ```