Add more docs - mostly warnings - to std::mem::transmute

src/libcore/intrinsics.rs

@@ -278,17 +278,157 @@ extern "rust-intrinsic" {
     /// Moves a value out of scope without running drop glue.
     pub fn forget<T>(_: T) -> ();
 
-    /// Unsafely transforms a value of one type into a value of another type.
+    /// Reinterprets the bits of a value of one type as another type. Both types
+    /// must have the same size. Neither the original, nor the result, may be an
+    /// [invalid value]
+    /// (https://doc.rust-lang.org/nomicon/meet-safe-and-unsafe.html).
     ///
-    /// Both types must have the same size.
+    /// `transmute::<T, U>(t)` is semantically equivalent to the following:
     ///
-    /// # Examples
+    /// ```
+    /// // assuming that T and U are the same size
+    /// unsafe fn transmute<T, U>(t: T) -> U {
+    ///     let u: U = mem::uninitialized();
+    ///     std::ptr::copy_nonoverlapping(&t as *const T as *const u8,
+    ///                                   &mut u as *mut U as *mut u8,
+    ///                                   mem::size_of::<T>());
+    ///     mem::forget(t);
+    ///     u
+    /// }
+    /// ```
+    ///
+    /// `transmute` is incredibly unsafe. There are a vast number of ways to
+    /// cause undefined behavior with this function. `transmute` should be
+    /// the absolute last resort.
+    ///
+    /// The [nomicon](https://doc.rust-lang.org/nomicon/transmutes.html) has
+    /// more complete documentation. Read it before using `transmute`.
+    ///
+    /// # Alternatives
+    ///
+    /// There are very few good cases for `transmute`. Most can be achieved
+    /// through other means. Some more or less common uses, and a better way,
+    /// are as follows:
     ///
     /// ```
     /// use std::mem;
     ///
-    /// let array: &[u8] = unsafe { mem::transmute("Rust") };
-    /// assert_eq!(array, [82, 117, 115, 116]);
+    /// // turning a pointer into a usize
+    /// {
+    ///     let ptr = &0;
+    ///     let ptr_num_transmute = mem::transmute::<&i32, usize>(ptr);
+    ///     // Use `as` casts instead
+    ///     let ptr_num_cast = ptr as *const i32 as usize;
+    /// }
+    ///
+    /// // Turning a *mut T into an &mut T
+    /// {
+    ///     let ptr: *mut i32 = &mut 0;
+    ///     let ref_transmuted = mem::transmute::<*mut i32, &mut i32>(ptr);
+    ///     // Use reborrows
+    ///     let ref_casted = &mut *ptr;
+    /// }
+    ///
+    /// // Turning an &mut T into an &mut U
+    /// {
+    ///     let ptr = &mut 0;
+    ///     let val_transmuted = mem::transmute::<&mut i32, &mut u32>(ptr);
+    ///     // Now let's put together `as` and reborrowing
+    ///     let val_casts = &mut *(ptr as *mut i32 as *mut u32);
+    /// }
+    ///
+    /// // Turning an `&str` into an `&[u8]`
+    /// {
+    ///     // this is not a good way to do this.
+    ///     let slice = unsafe { mem::transmute::<&str, &[u8]>("Rust") };
+    ///     assert_eq!(slice, [82, 117, 115, 116]);
+    ///     // You could use `str::as_bytes`
+    ///     let slice = "Rust".as_bytes();
+    ///     assert_eq!(slice, [82, 117, 115, 116]);
+    ///     // Or, just use a byte string, if you have control over the string
+    ///     // literal
+    ///     assert_eq!(b"Rust", [82, 117, 116, 116]);
+    /// }
+    ///
+    /// // Turning a Vec<&T> into a Vec<Option<&T>>
+    /// {
+    ///     let store = [0, 1, 2, 3];
+    ///     let v_orig = store.iter().collect::<Vec<&i32>>();
+    ///     // Using transmute; Undefined Behavior
+    ///     let v_transmuted = mem::transmute::<Vec<&i32>, Vec<Option<&i32>>>(
+    ///         v_orig.clone());
+    ///     // The suggested, safe way
+    ///     let v_collected = v_orig.clone()
+    ///                             .into_iter()
+    ///                             .map(|r| Some(r))
+    ///                             .collect::<Vec<Option<&i32>>>();
+    ///     // The no-copy, unsafe way, still using transmute, but not UB
+    ///     // This is equivalent to the original, but safer, and reuses the
+    ///     // same Vec internals. Therefore the new inner type must have the
+    ///     // exact same size, and the same or lesser alignment, as the old
+    ///     // type. The same caveats exist for this method as transmute, for
+    ///     // the original inner type (`&i32`) to the converted inner type
+    ///     // (`Option<&i32>`), so read the nomicon page linked above.
+    ///     let v_no_copy = Vec::from_raw_parts(v_orig.as_mut_ptr(),
+    ///                                         v_orig.len(),
+    ///                                         v_orig.capacity());
+    ///     mem::forget(v_orig);
+    /// }
+    ///
+    ///
+    /// // Copying an `&mut T` to reslice:
+    /// {
+    ///     fn split_at_mut_transmute<T>(slice: &mut [T], index: usize)
+    ///                                  -> (&mut [T], &mut [T]) {
+    ///         let len = slice.len();
+    ///         assert!(index < len);
+    ///         let slice2 = mem::transmute::<&mut [T], &mut [T]>(slice);
+    ///         (slice[0..index], slice2[index..len])
+    ///     }
+    ///     // Again, use `as` and reborrowing
+    ///     fn split_at_mut_casts<T>(slice: &mut [T], index: usize)
+    ///                              -> (&mut [T], &mut [T]) {
+    ///         let len = slice.len();
+    ///         assert!(index < len);
+    ///         let slice2 = &mut *(slice as *mut [T]); // actually typesafe!
+    ///         (slice[0..index], slice2[index..len])
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// # Examples
+    ///
+    /// There are valid uses of transmute, though they are few and far between.
+    ///
+    /// ```
+    /// // getting the bitpattern of a floating point type
+    /// {
+    ///     let x = mem::transmute::<f32, u32>(0.0/0.0)
+    /// }
+    ///
+    ///
+    /// // turning a pointer into a function pointer
+    /// {
+    ///     // in file.c: `int foo(void) { ... }`
+    ///     let handle: *mut libc::c_void = libc::dlopen(
+    ///         b"file.so\0".as_ptr() as *const libc::c_char, libc::RTLD_LAZY);
+    ///     let foo: *mut libc::c_void = libc::dlsym(
+    ///         handle,
+    ///         b"foo\0".as_ptr() as *const libc::c_char);
+    ///     let foo = mem::transmute::<*mut libc::c_void,
+    ///                                     extern fn() -> libc::c_int>(foo);
+    ///     println!("{}", foo());
+    /// }
+    ///
+    ///
+    /// // extending an invariant lifetime; this is advanced, very unsafe rust
+    /// {
+    ///     struct T<'a>(&'a i32);
+    ///     let value = 0;
+    ///     let t = T::new(&value);
+    ///     let ptr = &mut t;
+    ///     let ptr_extended = mem::transmute::<&mut T, &mut T<'static>>(ptr);
+    /// }
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn transmute<T, U>(e: T) -> U;