Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

array docs - advertise how to get array from slice #101672

Merged
merged 1 commit into from
Sep 17, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
array docs - advertise how to get array from slice
On my first Rust project, I spent more time than I care to admit
figuring out how to efficiently get an array from a slice. Update the
array documentation to explain this a bit more clearly.

(As a side note, it's a bit unfortunate that get-array-from-slice is
only available via trait since that means it can't be used from const
functions yet.)
Doug Cook (WINDOWS) committed Sep 11, 2022
commit 705a7667c5e14c7155145041ca2abe45c2863ea7
48 changes: 48 additions & 0 deletions library/core/src/array/mod.rs
Original file line number Diff line number Diff line change
@@ -184,6 +184,18 @@ impl<T, const N: usize> const BorrowMut<[T]> for [T; N] {
}
}

/// Tries to create an array `[T; N]` by copying from a slice `&[T]`. Succeeds if
/// `slice.len() == N`.
///
/// ```
/// let bytes: [u8; 3] = [1, 0, 2];
///
/// let bytes_head: [u8; 2] = <[u8; 2]>::try_from(&bytes[0..2]).unwrap();
/// assert_eq!(1, u16::from_le_bytes(bytes_head));
///
/// let bytes_tail: [u8; 2] = bytes[1..3].try_into().unwrap();
/// assert_eq!(512, u16::from_le_bytes(bytes_tail));
/// ```
#[stable(feature = "try_from", since = "1.34.0")]
impl<T, const N: usize> TryFrom<&[T]> for [T; N]
where
@@ -196,6 +208,18 @@ where
}
}

/// Tries to create an array `[T; N]` by copying from a mutable slice `&mut [T]`.
/// Succeeds if `slice.len() == N`.
///
/// ```
/// let mut bytes: [u8; 3] = [1, 0, 2];
///
/// let bytes_head: [u8; 2] = <[u8; 2]>::try_from(&mut bytes[0..2]).unwrap();
/// assert_eq!(1, u16::from_le_bytes(bytes_head));
///
/// let bytes_tail: [u8; 2] = (&mut bytes[1..3]).try_into().unwrap();
/// assert_eq!(512, u16::from_le_bytes(bytes_tail));
/// ```
#[stable(feature = "try_from_mut_slice_to_array", since = "1.59.0")]
impl<T, const N: usize> TryFrom<&mut [T]> for [T; N]
where
@@ -208,6 +232,18 @@ where
}
}

/// Tries to create an array ref `&[T; N]` from a slice ref `&[T]`. Succeeds if
/// `slice.len() == N`.
///
/// ```
/// let bytes: [u8; 3] = [1, 0, 2];
///
/// let bytes_head: &[u8; 2] = <&[u8; 2]>::try_from(&bytes[0..2]).unwrap();
/// assert_eq!(1, u16::from_le_bytes(*bytes_head));
///
/// let bytes_tail: &[u8; 2] = bytes[1..3].try_into().unwrap();
/// assert_eq!(512, u16::from_le_bytes(*bytes_tail));
/// ```
#[stable(feature = "try_from", since = "1.34.0")]
impl<'a, T, const N: usize> TryFrom<&'a [T]> for &'a [T; N] {
type Error = TryFromSliceError;
@@ -223,6 +259,18 @@ impl<'a, T, const N: usize> TryFrom<&'a [T]> for &'a [T; N] {
}
}

