Skip to content

Commit

Permalink
Unalign::update docs suggest DerefMut (#273)
Browse files Browse the repository at this point in the history
For `T: Unaligned`, `Unalign<T>: DerefMut`. Using that impl will usually
be faster and more ergonomic than using `update`.

Closes #262
  • Loading branch information
joshlf committed Aug 23, 2023
1 parent 4588a04 commit 496ee17
Showing 1 changed file with 6 additions and 0 deletions.
6 changes: 6 additions & 0 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1329,13 +1329,19 @@ impl<T> Unalign<T> {

/// Updates the inner `T` by calling a function on it.
///
/// If [`T: Unaligned`], then `Unalign<T>` implements [`DerefMut`], and that
/// impl should be preferred over this method when performing updates, as it
/// will usually be faster and more ergonomic.
///
/// For large types, this method may be expensive, as it requires copying
/// `2 * size_of::<T>()` bytes. \[1\]
///
/// \[1\] Since the inner `T` may not be aligned, it would not be sound to
/// invoke `f` on it directly. Instead, `update` moves it into a
/// properly-aligned location in the local stack frame, calls `f` on it, and
/// then moves it back to its original location in `self`.
///
/// [`T: Unaligned`]: Unaligned
pub fn update<O, F: FnOnce(&mut T) -> O>(&mut self, f: F) -> O {
// On drop, this moves `copy` out of itself and uses `ptr::write` to
// overwrite `slf`.
Expand Down

0 comments on commit 496ee17

Please sign in to comment.