Module std::mem

Working with memory (allocation, slices, copying, ...)

The main feature of this module is the slice type, which is a pointer to a region of memory. &[T] is a slice (read-only) of T, and &mut [T] is a mutable slice.

Protocols

Structs

Functions

• fn alloc<T>() -> &mut T

  source

  Allocates a single object on the heap using a default allocator (malloc)

  The value is not initialized. See alloc_zeroed which returns zeroed memory.

  See also a the matching method for allocating a slice.

  Example

  use std::mem::{alloc, free};
  
  let x: &mut i32 = alloc();
  *x = 42;
  assert_eq!(*x, 42);
  free(x);
  Run this example

• fn alloc_zeroed<T>() -> &mut T

  source

  Allocates a single object on the heap using a default allocator (malloc)

  The value is zero-initialized.

  See also a the matching method for allocating a slice.

  Example

  use std::mem::{alloc_zeroed, free};
  
  let x: &mut i32 = alloc_zeroed();
  assert_eq!(*x, 0);
  free(x);
  Run this example

• fn stack_alloc<T>(len: usize) -> &mut [T]

  source

  Allocates an array of specified size on the stack.

  The values are not initialized. The array is allocated on the stack, so it will be deallocated when the function returns.

  Care must be taken to ensure that the array is not accessed after the function returns. Additionally, there is no protection against stack overflow, so allocated arrays should not be too large.

  Example

  use std::mem::stack_alloc;
  
  let hw = "Hello, World!";
  let s = stack_alloc::<u8>(hw.len());
  
  hw.copy_to(&s[0]);
  assert_eq!(hw, s);
  Run this example

  use std::mem::stack_alloc;
  
  stack_alloc::<i32>(10000000); // stack overflow, probably
  Run this example

• fn free<T>(a: &mut T)

  source

  Frees a heap-allocated object

  The pointer must be allocated with the default allocator (malloc).

  Example

  struct Box<T> { ptr: &mut T }
  
  impl Box<T> {
      fn new(value: T) -> Box<T> {
          let ptr = std::mem::alloc::<T>();
          *ptr = value;
          Box { ptr: ptr }
      }
  
      fn free(self: &mut Box<T>) {
          std::mem::free(self.ptr);
      }
  }
  Run this example

• fn size_of<T>() -> usize

  source

  Memory size of for a given type in bytes.

  Example

  use std::mem::size_of;
  
  assert_eq!(size_of::<u8>(), 1);
  assert_eq!(size_of::<u16>(), 2);
  assert_eq!(size_of::<u32>(), 4);
  assert_eq!(size_of::<u64>(), 8);
  Run this example

• fn align_of<T>() -> usize

  source

  Minimum alignment for given type in bytes.

  Example

  use std::mem::align_of;
  
  // On most platforms
  assert_eq!(align_of::<u8>(), 1);
  assert_eq!(align_of::<u16>(), 2);
  assert_eq!(align_of::<u32>(), 4);
  assert_eq!(align_of::<u64>(), 8);
  Run this example

• fn swap<T>(a: &mut T, b: &mut T)

  source

  Swaps the data in two memory locations.

  Example

  use std::mem::swap;
  
  let a = 1;
  let b = 2;
  
  swap(&a, &b);
  
  assert_eq!(a, 2);
  assert_eq!(b, 1);
  Run this example

• fn replace<T>(a: &mut T, b: T) -> T

  source

  Replaces a memory at location a with value b.

  The existing value is returned.

  Example

  use std::mem::replace;
  
  let a = 1;
  
  assert_eq!(a.replace(2), 1);
  assert_eq!(a, 2);
  Run this example

• fn zeroed<T>() -> T

  source

  Zero-initialized object of a given type.

  Example

  use std::mem::zeroed;
  
  struct Foo { a: u8, b: u16 }
  
  let a: Foo = zeroed();
  
  assert_eq!(a.a, 0);
  assert_eq!(a.b, 0);
  Run this example

