mem

std::mem helpers for moving values in place: swap, replace, take, and drop, and how they differ.

主题页正文目前为英文。

std::mem has a small set of safe helpers for moving values around when you cannot simply rebind a variable. swap exchanges two values. replace puts a new value in a location and returns the old one. take is replace with T::default(). drop ends a value's lifetime early so its destructor runs now.

This page does not cover unsafe code, raw pointers, or mem::transmute. Those APIs are easy to misuse and are not part of this reference. Examples were compiled with rustc 1.90.0 and --edition=2024.

Examples were compiled with rustc 1.90.0 using --edition=2024 and run as a plain binary. See the Rust 1.90.0 documentation for the complete API.

Rust reference overview →

API index

APISummary
mem::swap, mem::replace, mem::takeExchange two values, or take a value out of a place by leaving something else behind.
mem::dropEnd a value's lifetime immediately. The destructor runs if the type implements Drop, and the name is then gone.

swap, replace, and take

swap needs two mutable places and exchanges their contents. replace overwrites dest with src and returns the previous value. take is the common case of replace(dest, T::default()) and therefore requires T: Default. After take on a String, the variable is still in scope, but it now holds an empty String rather than being moved away.

mem::swap, mem::replace, mem::take

pub fn swap<T>(x: &mut T, y: &mut T)
pub fn replace<T>(dest: &mut T, src: T) -> T
pub fn take<T>(dest: &mut T) -> T
    where
        T: Default

Exchange two values, or take a value out of a place by leaving something else behind.

ParameterDescription
x, yThe two mutable locations swapped in place.
destThe place to overwrite. replace and take both leave dest initialized.
srcThe value replace writes into dest.

Returns: swap returns (). replace returns the previous contents of dest. take returns the previous contents and leaves Default::default() in dest.

  • take is not a way to use a value after a move out of a non-Default type. If T has no Default, use replace with an explicit standby value, or restructure the code.
  • These functions are safe. They do not transmute representations or unsafely invent values.
rust
use std::mem;

fn main() {
    let mut a = 1;
    let mut b = 2;
    mem::swap(&mut a, &mut b);
    println!("swap={a} {b}");

    let mut left = String::from("old");
    let taken = mem::take(&mut left);
    println!("take={taken} left={left:?}");

    let mut current = String::from("old");
    let previous = mem::replace(&mut current, String::from("new"));
    println!("replace prev={previous} now={current}");
}

Expected output

swap=2 1
take=old left=""
replace prev=old now=new

Related: Default, Clone, and Copy, Official std::mem

Official documentation →

drop runs a destructor now

drop(value) moves value into the function and lets it go out of scope immediately, so Drop::drop runs at that point if the type implements Drop. After drop(values), the variable cannot be used again. drop is not a manual free for raw pointers, and it is not mem::forget, which skips destructors and can leak. This page does not document forget or unsafe deallocation.

mem::drop

pub fn drop<T>(_x: T)

End a value's lifetime immediately. The destructor runs if the type implements Drop, and the name is then gone.

ParameterDescription
_xThe value to drop. It is moved into drop and is no longer available to the caller.

Returns: (). There is no "dropped handle" to use afterwards.

  • The example prints the length, calls drop, then prints a literal. Using values after drop is a compile error (use of moved value).
  • A temporary is dropped at the end of the enclosing statement without an explicit drop call. Use drop when you need the destructor to run before later code in the same scope.
rust
fn main() {
    let values = vec![1, 2, 3];
    println!("before_drop={}", values.len());
    drop(values);
    println!("dropped");
}

Expected output

before_drop=3
dropped

Related: Official mem::drop

Official documentation →