      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163

    // Copyright 2013 The Rust Project Developers. See the COPYRIGHT
    // file at the top-level directory of this distribution and at
    // http://rust-lang.org/COPYRIGHT.
    //
    // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
    // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
    // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
    // option. This file may not be copied, modified, or distributed
    // except according to those terms.

    #![allow(missing_docs)]
    #![unstable(feature = "raw", issue = "27751")]

    //! Contains struct definitions for the layout of compiler built-in types.
    //!
    //! They can be used as targets of transmutes in unsafe code for manipulating
    //! the raw representations directly.
    //!
    //! Their definition should always match the ABI defined in `rustc::back::abi`.

    use clone::Clone;
    use marker::Copy;
    use mem;

    /// The representation of a slice like `&[T]`.
    ///
    /// This struct is guaranteed to have the layout of types like `&[T]`,
    /// `&str`, and `Box<[T]>`, but is not the type of such slices
    /// (e.g. the fields are not directly accessible on a `&[T]`) nor does
    /// it control that layout (changing the definition will not change
    /// the layout of a `&[T]`). It is only designed to be used by unsafe
    /// code that needs to manipulate the low-level details.
    ///
    /// However, it is not recommended to use this type for such code,
    /// since there are alternatives which may be safer:
    ///
    /// - Creating a slice from a data pointer and length can be done with
    ///   `std::slice::from_raw_parts` or `std::slice::from_raw_parts_mut`
    ///   instead of `std::mem::transmute`ing a value of type `Slice`.
    /// - Extracting the data pointer and length from a slice can be
    ///   performed with the `as_ptr` (or `as_mut_ptr`) and `len`
    ///   methods.
    ///
    /// If one does decide to convert a slice value to a `Slice`, the
    /// `Repr` trait in this module provides a method for a safe
    /// conversion from `&[T]` (and `&str`) to a `Slice`, more type-safe
    /// than a call to `transmute`.
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(raw)]
    ///
    /// use std::raw::{self, Repr};
    ///
    /// let slice: &[u16] = &[1, 2, 3, 4];
    ///
    /// let repr: raw::Slice<u16> = slice.repr();
    /// println!("data pointer = {:?}, length = {}", repr.data, repr.len);
    /// ```
    #[repr(C)]
    pub struct Slice<T> {
        pub data: *const T,
        pub len: usize,
    }

    impl<T> Copy for Slice<T> {}
    impl<T> Clone for Slice<T> {
        fn clone(&self) -> Slice<T> { *self }
    }

    /// The representation of a trait object like `&SomeTrait`.
    ///
    /// This struct has the same layout as types like `&SomeTrait` and
    /// `Box<AnotherTrait>`. The [Trait Objects chapter of the
    /// Book][moreinfo] contains more details about the precise nature of
    /// these internals.
    ///
    /// [moreinfo]: ../../book/trait-objects.html#representation
    ///
    /// `TraitObject` is guaranteed to match layouts, but it is not the
    /// type of trait objects (e.g. the fields are not directly accessible
    /// on a `&SomeTrait`) nor does it control that layout (changing the
    /// definition will not change the layout of a `&SomeTrait`). It is
    /// only designed to be used by unsafe code that needs to manipulate
    /// the low-level details.
    ///
    /// There is no `Repr` implementation for `TraitObject` because there
    /// is no way to refer to all trait objects generically, so the only
    /// way to create values of this type is with functions like
    /// `std::mem::transmute`. Similarly, the only way to create a true
    /// trait object from a `TraitObject` value is with `transmute`.
    ///
    /// Synthesizing a trait object with mismatched types—one where the
    /// vtable does not correspond to the type of the value to which the
    /// data pointer points—is highly likely to lead to undefined
    /// behavior.
    ///
    /// # Examples
    ///
    /// ```
    /// #![feature(raw)]
    ///
    /// use std::mem;
    /// use std::raw;
    ///
    /// // an example trait
    /// trait Foo {
    ///     fn bar(&self) -> i32;
    /// }
    /// impl Foo for i32 {
    ///     fn bar(&self) -> i32 {
    ///          *self + 1
    ///     }
    /// }
    ///
    /// let value: i32 = 123;
    ///
    /// // let the compiler make a trait object
    /// let object: &Foo = &value;
    ///
    /// // look at the raw representation
    /// let raw_object: raw::TraitObject = unsafe { mem::transmute(object) };
    ///
    /// // the data pointer is the address of `value`
    /// assert_eq!(raw_object.data as *const i32, &value as *const _);
    ///
    ///
    /// let other_value: i32 = 456;
    ///
    /// // construct a new object, pointing to a different `i32`, being
    /// // careful to use the `i32` vtable from `object`
    /// let synthesized: &Foo = unsafe {
    ///      mem::transmute(raw::TraitObject {
    ///          data: &other_value as *const _ as *mut (),
    ///          vtable: raw_object.vtable
    ///      })
    /// };
    ///
    /// // it should work just like we constructed a trait object out of
    /// // `other_value` directly
    /// assert_eq!(synthesized.bar(), 457);
    /// ```
    #[repr(C)]
    #[derive(Copy, Clone)]
    pub struct TraitObject {
        pub data: *mut (),
        pub vtable: *mut (),
    }

    /// This trait is meant to map equivalences between raw structs and their
    /// corresponding rust values.
    pub unsafe trait Repr<T> {
        /// This function "unwraps" a rust value (without consuming it) into its raw
        /// struct representation. This can be used to read/write different values
        /// for the struct. This is a safe method because by default it does not
        /// enable write-access to the fields of the return value in safe code.
        #[inline]
        fn repr(&self) -> T { unsafe { mem::transmute_copy(&self) } }
    }

    unsafe impl<T> Repr<Slice<T>> for [T] {}
    unsafe impl Repr<Slice<u8>> for str {}

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize`)