/// Tries to create a mutable array ref `&mut [T; N]` from a mutable slice ref
/// `&mut [T]`. Succeeds if `slice.len() == N`.
///
/// ```
/// let mut bytes: [u8; 3] = [1, 0, 2];
///
/// let bytes_head: &mut [u8; 2] = <&mut [u8; 2]>::try_from(&mut bytes[0..2]).unwrap();
/// assert_eq!(1, u16::from_le_bytes(*bytes_head));
///
/// let bytes_tail: &mut [u8; 2] = (&mut bytes[1..3]).try_into().unwrap();
/// assert_eq!(512, u16::from_le_bytes(*bytes_tail));
/// ```
#[stable(feature = "try_from", since = "1.34.0")]
impl<'a, T, const N: usize> TryFrom<&'a mut [T]> for &'a mut [T; N] {
type Error = TryFromSliceError;
23 changes: 22 additions & 1 deletion library/core/src/primitive_docs.rs
Original file line number Diff line number Diff line change
@@ -611,7 +611,19 @@ mod prim_pointer {}
///
/// Arrays coerce to [slices (`[T]`)][slice], so a slice method may be called on
/// an array. Indeed, this provides most of the API for working with arrays.
/// Slices have a dynamic size and do not coerce to arrays.
///
/// Slices have a dynamic size and do not coerce to arrays. Instead, use
/// `slice.try_into().unwrap()` or `<ArrayType>::try_from(slice).unwrap()`.
///
/// Array's `try_from(slice)` implementations (and the corresponding `slice.try_into()`
/// array implementations) succeed if the input slice length is the same as the result
/// array length. They optimize especially well when the optimizer can easily determine
/// the slice length, e.g. `<[u8; 4]>::try_from(&slice[4..8]).unwrap()`. Array implements
/// [TryFrom](crate::convert::TryFrom) returning:
///
/// - `[T; N]` copies from the slice's elements
/// - `&[T; N]` references the original slice's elements
/// - `&mut [T; N]` references the original slice's elements
///
/// You can move elements out of an array with a [slice pattern]. If you want
/// one element, see [`mem::replace`].
@@ -640,6 +652,15 @@ mod prim_pointer {}
/// for x in &array { }
/// ```
///
/// You can use `<ArrayType>::try_from(slice)` or `slice.try_into()` to get an array from
/// a slice:
///
/// ```
/// let bytes: [u8; 3] = [1, 0, 2];
/// assert_eq!(1, u16::from_le_bytes(<[u8; 2]>::try_from(&bytes[0..2]).unwrap()));
/// assert_eq!(512, u16::from_le_bytes(bytes[1..3].try_into().unwrap()));
/// ```
///
/// You can use a [slice pattern] to move elements out of an array:
///
/// ```
23 changes: 22 additions & 1 deletion library/std/src/primitive_docs.rs
Original file line number Diff line number Diff line change
@@ -611,7 +611,19 @@ mod prim_pointer {}
///
/// Arrays coerce to [slices (`[T]`)][slice], so a slice method may be called on
/// an array. Indeed, this provides most of the API for working with arrays.
/// Slices have a dynamic size and do not coerce to arrays.
///
/// Slices have a dynamic size and do not coerce to arrays. Instead, use
/// `slice.try_into().unwrap()` or `<ArrayType>::try_from(slice).unwrap()`.
///
/// Array's `try_from(slice)` implementations (and the corresponding `slice.try_into()`
/// array implementations) succeed if the input slice length is the same as the result
/// array length. They optimize especially well when the optimizer can easily determine
/// the slice length, e.g. `<[u8; 4]>::try_from(&slice[4..8]).unwrap()`. Array implements
/// [TryFrom](crate::convert::TryFrom) returning:
///
/// - `[T; N]` copies from the slice's elements
/// - `&[T; N]` references the original slice's elements
/// - `&mut [T; N]` references the original slice's elements
///
/// You can move elements out of an array with a [slice pattern]. If you want
/// one element, see [`mem::replace`].
@@ -640,6 +652,15 @@ mod prim_pointer {}
/// for x in &array { }
/// ```
///
/// You can use `<ArrayType>::try_from(slice)` or `slice.try_into()` to get an array from
/// a slice:
///
/// ```
/// let bytes: [u8; 3] = [1, 0, 2];
/// assert_eq!(1, u16::from_le_bytes(<[u8; 2]>::try_from(&bytes[0..2]).unwrap()));
/// assert_eq!(512, u16::from_le_bytes(bytes[1..3].try_into().unwrap()));
/// ```
///
/// You can use a [slice pattern] to move elements out of an array:
///
/// ```