core/array/mod.rs
1//! Utilities for the array primitive type.
2//!
3//! *[See also the array primitive type](array).*
4
5#![stable(feature = "core_array", since = "1.35.0")]
6
7use crate::borrow::{Borrow, BorrowMut};
8use crate::cmp::Ordering;
9use crate::convert::Infallible;
10use crate::error::Error;
11use crate::fmt;
12use crate::hash::{self, Hash};
13use crate::intrinsics::transmute_unchecked;
14use crate::iter::{UncheckedIterator, repeat_n};
15use crate::mem::{self, MaybeUninit};
16use crate::ops::{
17 ChangeOutputType, ControlFlow, FromResidual, Index, IndexMut, NeverShortCircuit, Residual, Try,
18};
19use crate::ptr::{null, null_mut};
20use crate::slice::{Iter, IterMut};
21
22mod ascii;
23mod drain;
24mod equality;
25mod iter;
26
27pub(crate) use drain::drain_array_with;
28#[stable(feature = "array_value_iter", since = "1.51.0")]
29pub use iter::IntoIter;
30
31/// Creates an array of type `[T; N]` by repeatedly cloning a value.
32///
33/// This is the same as `[val; N]`, but it also works for types that do not
34/// implement [`Copy`].
35///
36/// The provided value will be used as an element of the resulting array and
37/// will be cloned N - 1 times to fill up the rest. If N is zero, the value
38/// will be dropped.
39///
40/// # Example
41///
42/// Creating multiple copies of a `String`:
43/// ```rust
44/// use std::array;
45///
46/// let string = "Hello there!".to_string();
47/// let strings = array::repeat(string);
48/// assert_eq!(strings, ["Hello there!", "Hello there!"]);
49/// ```
50#[inline]
51#[stable(feature = "array_repeat", since = "CURRENT_RUSTC_VERSION")]
52pub fn repeat<T: Clone, const N: usize>(val: T) -> [T; N] {
53 from_trusted_iterator(repeat_n(val, N))
54}
55
56/// Creates an array where each element is produced by calling `f` with
57/// that element's index while walking forward through the array.
58///
59/// This is essentially the same as writing
60/// ```text
61/// [f(0), f(1), f(2), …, f(N - 2), f(N - 1)]
62/// ```
63/// and is similar to `(0..i).map(f)`, just for arrays not iterators.
64///
65/// If `N == 0`, this produces an empty array without ever calling `f`.
66///
67/// # Example
68///
69/// ```rust
70/// // type inference is helping us here, the way `from_fn` knows how many
71/// // elements to produce is the length of array down there: only arrays of
72/// // equal lengths can be compared, so the const generic parameter `N` is
73/// // inferred to be 5, thus creating array of 5 elements.
74///
75/// let array = core::array::from_fn(|i| i);
76/// // indexes are: 0 1 2 3 4
77/// assert_eq!(array, [0, 1, 2, 3, 4]);
78///
79/// let array2: [usize; 8] = core::array::from_fn(|i| i * 2);
80/// // indexes are: 0 1 2 3 4 5 6 7
81/// assert_eq!(array2, [0, 2, 4, 6, 8, 10, 12, 14]);
82///
83/// let bool_arr = core::array::from_fn::<_, 5, _>(|i| i % 2 == 0);
84/// // indexes are: 0 1 2 3 4
85/// assert_eq!(bool_arr, [true, false, true, false, true]);
86/// ```
87///
88/// You can also capture things, for example to create an array full of clones
89/// where you can't just use `[item; N]` because it's not `Copy`:
90/// ```
91/// # // TBH `array::repeat` would be better for this, but it's not stable yet.
92/// let my_string = String::from("Hello");
93/// let clones: [String; 42] = std::array::from_fn(|_| my_string.clone());
94/// assert!(clones.iter().all(|x| *x == my_string));
95/// ```
96///
97/// The array is generated in ascending index order, starting from the front
98/// and going towards the back, so you can use closures with mutable state:
99/// ```
100/// let mut state = 1;
101/// let a = std::array::from_fn(|_| { let x = state; state *= 2; x });
102/// assert_eq!(a, [1, 2, 4, 8, 16, 32]);
103/// ```
104#[inline]
105#[stable(feature = "array_from_fn", since = "1.63.0")]
106pub fn from_fn<T, const N: usize, F>(f: F) -> [T; N]
107where
108 F: FnMut(usize) -> T,
109{
110 try_from_fn(NeverShortCircuit::wrap_mut_1(f)).0
111}
112
113/// Creates an array `[T; N]` where each fallible array element `T` is returned by the `cb` call.
114/// Unlike [`from_fn`], where the element creation can't fail, this version will return an error
115/// if any element creation was unsuccessful.
116///
117/// The return type of this function depends on the return type of the closure.
118/// If you return `Result<T, E>` from the closure, you'll get a `Result<[T; N], E>`.
119/// If you return `Option<T>` from the closure, you'll get an `Option<[T; N]>`.
120///
121/// # Arguments
122///
123/// * `cb`: Callback where the passed argument is the current array index.
124///
125/// # Example
126///
127/// ```rust
128/// #![feature(array_try_from_fn)]
129///
130/// let array: Result<[u8; 5], _> = std::array::try_from_fn(|i| i.try_into());
131/// assert_eq!(array, Ok([0, 1, 2, 3, 4]));
132///
133/// let array: Result<[i8; 200], _> = std::array::try_from_fn(|i| i.try_into());
134/// assert!(array.is_err());
135///
136/// let array: Option<[_; 4]> = std::array::try_from_fn(|i| i.checked_add(100));
137/// assert_eq!(array, Some([100, 101, 102, 103]));
138///
139/// let array: Option<[_; 4]> = std::array::try_from_fn(|i| i.checked_sub(100));
140/// assert_eq!(array, None);
141/// ```
142#[inline]
143#[unstable(feature = "array_try_from_fn", issue = "89379")]
144pub fn try_from_fn<R, const N: usize, F>(cb: F) -> ChangeOutputType<R, [R::Output; N]>
145where
146 F: FnMut(usize) -> R,
147 R: Try,
148 R::Residual: Residual<[R::Output; N]>,
149{
150 let mut array = [const { MaybeUninit::uninit() }; N];
151 match try_from_fn_erased(&mut array, cb) {
152 ControlFlow::Break(r) => FromResidual::from_residual(r),
153 ControlFlow::Continue(()) => {
154 // SAFETY: All elements of the array were populated.
155 try { unsafe { MaybeUninit::array_assume_init(array) } }
156 }
157 }
158}
159
160/// Converts a reference to `T` into a reference to an array of length 1 (without copying).
161#[stable(feature = "array_from_ref", since = "1.53.0")]
162#[rustc_const_stable(feature = "const_array_from_ref_shared", since = "1.63.0")]
163pub const fn from_ref<T>(s: &T) -> &[T; 1] {
164 // SAFETY: Converting `&T` to `&[T; 1]` is sound.
165 unsafe { &*(s as *const T).cast::<[T; 1]>() }
166}
167
168/// Converts a mutable reference to `T` into a mutable reference to an array of length 1 (without copying).
169#[stable(feature = "array_from_ref", since = "1.53.0")]
170#[rustc_const_stable(feature = "const_array_from_ref", since = "1.83.0")]
171pub const fn from_mut<T>(s: &mut T) -> &mut [T; 1] {
172 // SAFETY: Converting `&mut T` to `&mut [T; 1]` is sound.
173 unsafe { &mut *(s as *mut T).cast::<[T; 1]>() }
174}
175
176/// The error type returned when a conversion from a slice to an array fails.
177#[stable(feature = "try_from", since = "1.34.0")]
178#[derive(Debug, Copy, Clone)]
179pub struct TryFromSliceError(());
180
181#[stable(feature = "core_array", since = "1.35.0")]
182impl fmt::Display for TryFromSliceError {
183 #[inline]
184 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
185 "could not convert slice to array".fmt(f)
186 }
187}
188
189#[stable(feature = "try_from", since = "1.34.0")]
190impl Error for TryFromSliceError {}
191
192#[stable(feature = "try_from_slice_error", since = "1.36.0")]
193#[rustc_const_unstable(feature = "const_try", issue = "74935")]
194impl const From<Infallible> for TryFromSliceError {
195 fn from(x: Infallible) -> TryFromSliceError {
196 match x {}
197 }
198}
199
200#[stable(feature = "rust1", since = "1.0.0")]
201impl<T, const N: usize> AsRef<[T]> for [T; N] {
202 #[inline]
203 fn as_ref(&self) -> &[T] {
204 &self[..]
205 }
206}
207
208#[stable(feature = "rust1", since = "1.0.0")]
209impl<T, const N: usize> AsMut<[T]> for [T; N] {
210 #[inline]
211 fn as_mut(&mut self) -> &mut [T] {
212 &mut self[..]
213 }
214}
215
216#[stable(feature = "array_borrow", since = "1.4.0")]
217impl<T, const N: usize> Borrow<[T]> for [T; N] {
218 fn borrow(&self) -> &[T] {
219 self
220 }
221}
222
223#[stable(feature = "array_borrow", since = "1.4.0")]
224impl<T, const N: usize> BorrowMut<[T]> for [T; N] {
225 fn borrow_mut(&mut self) -> &mut [T] {
226 self
227 }
228}
229
230/// Tries to create an array `[T; N]` by copying from a slice `&[T]`.
231/// Succeeds if `slice.len() == N`.
232///
233/// ```
234/// let bytes: [u8; 3] = [1, 0, 2];
235///
236/// let bytes_head: [u8; 2] = <[u8; 2]>::try_from(&bytes[0..2]).unwrap();
237/// assert_eq!(1, u16::from_le_bytes(bytes_head));
238///
239/// let bytes_tail: [u8; 2] = bytes[1..3].try_into().unwrap();
240/// assert_eq!(512, u16::from_le_bytes(bytes_tail));
241/// ```
242#[stable(feature = "try_from", since = "1.34.0")]
243impl<T, const N: usize> TryFrom<&[T]> for [T; N]
244where
245 T: Copy,
246{
247 type Error = TryFromSliceError;
248
249 #[inline]
250 fn try_from(slice: &[T]) -> Result<[T; N], TryFromSliceError> {
251 <&Self>::try_from(slice).copied()
252 }
253}
254
255/// Tries to create an array `[T; N]` by copying from a mutable slice `&mut [T]`.
256/// Succeeds if `slice.len() == N`.
257///
258/// ```
259/// let mut bytes: [u8; 3] = [1, 0, 2];
260///
261/// let bytes_head: [u8; 2] = <[u8; 2]>::try_from(&mut bytes[0..2]).unwrap();
262/// assert_eq!(1, u16::from_le_bytes(bytes_head));
263///
264/// let bytes_tail: [u8; 2] = (&mut bytes[1..3]).try_into().unwrap();
265/// assert_eq!(512, u16::from_le_bytes(bytes_tail));
266/// ```
267#[stable(feature = "try_from_mut_slice_to_array", since = "1.59.0")]
268impl<T, const N: usize> TryFrom<&mut [T]> for [T; N]
269where
270 T: Copy,
271{
272 type Error = TryFromSliceError;
273
274 #[inline]
275 fn try_from(slice: &mut [T]) -> Result<[T; N], TryFromSliceError> {
276 <Self>::try_from(&*slice)
277 }
278}
279
280/// Tries to create an array ref `&[T; N]` from a slice ref `&[T]`. Succeeds if
281/// `slice.len() == N`.
282///
283/// ```
284/// let bytes: [u8; 3] = [1, 0, 2];
285///
286/// let bytes_head: &[u8; 2] = <&[u8; 2]>::try_from(&bytes[0..2]).unwrap();
287/// assert_eq!(1, u16::from_le_bytes(*bytes_head));
288///
289/// let bytes_tail: &[u8; 2] = bytes[1..3].try_into().unwrap();
290/// assert_eq!(512, u16::from_le_bytes(*bytes_tail));
291/// ```
292#[stable(feature = "try_from", since = "1.34.0")]
293impl<'a, T, const N: usize> TryFrom<&'a [T]> for &'a [T; N] {
294 type Error = TryFromSliceError;
295
296 #[inline]
297 fn try_from(slice: &'a [T]) -> Result<&'a [T; N], TryFromSliceError> {
298 slice.as_array().ok_or(TryFromSliceError(()))
299 }
300}
301
302/// Tries to create a mutable array ref `&mut [T; N]` from a mutable slice ref
303/// `&mut [T]`. Succeeds if `slice.len() == N`.
304///
305/// ```
306/// let mut bytes: [u8; 3] = [1, 0, 2];
307///
308/// let bytes_head: &mut [u8; 2] = <&mut [u8; 2]>::try_from(&mut bytes[0..2]).unwrap();
309/// assert_eq!(1, u16::from_le_bytes(*bytes_head));
310///
311/// let bytes_tail: &mut [u8; 2] = (&mut bytes[1..3]).try_into().unwrap();
312/// assert_eq!(512, u16::from_le_bytes(*bytes_tail));
313/// ```
314#[stable(feature = "try_from", since = "1.34.0")]
315impl<'a, T, const N: usize> TryFrom<&'a mut [T]> for &'a mut [T; N] {
316 type Error = TryFromSliceError;
317
318 #[inline]
319 fn try_from(slice: &'a mut [T]) -> Result<&'a mut [T; N], TryFromSliceError> {
320 slice.as_mut_array().ok_or(TryFromSliceError(()))
321 }
322}
323
324/// The hash of an array is the same as that of the corresponding slice,
325/// as required by the `Borrow` implementation.
326///
327/// ```
328/// use std::hash::BuildHasher;
329///
330/// let b = std::hash::RandomState::new();
331/// let a: [u8; 3] = [0xa8, 0x3c, 0x09];
332/// let s: &[u8] = &[0xa8, 0x3c, 0x09];
333/// assert_eq!(b.hash_one(a), b.hash_one(s));
334/// ```
335#[stable(feature = "rust1", since = "1.0.0")]
336impl<T: Hash, const N: usize> Hash for [T; N] {
337 fn hash<H: hash::Hasher>(&self, state: &mut H) {
338 Hash::hash(&self[..], state)
339 }
340}
341
342#[stable(feature = "rust1", since = "1.0.0")]
343impl<T: fmt::Debug, const N: usize> fmt::Debug for [T; N] {
344 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
345 fmt::Debug::fmt(&&self[..], f)
346 }
347}
348
349#[stable(feature = "rust1", since = "1.0.0")]
350impl<'a, T, const N: usize> IntoIterator for &'a [T; N] {
351 type Item = &'a T;
352 type IntoIter = Iter<'a, T>;
353
354 fn into_iter(self) -> Iter<'a, T> {
355 self.iter()
356 }
357}
358
359#[stable(feature = "rust1", since = "1.0.0")]
360impl<'a, T, const N: usize> IntoIterator for &'a mut [T; N] {
361 type Item = &'a mut T;
362 type IntoIter = IterMut<'a, T>;
363
364 fn into_iter(self) -> IterMut<'a, T> {
365 self.iter_mut()
366 }
367}
368
369#[stable(feature = "index_trait_on_arrays", since = "1.50.0")]
370#[rustc_const_unstable(feature = "const_index", issue = "143775")]
371impl<T, I, const N: usize> const Index<I> for [T; N]
372where
373 [T]: [const] Index<I>,
374{
375 type Output = <[T] as Index<I>>::Output;
376
377 #[inline]
378 fn index(&self, index: I) -> &Self::Output {
379 Index::index(self as &[T], index)
380 }
381}
382
383#[stable(feature = "index_trait_on_arrays", since = "1.50.0")]
384#[rustc_const_unstable(feature = "const_index", issue = "143775")]
385impl<T, I, const N: usize> const IndexMut<I> for [T; N]
386where
387 [T]: [const] IndexMut<I>,
388{
389 #[inline]
390 fn index_mut(&mut self, index: I) -> &mut Self::Output {
391 IndexMut::index_mut(self as &mut [T], index)
392 }
393}
394
395/// Implements comparison of arrays [lexicographically](Ord#lexicographical-comparison).
396#[stable(feature = "rust1", since = "1.0.0")]
397impl<T: PartialOrd, const N: usize> PartialOrd for [T; N] {
398 #[inline]
399 fn partial_cmp(&self, other: &[T; N]) -> Option<Ordering> {
400 PartialOrd::partial_cmp(&&self[..], &&other[..])
401 }
402 #[inline]
403 fn lt(&self, other: &[T; N]) -> bool {
404 PartialOrd::lt(&&self[..], &&other[..])
405 }
406 #[inline]
407 fn le(&self, other: &[T; N]) -> bool {
408 PartialOrd::le(&&self[..], &&other[..])
409 }
410 #[inline]
411 fn ge(&self, other: &[T; N]) -> bool {
412 PartialOrd::ge(&&self[..], &&other[..])
413 }
414 #[inline]
415 fn gt(&self, other: &[T; N]) -> bool {
416 PartialOrd::gt(&&self[..], &&other[..])
417 }
418}
419
420/// Implements comparison of arrays [lexicographically](Ord#lexicographical-comparison).
421#[stable(feature = "rust1", since = "1.0.0")]
422impl<T: Ord, const N: usize> Ord for [T; N] {
423 #[inline]
424 fn cmp(&self, other: &[T; N]) -> Ordering {
425 Ord::cmp(&&self[..], &&other[..])
426 }
427}
428
429#[stable(feature = "copy_clone_array_lib", since = "1.58.0")]
430impl<T: Copy, const N: usize> Copy for [T; N] {}
431
432#[stable(feature = "copy_clone_array_lib", since = "1.58.0")]
433impl<T: Clone, const N: usize> Clone for [T; N] {
434 #[inline]
435 fn clone(&self) -> Self {
436 SpecArrayClone::clone(self)
437 }
438
439 #[inline]
440 fn clone_from(&mut self, other: &Self) {
441 self.clone_from_slice(other);
442 }
443}
444
445trait SpecArrayClone: Clone {
446 fn clone<const N: usize>(array: &[Self; N]) -> [Self; N];
447}
448
449impl<T: Clone> SpecArrayClone for T {
450 #[inline]
451 default fn clone<const N: usize>(array: &[T; N]) -> [T; N] {
452 from_trusted_iterator(array.iter().cloned())
453 }
454}
455
456impl<T: Copy> SpecArrayClone for T {
457 #[inline]
458 fn clone<const N: usize>(array: &[T; N]) -> [T; N] {
459 *array
460 }
461}
462
463// The Default impls cannot be done with const generics because `[T; 0]` doesn't
464// require Default to be implemented, and having different impl blocks for
465// different numbers isn't supported yet.
466
467macro_rules! array_impl_default {
468 {$n:expr, $t:ident $($ts:ident)*} => {
469 #[stable(since = "1.4.0", feature = "array_default")]
470 impl<T> Default for [T; $n] where T: Default {
471 fn default() -> [T; $n] {
472 [$t::default(), $($ts::default()),*]
473 }
474 }
475 array_impl_default!{($n - 1), $($ts)*}
476 };
477 {$n:expr,} => {
478 #[stable(since = "1.4.0", feature = "array_default")]
479 impl<T> Default for [T; $n] {
480 fn default() -> [T; $n] { [] }
481 }
482 };
483}
484
485array_impl_default! {32, T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T}
486
487impl<T, const N: usize> [T; N] {
488 /// Returns an array of the same size as `self`, with function `f` applied to each element
489 /// in order.
490 ///
491 /// If you don't necessarily need a new fixed-size array, consider using
492 /// [`Iterator::map`] instead.
493 ///
494 ///
495 /// # Note on performance and stack usage
496 ///
497 /// Unfortunately, usages of this method are currently not always optimized
498 /// as well as they could be. This mainly concerns large arrays, as mapping
499 /// over small arrays seem to be optimized just fine. Also note that in
500 /// debug mode (i.e. without any optimizations), this method can use a lot
501 /// of stack space (a few times the size of the array or more).
502 ///
503 /// Therefore, in performance-critical code, try to avoid using this method
504 /// on large arrays or check the emitted code. Also try to avoid chained
505 /// maps (e.g. `arr.map(...).map(...)`).
506 ///
507 /// In many cases, you can instead use [`Iterator::map`] by calling `.iter()`
508 /// or `.into_iter()` on your array. `[T; N]::map` is only necessary if you
509 /// really need a new array of the same size as the result. Rust's lazy
510 /// iterators tend to get optimized very well.
511 ///
512 ///
513 /// # Examples
514 ///
515 /// ```
516 /// let x = [1, 2, 3];
517 /// let y = x.map(|v| v + 1);
518 /// assert_eq!(y, [2, 3, 4]);
519 ///
520 /// let x = [1, 2, 3];
521 /// let mut temp = 0;
522 /// let y = x.map(|v| { temp += 1; v * temp });
523 /// assert_eq!(y, [1, 4, 9]);
524 ///
525 /// let x = ["Ferris", "Bueller's", "Day", "Off"];
526 /// let y = x.map(|v| v.len());
527 /// assert_eq!(y, [6, 9, 3, 3]);
528 /// ```
529 #[must_use]
530 #[stable(feature = "array_map", since = "1.55.0")]
531 pub fn map<F, U>(self, f: F) -> [U; N]
532 where
533 F: FnMut(T) -> U,
534 {
535 self.try_map(NeverShortCircuit::wrap_mut_1(f)).0
536 }
537
538 /// A fallible function `f` applied to each element on array `self` in order to
539 /// return an array the same size as `self` or the first error encountered.
540 ///
541 /// The return type of this function depends on the return type of the closure.
542 /// If you return `Result<T, E>` from the closure, you'll get a `Result<[T; N], E>`.
543 /// If you return `Option<T>` from the closure, you'll get an `Option<[T; N]>`.
544 ///
545 /// # Examples
546 ///
547 /// ```
548 /// #![feature(array_try_map)]
549 ///
550 /// let a = ["1", "2", "3"];
551 /// let b = a.try_map(|v| v.parse::<u32>()).unwrap().map(|v| v + 1);
552 /// assert_eq!(b, [2, 3, 4]);
553 ///
554 /// let a = ["1", "2a", "3"];
555 /// let b = a.try_map(|v| v.parse::<u32>());
556 /// assert!(b.is_err());
557 ///
558 /// use std::num::NonZero;
559 ///
560 /// let z = [1, 2, 0, 3, 4];
561 /// assert_eq!(z.try_map(NonZero::new), None);
562 ///
563 /// let a = [1, 2, 3];
564 /// let b = a.try_map(NonZero::new);
565 /// let c = b.map(|x| x.map(NonZero::get));
566 /// assert_eq!(c, Some(a));
567 /// ```
568 #[unstable(feature = "array_try_map", issue = "79711")]
569 pub fn try_map<R>(self, f: impl FnMut(T) -> R) -> ChangeOutputType<R, [R::Output; N]>
570 where
571 R: Try<Residual: Residual<[R::Output; N]>>,
572 {
573 drain_array_with(self, |iter| try_from_trusted_iterator(iter.map(f)))
574 }
575
576 /// Returns a slice containing the entire array. Equivalent to `&s[..]`.
577 #[stable(feature = "array_as_slice", since = "1.57.0")]
578 #[rustc_const_stable(feature = "array_as_slice", since = "1.57.0")]
579 pub const fn as_slice(&self) -> &[T] {
580 self
581 }
582
583 /// Returns a mutable slice containing the entire array. Equivalent to
584 /// `&mut s[..]`.
585 #[stable(feature = "array_as_slice", since = "1.57.0")]
586 #[rustc_const_stable(feature = "const_array_as_mut_slice", since = "1.89.0")]
587 pub const fn as_mut_slice(&mut self) -> &mut [T] {
588 self
589 }
590
591 /// Borrows each element and returns an array of references with the same
592 /// size as `self`.
593 ///
594 ///
595 /// # Example
596 ///
597 /// ```
598 /// let floats = [3.1, 2.7, -1.0];
599 /// let float_refs: [&f64; 3] = floats.each_ref();
600 /// assert_eq!(float_refs, [&3.1, &2.7, &-1.0]);
601 /// ```
602 ///
603 /// This method is particularly useful if combined with other methods, like
604 /// [`map`](#method.map). This way, you can avoid moving the original
605 /// array if its elements are not [`Copy`].
606 ///
607 /// ```
608 /// let strings = ["Ferris".to_string(), "♥".to_string(), "Rust".to_string()];
609 /// let is_ascii = strings.each_ref().map(|s| s.is_ascii());
610 /// assert_eq!(is_ascii, [true, false, true]);
611 ///
612 /// // We can still access the original array: it has not been moved.
613 /// assert_eq!(strings.len(), 3);
614 /// ```
615 #[stable(feature = "array_methods", since = "1.77.0")]
616 #[rustc_const_stable(feature = "const_array_each_ref", since = "CURRENT_RUSTC_VERSION")]
617 pub const fn each_ref(&self) -> [&T; N] {
618 let mut buf = [null::<T>(); N];
619
620 // FIXME(const_trait_impl): We would like to simply use iterators for this (as in the original implementation), but this is not allowed in constant expressions.
621 let mut i = 0;
622 while i < N {
623 buf[i] = &raw const self[i];
624
625 i += 1;
626 }
627
628 // SAFETY: `*const T` has the same layout as `&T`, and we've also initialised each pointer as a valid reference.
629 unsafe { transmute_unchecked(buf) }
630 }
631
632 /// Borrows each element mutably and returns an array of mutable references
633 /// with the same size as `self`.
634 ///
635 ///
636 /// # Example
637 ///
638 /// ```
639 ///
640 /// let mut floats = [3.1, 2.7, -1.0];
641 /// let float_refs: [&mut f64; 3] = floats.each_mut();
642 /// *float_refs[0] = 0.0;
643 /// assert_eq!(float_refs, [&mut 0.0, &mut 2.7, &mut -1.0]);
644 /// assert_eq!(floats, [0.0, 2.7, -1.0]);
645 /// ```
646 #[stable(feature = "array_methods", since = "1.77.0")]
647 #[rustc_const_stable(feature = "const_array_each_ref", since = "CURRENT_RUSTC_VERSION")]
648 pub const fn each_mut(&mut self) -> [&mut T; N] {
649 let mut buf = [null_mut::<T>(); N];
650
651 // FIXME(const_trait_impl): We would like to simply use iterators for this (as in the original implementation), but this is not allowed in constant expressions.
652 let mut i = 0;
653 while i < N {
654 buf[i] = &raw mut self[i];
655
656 i += 1;
657 }
658
659 // SAFETY: `*mut T` has the same layout as `&mut T`, and we've also initialised each pointer as a valid reference.
660 unsafe { transmute_unchecked(buf) }
661 }
662
663 /// Divides one array reference into two at an index.
664 ///
665 /// The first will contain all indices from `[0, M)` (excluding
666 /// the index `M` itself) and the second will contain all
667 /// indices from `[M, N)` (excluding the index `N` itself).
668 ///
669 /// # Panics
670 ///
671 /// Panics if `M > N`.
672 ///
673 /// # Examples
674 ///
675 /// ```
676 /// #![feature(split_array)]
677 ///
678 /// let v = [1, 2, 3, 4, 5, 6];
679 ///
680 /// {
681 /// let (left, right) = v.split_array_ref::<0>();
682 /// assert_eq!(left, &[]);
683 /// assert_eq!(right, &[1, 2, 3, 4, 5, 6]);
684 /// }
685 ///
686 /// {
687 /// let (left, right) = v.split_array_ref::<2>();
688 /// assert_eq!(left, &[1, 2]);
689 /// assert_eq!(right, &[3, 4, 5, 6]);
690 /// }
691 ///
692 /// {
693 /// let (left, right) = v.split_array_ref::<6>();
694 /// assert_eq!(left, &[1, 2, 3, 4, 5, 6]);
695 /// assert_eq!(right, &[]);
696 /// }
697 /// ```
698 #[unstable(
699 feature = "split_array",
700 reason = "return type should have array as 2nd element",
701 issue = "90091"
702 )]
703 #[inline]
704 pub fn split_array_ref<const M: usize>(&self) -> (&[T; M], &[T]) {
705 self.split_first_chunk::<M>().unwrap()
706 }
707
708 /// Divides one mutable array reference into two at an index.
709 ///
710 /// The first will contain all indices from `[0, M)` (excluding
711 /// the index `M` itself) and the second will contain all
712 /// indices from `[M, N)` (excluding the index `N` itself).
713 ///
714 /// # Panics
715 ///
716 /// Panics if `M > N`.
717 ///
718 /// # Examples
719 ///
720 /// ```
721 /// #![feature(split_array)]
722 ///
723 /// let mut v = [1, 0, 3, 0, 5, 6];
724 /// let (left, right) = v.split_array_mut::<2>();
725 /// assert_eq!(left, &mut [1, 0][..]);
726 /// assert_eq!(right, &mut [3, 0, 5, 6]);
727 /// left[1] = 2;
728 /// right[1] = 4;
729 /// assert_eq!(v, [1, 2, 3, 4, 5, 6]);
730 /// ```
731 #[unstable(
732 feature = "split_array",
733 reason = "return type should have array as 2nd element",
734 issue = "90091"
735 )]
736 #[inline]
737 pub fn split_array_mut<const M: usize>(&mut self) -> (&mut [T; M], &mut [T]) {
738 self.split_first_chunk_mut::<M>().unwrap()
739 }
740
741 /// Divides one array reference into two at an index from the end.
742 ///
743 /// The first will contain all indices from `[0, N - M)` (excluding
744 /// the index `N - M` itself) and the second will contain all
745 /// indices from `[N - M, N)` (excluding the index `N` itself).
746 ///
747 /// # Panics
748 ///
749 /// Panics if `M > N`.
750 ///
751 /// # Examples
752 ///
753 /// ```
754 /// #![feature(split_array)]
755 ///
756 /// let v = [1, 2, 3, 4, 5, 6];
757 ///
758 /// {
759 /// let (left, right) = v.rsplit_array_ref::<0>();
760 /// assert_eq!(left, &[1, 2, 3, 4, 5, 6]);
761 /// assert_eq!(right, &[]);
762 /// }
763 ///
764 /// {
765 /// let (left, right) = v.rsplit_array_ref::<2>();
766 /// assert_eq!(left, &[1, 2, 3, 4]);
767 /// assert_eq!(right, &[5, 6]);
768 /// }
769 ///
770 /// {
771 /// let (left, right) = v.rsplit_array_ref::<6>();
772 /// assert_eq!(left, &[]);
773 /// assert_eq!(right, &[1, 2, 3, 4, 5, 6]);
774 /// }
775 /// ```
776 #[unstable(
777 feature = "split_array",
778 reason = "return type should have array as 2nd element",
779 issue = "90091"
780 )]
781 #[inline]
782 pub fn rsplit_array_ref<const M: usize>(&self) -> (&[T], &[T; M]) {
783 self.split_last_chunk::<M>().unwrap()
784 }
785
786 /// Divides one mutable array reference into two at an index from the end.
787 ///
788 /// The first will contain all indices from `[0, N - M)` (excluding
789 /// the index `N - M` itself) and the second will contain all
790 /// indices from `[N - M, N)` (excluding the index `N` itself).
791 ///
792 /// # Panics
793 ///
794 /// Panics if `M > N`.
795 ///
796 /// # Examples
797 ///
798 /// ```
799 /// #![feature(split_array)]
800 ///
801 /// let mut v = [1, 0, 3, 0, 5, 6];
802 /// let (left, right) = v.rsplit_array_mut::<4>();
803 /// assert_eq!(left, &mut [1, 0]);
804 /// assert_eq!(right, &mut [3, 0, 5, 6][..]);
805 /// left[1] = 2;
806 /// right[1] = 4;
807 /// assert_eq!(v, [1, 2, 3, 4, 5, 6]);
808 /// ```
809 #[unstable(
810 feature = "split_array",
811 reason = "return type should have array as 2nd element",
812 issue = "90091"
813 )]
814 #[inline]
815 pub fn rsplit_array_mut<const M: usize>(&mut self) -> (&mut [T], &mut [T; M]) {
816 self.split_last_chunk_mut::<M>().unwrap()
817 }
818}
819
820/// Populate an array from the first `N` elements of `iter`
821///
822/// # Panics
823///
824/// If the iterator doesn't actually have enough items.
825///
826/// By depending on `TrustedLen`, however, we can do that check up-front (where
827/// it easily optimizes away) so it doesn't impact the loop that fills the array.
828#[inline]
829fn from_trusted_iterator<T, const N: usize>(iter: impl UncheckedIterator<Item = T>) -> [T; N] {
830 try_from_trusted_iterator(iter.map(NeverShortCircuit)).0
831}
832
833#[inline]
834fn try_from_trusted_iterator<T, R, const N: usize>(
835 iter: impl UncheckedIterator<Item = R>,
836) -> ChangeOutputType<R, [T; N]>
837where
838 R: Try<Output = T>,
839 R::Residual: Residual<[T; N]>,
840{
841 assert!(iter.size_hint().0 >= N);
842 fn next<T>(mut iter: impl UncheckedIterator<Item = T>) -> impl FnMut(usize) -> T {
843 move |_| {
844 // SAFETY: We know that `from_fn` will call this at most N times,
845 // and we checked to ensure that we have at least that many items.
846 unsafe { iter.next_unchecked() }
847 }
848 }
849
850 try_from_fn(next(iter))
851}
852
853/// Version of [`try_from_fn`] using a passed-in slice in order to avoid
854/// needing to monomorphize for every array length.
855///
856/// This takes a generator rather than an iterator so that *at the type level*
857/// it never needs to worry about running out of items. When combined with
858/// an infallible `Try` type, that means the loop canonicalizes easily, allowing
859/// it to optimize well.
860///
861/// It would be *possible* to unify this and [`iter_next_chunk_erased`] into one
862/// function that does the union of both things, but last time it was that way
863/// it resulted in poor codegen from the "are there enough source items?" checks
864/// not optimizing away. So if you give it a shot, make sure to watch what
865/// happens in the codegen tests.
866#[inline]
867fn try_from_fn_erased<T, R>(
868 buffer: &mut [MaybeUninit<T>],
869 mut generator: impl FnMut(usize) -> R,
870) -> ControlFlow<R::Residual>
871where
872 R: Try<Output = T>,
873{
874 let mut guard = Guard { array_mut: buffer, initialized: 0 };
875
876 while guard.initialized < guard.array_mut.len() {
877 let item = generator(guard.initialized).branch()?;
878
879 // SAFETY: The loop condition ensures we have space to push the item
880 unsafe { guard.push_unchecked(item) };
881 }
882
883 mem::forget(guard);
884 ControlFlow::Continue(())
885}
886
887/// Panic guard for incremental initialization of arrays.
888///
889/// Disarm the guard with `mem::forget` once the array has been initialized.
890///
891/// # Safety
892///
893/// All write accesses to this structure are unsafe and must maintain a correct
894/// count of `initialized` elements.
895///
896/// To minimize indirection fields are still pub but callers should at least use
897/// `push_unchecked` to signal that something unsafe is going on.
898struct Guard<'a, T> {
899 /// The array to be initialized.
900 pub array_mut: &'a mut [MaybeUninit<T>],
901 /// The number of items that have been initialized so far.
902 pub initialized: usize,
903}
904
905impl<T> Guard<'_, T> {
906 /// Adds an item to the array and updates the initialized item counter.
907 ///
908 /// # Safety
909 ///
910 /// No more than N elements must be initialized.
911 #[inline]
912 pub(crate) unsafe fn push_unchecked(&mut self, item: T) {
913 // SAFETY: If `initialized` was correct before and the caller does not
914 // invoke this method more than N times then writes will be in-bounds
915 // and slots will not be initialized more than once.
916 unsafe {
917 self.array_mut.get_unchecked_mut(self.initialized).write(item);
918 self.initialized = self.initialized.unchecked_add(1);
919 }
920 }
921}
922
923impl<T> Drop for Guard<'_, T> {
924 #[inline]
925 fn drop(&mut self) {
926 debug_assert!(self.initialized <= self.array_mut.len());
927
928 // SAFETY: this slice will contain only initialized objects.
929 unsafe {
930 self.array_mut.get_unchecked_mut(..self.initialized).assume_init_drop();
931 }
932 }
933}
934
935/// Pulls `N` items from `iter` and returns them as an array. If the iterator
936/// yields fewer than `N` items, `Err` is returned containing an iterator over
937/// the already yielded items.
938///
939/// Since the iterator is passed as a mutable reference and this function calls
940/// `next` at most `N` times, the iterator can still be used afterwards to
941/// retrieve the remaining items.
942///
943/// If `iter.next()` panicks, all items already yielded by the iterator are
944/// dropped.
945///
946/// Used for [`Iterator::next_chunk`].
947#[inline]
948pub(crate) fn iter_next_chunk<T, const N: usize>(
949 iter: &mut impl Iterator<Item = T>,
950) -> Result<[T; N], IntoIter<T, N>> {
951 let mut array = [const { MaybeUninit::uninit() }; N];
952 let r = iter_next_chunk_erased(&mut array, iter);
953 match r {
954 Ok(()) => {
955 // SAFETY: All elements of `array` were populated.
956 Ok(unsafe { MaybeUninit::array_assume_init(array) })
957 }
958 Err(initialized) => {
959 // SAFETY: Only the first `initialized` elements were populated
960 Err(unsafe { IntoIter::new_unchecked(array, 0..initialized) })
961 }
962 }
963}
964
965/// Version of [`iter_next_chunk`] using a passed-in slice in order to avoid
966/// needing to monomorphize for every array length.
967///
968/// Unfortunately this loop has two exit conditions, the buffer filling up
969/// or the iterator running out of items, making it tend to optimize poorly.
970#[inline]
971fn iter_next_chunk_erased<T>(
972 buffer: &mut [MaybeUninit<T>],
973 iter: &mut impl Iterator<Item = T>,
974) -> Result<(), usize> {
975 let mut guard = Guard { array_mut: buffer, initialized: 0 };
976 while guard.initialized < guard.array_mut.len() {
977 let Some(item) = iter.next() else {
978 // Unlike `try_from_fn_erased`, we want to keep the partial results,
979 // so we need to defuse the guard instead of using `?`.
980 let initialized = guard.initialized;
981 mem::forget(guard);
982 return Err(initialized);
983 };
984
985 // SAFETY: The loop condition ensures we have space to push the item
986 unsafe { guard.push_unchecked(item) };
987 }
988
989 mem::forget(guard);
990 Ok(())
991}