nordic-dev.net/bytemuck
2
0
Fork 0
mirror of https://github.com/Lokathor/bytemuck.git synced 2024-11-22 06:42:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Explicitly document that pod_read_unaligned and try_pod_read_unaligned don't panic on unallowed reads (#220)

Browse Source 
* Explicitly document that pod_read_unaligned and try_pod_read_unaligned don't panic on unallowed reads

Their names make that reasonably clear already, but it doesn't hurt to
be explicit. Also, when choosing between `*from_bytes(x)` and
`pod_read_unaligned(x)`, it's good to have a clearly documented
criterion.

* Cosmetic doc changes

Add a couple of missing links, add a missing "like" (consistent with
other similar sentences).

* Remove redundant link

The redundant link emits a warning in `cargo doc`.
This commit is contained in:
Hrvoje Nikšić 2024-01-25 01:30:59 +01:00 committed by GitHub
parent 085a5f573e
commit 8dc32b1e50
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 14 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/checked.rs
View File

@ -450,7 +450,7 @@ pub fn pod_read_unaligned<T: CheckedBitPattern>(bytes: &[u8]) -> T {
/// ///
/// ## Panics /// ## Panics
/// ///
/// * This is like [`try_cast`](try_cast), but will panic on a size mismatch. /// * This is like [`try_cast`], but will panic on a size mismatch.
#[inline] #[inline]
pub fn cast<A: NoUninit, B: CheckedBitPattern>(a: A) -> B { pub fn cast<A: NoUninit, B: CheckedBitPattern>(a: A) -> B {
match try_cast(a) { match try_cast(a) {

18
src/lib.rs
View File

@ -234,7 +234,7 @@ pub fn bytes_of_mut<T: NoUninit + AnyBitPattern>(t: &mut T) -> &mut [u8] {
/// ///
/// ## Panics /// ## Panics
/// ///
/// This is [`try_from_bytes`] but will panic on error. /// This is like [`try_from_bytes`] but will panic on error.
#[inline] #[inline]
pub fn from_bytes<T: AnyBitPattern>(s: &[u8]) -> &T { pub fn from_bytes<T: AnyBitPattern>(s: &[u8]) -> &T {
unsafe { internal::from_bytes(s) } unsafe { internal::from_bytes(s) }
@ -244,7 +244,7 @@ pub fn from_bytes<T: AnyBitPattern>(s: &[u8]) -> &T {
/// ///
/// ## Panics /// ## Panics
/// ///
/// This is [`try_from_bytes_mut`] but will panic on error. /// This is like [`try_from_bytes_mut`] but will panic on error.
#[inline] #[inline]
pub fn from_bytes_mut<T: NoUninit + AnyBitPattern>(s: &mut [u8]) -> &mut T { pub fn from_bytes_mut<T: NoUninit + AnyBitPattern>(s: &mut [u8]) -> &mut T {
unsafe { internal::from_bytes_mut(s) } unsafe { internal::from_bytes_mut(s) }
@ -252,6 +252,9 @@ pub fn from_bytes_mut<T: NoUninit + AnyBitPattern>(s: &mut [u8]) -> &mut T {
/// Reads from the bytes as if they were a `T`. /// Reads from the bytes as if they were a `T`.
/// ///
/// Unlike [`from_bytes`], the slice doesn't need to respect alignment of `T`, only sizes
/// must match.
///
/// ## Failure /// ## Failure
/// * If the `bytes` length is not equal to `size_of::<T>()`. /// * If the `bytes` length is not equal to `size_of::<T>()`.
#[inline] #[inline]
@ -263,6 +266,9 @@ pub fn try_pod_read_unaligned<T: AnyBitPattern>(
/// Reads the slice into a `T` value. /// Reads the slice into a `T` value.
/// ///
/// Unlike [`from_bytes`], the slice doesn't need to respect alignment of `T`, only sizes
/// must match.
///
/// ## Panics /// ## Panics
/// * This is like `try_pod_read_unaligned` but will panic on failure. /// * This is like `try_pod_read_unaligned` but will panic on failure.
#[inline] #[inline]
@ -298,7 +304,7 @@ pub fn try_from_bytes_mut<T: NoUninit + AnyBitPattern>(
/// ///
/// ## Panics /// ## Panics
/// ///
/// * This is like [`try_cast`](try_cast), but will panic on a size mismatch. /// * This is like [`try_cast`], but will panic on a size mismatch.
#[inline] #[inline]
pub fn cast<A: NoUninit, B: AnyBitPattern>(a: A) -> B { pub fn cast<A: NoUninit, B: AnyBitPattern>(a: A) -> B {
unsafe { internal::cast(a) } unsafe { internal::cast(a) }
@ -351,7 +357,8 @@ pub fn cast_slice_mut<
unsafe { internal::cast_slice_mut(a) } unsafe { internal::cast_slice_mut(a) }
} }
/// As `align_to`, but safe because of the [`Pod`] bound. /// As [`align_to`](https://doc.rust-lang.org/std/primitive.slice.html#method.align_to),
/// but safe because of the [`Pod`] bound.
#[inline] #[inline]
pub fn pod_align_to<T: NoUninit, U: AnyBitPattern>( pub fn pod_align_to<T: NoUninit, U: AnyBitPattern>(
vals: &[T], vals: &[T],
@ -359,7 +366,8 @@ pub fn pod_align_to<T: NoUninit, U: AnyBitPattern>(
unsafe { vals.align_to::<U>() } unsafe { vals.align_to::<U>() }
} }
/// As `align_to_mut`, but safe because of the [`Pod`] bound. /// As [`align_to_mut`](https://doc.rust-lang.org/std/primitive.slice.html#method.align_to_mut),
/// but safe because of the [`Pod`] bound.
#[inline] #[inline]
pub fn pod_align_to_mut< pub fn pod_align_to_mut<
T: NoUninit + AnyBitPattern, T: NoUninit + AnyBitPattern,