From: Corey Farwell <coreyf@rwell.org>
Date: Sat, 23 Sep 2017 04:29:10 +0000 (-0400)
Subject: Rollup merge of #44648 - Havvy:doc-size_of, r=dtolnay
X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=04eb88c987be232e9eecba7c2d336e10b614dfac;hp=-c;p=rust.git

Rollup merge of #44648 - Havvy:doc-size_of, r=dtolnay

Expand size_of docs

This PR does 3 things.

1. Adds a description of what pointer size means to the primitive pages for usize and isize.
2. Says the general size of things is not stable from compiler to compiler.
3. Adds a table of sizes of things that we do guarantee. As this is the first table in the libstd docs, I've included a picture of how that looks.

![](https://i.imgur.com/YZ6IChH.png?1)
---

04eb88c987be232e9eecba7c2d336e10b614dfac
diff --combined src/libcore/mem.rs
index 34994dc3b70,e98dab739cb..669b93120cf
--- a/src/libcore/mem.rs
+++ b/src/libcore/mem.rs
@@@ -177,15 -177,59 +177,59 @@@ pub fn forget<T>(t: T) 
  
  /// Returns the size of a type in bytes.
  ///
- /// More specifically, this is the offset in bytes between successive
- /// items of the same type, including alignment padding.
+ /// More specifically, this is the offset in bytes between successive elements
+ /// in an array with that item type including alignment padding. Thus, for any
+ /// type `T` and length `n`, `[T; n]` has a size of `n * size_of::<T>()`.
+ ///
+ /// In general, the size of a type is not stable across compilations, but
+ /// specific types such as primitives are.
+ ///
+ /// The following table gives the size for primitives.
+ ///
+ /// Type | size_of::\<Type>()
+ /// ---- | ---------------
+ /// () | 0
+ /// u8 | 1
+ /// u16 | 2
+ /// u32 | 4
+ /// u64 | 8
+ /// i8 | 1
+ /// i16 | 2
+ /// i32 | 4
+ /// i64 | 8
+ /// f32 | 4
+ /// f64 | 8
+ /// char | 4
+ ///
+ /// Furthermore, `usize` and `isize` have the same size.
+ ///
+ /// The types `*const T`, `&T`, `Box<T>`, `Option<&T>`, and `Option<Box<T>>` all have
+ /// the same size. If `T` is Sized, all of those types have the same size as `usize`.
+ ///
+ /// The mutability of a pointer does not change its size. As such, `&T` and `&mut T`
+ /// have the same size. Likewise for `*const T` and `*mut T`.
  ///
  /// # Examples
  ///
  /// ```
  /// use std::mem;
  ///
+ /// // Some primitives
  /// assert_eq!(4, mem::size_of::<i32>());
+ /// assert_eq!(8, mem::size_of::<f64>());
+ /// assert_eq!(0, mem::size_of::<()>());
+ ///
+ /// // Some arrays
+ /// assert_eq!(8, mem::size_of::<[i32; 2]>());
+ /// assert_eq!(12, mem::size_of::<[i32; 3]>());
+ /// assert_eq!(0, mem::size_of::<[i32; 0]>());
+ ///
+ ///
+ /// // Pointer size equality
+ /// assert_eq!(mem::size_of::<&i32>(), mem::size_of::<*const i32>());
+ /// assert_eq!(mem::size_of::<&i32>(), mem::size_of::<Box<i32>>());
+ /// assert_eq!(mem::size_of::<&i32>(), mem::size_of::<Option<&i32>>());
+ /// assert_eq!(mem::size_of::<Box<i32>>(), mem::size_of::<Option<Box<i32>>>());
  /// ```
  #[inline]
  #[stable(feature = "rust1", since = "1.0.0")]
@@@ -332,6 -376,7 +376,6 @@@ pub fn align_of_val<T: ?Sized>(val: &T
  /// Here's an example of how a collection might make use of needs_drop:
  ///
  /// ```
 -/// #![feature(needs_drop)]
  /// use std::{mem, ptr};
  ///
  /// pub struct MyCollection<T> {
@@@ -358,7 -403,7 +402,7 @@@
  /// }
  /// ```
  #[inline]
 -#[unstable(feature = "needs_drop", issue = "41890")]
 +#[stable(feature = "needs_drop", since = "1.22.0")]
  pub fn needs_drop<T>() -> bool {
      unsafe { intrinsics::needs_drop::<T>() }
  }