W3cubDocs

/Rust

Function std::ptr::swap

pub unsafe fn swap<T>(x: *mut T, y: *mut T)

Swaps the values at two mutable locations of the same type, without deinitializing either.

But for the following two exceptions, this function is semantically equivalent to mem::swap:

  • It operates on raw pointers instead of references. When references are available, mem::swap should be preferred.

  • The two pointed-to values may overlap. If the values do overlap, then the overlapping region of memory from x will be used. This is demonstrated in the second example below.

Safety

Behavior is undefined if any of the following conditions are violated:

  • Both x and y must be valid for both reads and writes.

  • Both x and y must be properly aligned.

Note that even if T has size 0, the pointers must be non-NULL and properly aligned.

Examples

Swapping two non-overlapping regions:

use std::ptr;

let mut array = [0, 1, 2, 3];

let x = array[0..].as_mut_ptr() as *mut [u32; 2]; // this is `array[0..2]`
let y = array[2..].as_mut_ptr() as *mut [u32; 2]; // this is `array[2..4]`

unsafe {
    ptr::swap(x, y);
    assert_eq!([2, 3, 0, 1], array);
}

Swapping two overlapping regions:

use std::ptr;

let mut array = [0, 1, 2, 3];

let x = array[0..].as_mut_ptr() as *mut [u32; 3]; // this is `array[0..3]`
let y = array[1..].as_mut_ptr() as *mut [u32; 3]; // this is `array[1..4]`

unsafe {
    ptr::swap(x, y);
    // The indices `1..3` of the slice overlap between `x` and `y`.
    // Reasonable results would be for to them be `[2, 3]`, so that indices `0..3` are
    // `[1, 2, 3]` (matching `y` before the `swap`); or for them to be `[0, 1]`
    // so that indices `1..4` are `[0, 1, 2]` (matching `x` before the `swap`).
    // This implementation is defined to make the latter choice.
    assert_eq!([1, 0, 1, 2], array);
}

© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/ptr/fn.swap.html