src/libstd/cast.rs

   1 // Copyright 2012 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Unsafe casting functions
  12
  13 use mem;
  14 use intrinsics;
  15 use ptr::copy_nonoverlapping_memory;
  16
  17 /// Casts the value at `src` to U. The two types must have the same length.
  18 #[inline]
  19 pub unsafe fn transmute_copy<T, U>(src: &T) -> U {
  20     let mut dest: U = mem::uninit();
  21     let dest_ptr: *mut u8 = transmute(&mut dest);
  22     let src_ptr: *u8 = transmute(src);
  23     copy_nonoverlapping_memory(dest_ptr, src_ptr, mem::size_of::<U>());
  24     dest
  25 }
  26
  27 /**
  28  * Move a thing into the void
  29  *
  30  * The forget function will take ownership of the provided value but neglect
  31  * to run any required cleanup or memory-management operations on it. This
  32  * can be used for various acts of magick.
  33  */
  34 #[inline]
  35 pub unsafe fn forget<T>(thing: T) { intrinsics::forget(thing); }
  36
  37 /**
  38  * Force-increment the reference count on a shared box. If used
  39  * carelessly, this can leak the box.
  40  */
  41 #[inline]
  42 pub unsafe fn bump_box_refcount<T>(t: @T) { forget(t); }
  43
  44 /**
  45  * Transform a value of one type into a value of another type.
  46  * Both types must have the same size and alignment.
  47  *
  48  * # Example
  49  *
  50  * ```rust
  51  * use std::cast;
  52  *
  53  * let v: &[u8] = unsafe { cast::transmute("L") };
  54  * assert!(v == [76u8]);
  55  * ```
  56  */
  57 #[inline]
  58 pub unsafe fn transmute<L, G>(thing: L) -> G {
  59     intrinsics::transmute(thing)
  60 }
  61
  62 /// Coerce an immutable reference to be mutable.
  63 #[inline]
  64 pub unsafe fn transmute_mut<'a,T>(ptr: &'a T) -> &'a mut T { transmute(ptr) }
  65
  66 /// Coerce a reference to have an arbitrary associated lifetime.
  67 #[inline]
  68 pub unsafe fn transmute_lifetime<'a,'b,T>(ptr: &'a T) -> &'b T {
  69     transmute(ptr)
  70 }
  71
  72 /// Coerce an immutable reference to be mutable.
  73 #[inline]
  74 pub unsafe fn transmute_mut_unsafe<T>(ptr: *T) -> *mut T {
  75     transmute(ptr)
  76 }
  77
  78 /// Coerce a mutable reference to have an arbitrary associated lifetime.
  79 #[inline]
  80 pub unsafe fn transmute_mut_lifetime<'a,'b,T>(ptr: &'a mut T) -> &'b mut T {
  81     transmute(ptr)
  82 }
  83
  84 /// Transforms lifetime of the second pointer to match the first.
  85 #[inline]
  86 pub unsafe fn copy_lifetime<'a,S,T>(_ptr: &'a S, ptr: &T) -> &'a T {
  87     transmute_lifetime(ptr)
  88 }
  89
  90 /// Transforms lifetime of the second pointer to match the first.
  91 #[inline]
  92 pub unsafe fn copy_mut_lifetime<'a,S,T>(_ptr: &'a mut S, ptr: &mut T) -> &'a mut T {
  93     transmute_mut_lifetime(ptr)
  94 }
  95
  96 /// Transforms lifetime of the second pointer to match the first.
  97 #[inline]
  98 pub unsafe fn copy_lifetime_vec<'a,S,T>(_ptr: &'a [S], ptr: &T) -> &'a T {
  99     transmute_lifetime(ptr)
 100 }
 101
 102
 103 /****************************************************************************
 104  * Tests
 105  ****************************************************************************/
 106
 107 #[cfg(test)]
 108 mod tests {
 109     use cast::{bump_box_refcount, transmute};
 110     use raw;
 111
 112     #[test]
 113     fn test_transmute_copy() {
 114         assert_eq!(1u, unsafe { ::cast::transmute_copy(&1) });
 115     }
 116
 117     #[test]
 118     fn test_bump_managed_refcount() {
 119         unsafe {
 120             let managed = @~"box box box";      // refcount 1
 121             bump_box_refcount(managed);     // refcount 2
 122             let ptr: *int = transmute(managed); // refcount 2
 123             let _box1: @~str = ::cast::transmute_copy(&ptr);
 124             let _box2: @~str = ::cast::transmute_copy(&ptr);
 125             assert!(*_box1 == ~"box box box");
 126             assert!(*_box2 == ~"box box box");
 127             // Will destroy _box1 and _box2. Without the bump, this would
 128             // use-after-free. With too many bumps, it would leak.
 129         }
 130     }
 131
 132     #[test]
 133     fn test_transmute() {
 134         unsafe {
 135             let x = @100u8;
 136             let x: *raw::Box<u8> = transmute(x);
 137             assert!((*x).data == 100);
 138             let _x: @int = transmute(x);
 139         }
 140     }
 141
 142     #[test]
 143     fn test_transmute2() {
 144         unsafe {
 145             assert_eq!(~[76u8], transmute(~"L"));
 146         }
 147     }
 148 }