std::ptr::swap - Rust
Description: API documentation for the Rust `swap` fn in crate `std`.
Keywords: rust, rustlang, rust-lang, swap

# 1.0.0[−][src]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 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);
    }Run

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);
    }Run