• fn uninitialized<T>() -> T

  source

  Uninitialized object.

  Using the return value is usually undefined behavior.

  Examples

  This is probably fine:

  use std::mem::uninitialized;
  
  struct MyOption<T> { some: bool, val: T }
  
  let _: MyOption<i32> = MyOption { some: true, val: 2 };
  let _: MyOption<i32> = MyOption { some: false, val: uninitialized() };
  Run this example

  This is not:

  use std::mem::uninitialized;
  
  let val: i32 = uninitialized();
  if val > 0 {  // UB!
      println!("positive");
  } else {
      println!("negative");
  }
  Run this example

• fn copy_nonoverlapping<T>(src: &T, dst: &mut T, count: usize)

  source

  Copies a region of memory from src to dst.

  The memory ranges must not overlap, use copy if they may be overlapping.

• fn copy<T>(src: &T, dst: &mut T, count: usize)

  source

  Copies a region of memory from src to dst.

  The ranges may overlap.

• fn read_volatile<T>(ptr: &T) -> T

  source

  Performs a volatile read from a memory location.

  This is useful in limited situations such as when dealing with signals/interrupts and is not likely to do what you'd expect in a multi-threaded scenario. Use Atomic instead.

  When pointed-to type is zero-sized, no read is performed.

  Example

  use std::mem::{write_volatile, read_volatile};
  
  static FLAG: i32;
  
  fn signal_handler() {
      FLAG.write_volatile(1);
  }
  
  while FLAG.read_volatile() == 0 {
      // wait for something to set the flag
  }
  Run this example

• fn write_volatile<T>(ptr: &mut T, val: T)

  source

  Performs a volatile write to a memory location.

  This is useful in limited situations such as when dealing with signals/interrupts and is not likely to do what you'd expect in a multi-threaded scenario. Use Atomic instead.

  When pointed-to type is zero-sized, no write is performed.

  Example

  use std::mem::{write_volatile, read_volatile};
  
  static FLAG: i32;
  
  fn signal_handler() {
      FLAG.write_volatile(1);
  }
  
  while FLAG.read_volatile() == 0 {
      // wait for something to set the flag
  }
  Run this example

• fn read_unaligned<T>(ptr: &T) -> T

  source

  Performs an unaligned read from a memory location.

  When pointed-to type is zero-sized, no read is performed.

  Example

  use std::mem::read_unaligned;
  
  let a = [255u8, 1, 0, 0, 0];
  let b: u32 = (&a[1] as &u32).read_unaligned();
  
  assert_eq!(b, 1);
  Run this example

• fn write_unaligned<T>(ptr: &mut T, val: T)

  source

  Performs an unaligned write to a memory location.

  When pointed-to type is zero-sized, no write is performed.

  Example

  use std::mem::write_unaligned;
  
  let a = [0u8, 0, 0, 0, 0];
  (&a[1] as &mut u32).write_unaligned(2);
  
  
  assert_eq!(a, [0, 2, 0, 0, 0]);
  Run this example

• fn dangling<Ptr>() -> Ptr

  Ptr: Pointer

  source

  Returns a dangling non-null pointer.

  The pointer is appropriately aligned for the provided type, and is non-null.

  This can be used as a sentinel value for e.g. collections of zero-sized types or empty slices where the pointer is never dereferenced, but null cannot be used for whatever reason.

  This is the pointer that is returned when taking an address of a value that has a zero-sized type.

  If the pointer points to a sized type, dereferencing it is undefined behavior. If the pointer points to a zero-sized type, dereferencing it is no-op.

  Example

  use std::mem::dangling;
  
  struct Foo { a: (), b: [u64; 0] }
  
  let foo: Foo;
  
  assert_eq!(&foo.a, dangling::<&mut ()>());
  assert_eq!(&foo.b, dangling::<&mut [u64; 0]>());
  
  // Because the types have different alignment. Currently `dangling`
  // just returns the alignment of the type (e.g. 1, 2, 4, ...)
  // cast to the pointer type.
  assert_ne!(&foo.a, &foo.b as &mut void);
  Run this example