[collections] Adds `drain`: a way to sneak out the elements while clearing.

It is useful to move all the elements out of some collections without
deallocating the underlying buffer. It came up in IRC, and this patch
implements it as `drain`. This has been discussed as part of RFC 509.

r? @Gankro
cc: @frankmcsherry
auto merge of #19946 : cgaebel/rust/hashmap-drain-iter, r=gankro

It is useful to move all the elements out of a hashmap without deallocating
the underlying buffer. It came up in IRC, and this patch implements it as
`drain`.

r? @Gankro
cc: @frankmcsherry
auto merge of #19953 : sanxiyn/rust/privacy-span, r=alexcrichton

Fix #19062.
rollup merge of #19651: Gankro/ptr-docs

r? @steveklabnik @thestinger
rollup merge of #19727: lfairy/patch-1

Closes #19323.
rollup merge of #19823: iKevinY/doc-fixes

I was reading through the Rust Guide (hopefully looking to learn some Rust), and I figured it would be a good idea to open a pull request with some of the errata I noticed along the way. Most of the changes are pretty mundane, but there are a couple that might raise a bit of discussion.

### Punctuation outside of 'key term' quotes

This is something that was inconsistent in the Guide. While the convention in American English is to place punctuation immediately following a quotation mark *inside* the quotation mark, it seems strange to do this with 'key terms', considering they are not a true quotation.

### Changed comment placement in 17.2 code block

This is what the code block in [17.2 — Ownership, borrowing, and lifetimes](http://doc.rust-lang.org/guide.html#ownership,-borrowing,-and-lifetimes) looks like in fullscreened Safari 8:

![screen shot 2014-12-13 at 2 48 47 pm](https://cloud.githubusercontent.com/assets/2434728/5425704/2fff3bf0-82d7-11e4-8c8f-d594acde8937.png)

Some of the comments extend *just* too far, causing them to bleed into the next line, so I moved a few of them above the relevant lines of code to avoid this.
Remove a ton of public reexports

Remove most of the public reexports mentioned in #19253

These are all leftovers from the enum namespacing transition

In particular:

* src/libstd/num/strconv.rs
 * ExponentFormat
 * SignificantDigits
 * SignFormat
* src/libstd/path/windows.rs
 * PathPrefix
* src/libstd/sys/windows/timer.rs
 * Req
* src/libcollections/str.rs
 * MaybeOwned
* src/libstd/collections/hash/map.rs
 * Entry
* src/libstd/collections/hash/table.rs
 * BucketState
* src/libstd/dynamic_lib.rs
 * Rtld
* src/libstd/io/net/ip.rs
 * IpAddr
* src/libstd/os.rs
 * MemoryMapKind
 * MapOption
 * MapError
* src/libstd/sys/common/net.rs
 * SocketStatus
 * InAddr
* src/libstd/sys/unix/timer.rs
 * Req

[breaking-change]
rollup merge of #19838: shepmaster/invariant-lifetime-copy

Both ContravariantLifetime and CovariantLifetime are marked as Copy,
so it makes sense for InvariantLifetime to be as well.
rollup merge of #19842: frewsxcv/rm-reexports

Remove most of the public reexports mentioned in #19253

These are all leftovers from the enum namespacing transition

In particular:

* src/libstd/num/strconv.rs
 * ExponentFormat
 * SignificantDigits
 * SignFormat
* src/libstd/path/windows.rs
 * PathPrefix
* src/libstd/sys/windows/timer.rs
 * Req
* src/libcollections/str.rs
 * MaybeOwned
* src/libstd/collections/hash/map.rs
 * Entry
* src/libstd/collections/hash/table.rs
 * BucketState
* src/libstd/dynamic_lib.rs
 * Rtld
* src/libstd/os.rs
 * MemoryMapKind
 * MapOption
 * MapError
* src/libstd/sys/common/net.rs
 * SocketStatus
 * InAddr
* src/libstd/sys/unix/timer.rs
 * Req

[breaking-change]
rollup merge of #19898: Aatch/issue-19684

#16081 fixed an issue where a nested return statement would cause incorrect behaviour due to the inner return writing over the return stack slot that had already been written too. However, the check was very broad and picked many cases that wouldn't ever be affected by this issue.

As a result, the number of allocas increased dramatically and therefore stack-size increased. LLVM is not able to remove all of the extraneous allocas. Any code that had multiple return values in a compound expression at the end of a function (including loops) would be hit by the issue.

The check now uses a control-flow graph to only consider the case when the inner return is executed conditionally. By itself, this narrowed definition causes #15763 to return, so the control-flow graph is also used to avoid passing the return slot as a destination when the result won't be used.

This change allows the stack-size of the main rustc task to be reduced to 8MB from 32MB.
rollup merge of #19926: eddyb/less-sty

r? @nikomatsakis
rollup merge of #19932: elszben/master

First attempt to contribute to rust (and using github). This commit adds a few examples to std::io::TempDir. The examples seem to look okay (in my browser) and make check also passes.
rollup merge of #19944: steveklabnik/doc_sync_arc

Take the docs from Rc<T>, apply them to Arc<T>, and fix some line lengths.
rollup merge of #19957: tshepang/patch-1
rollup merge of #19961: alexcrichton/second-pass-result

This commit, like the second pass of `Option`, largely just stablizes the
existing functionality after renaming a few iterators.

The specific actions taken were:

* The `Ok` and `Err` variants were marked `#[stable]` as the stability
  inheritance was since removed.
* The `as_mut` method is now stable.
* The `map` method is now stable
* The `map_err` method is now stable
* The `iter`, `iter_mut`, and `into_iter` methods now returned structures named
  after the method of iteration. The methods are also now all stable.
* The `and_then` method is now stable.
* The `or_else` method is now stable.
* The `unwrap` family of functions are now all stable: `unwrap_or`,
  `unwrap_or_else`, `unwrap`, and `unwrap_err`.

There is a possible open extension to `Result::{and, and_then}` to make the
return type further generic over `FromError` (as proposed in #19078), but this
is a backwards compatible change due to the usage of default type parameters,
which makes the two functions safe to stabilize now regardless of the outcome of
that issue.
rollup merge of #19965: japaric/remove-wrong-add

TL;DR I wrongly implemented these two ops, namely `"prefix" + "suffix".to_string()` gives back `"suffixprefix"`. Let's remove them.

The correct implementation of these operations (`lhs.clone().push_str(rhs.as_slice())`) is really wasteful, because the lhs has to be cloned and the rhs gets moved/consumed just to be dropped (no buffer reuse). For this reason, I'd prefer to drop the implementation instead of fixing it. This leaves us with the fact that you'll be able to do `String + &str` but not `&str + String`, which may be unexpected.

r? @aturon
Closes #19952
rollup merge of #19966: steveklabnik/remove_l10n

@brson suggested that I remove this stuff in https://github.com/rust-lang/rust/pull/19897/files#r22014810, but it seems more appropriate to do separate from that.
rollup merge of #19967: apasel422/binary_heap

Just a few simplifications and a missing `assert!`.
rollup merge of #19969: aturon/inherit-trait-stab

There is currently no way to specify the stability level for a trait
impl produced by `deriving`. This patch is a stopgap solution that:

* Turns of stability inheritance for trait impls, and
* Uses the stability level of the *trait* if no level is directly
  specified.

That is, manual trait impls may still provide a directly stability
level, but `deriving` will use the level of the trait. While not a
perfect solution, it should be good enough for 1.0 API stabilization, as
we will like *remove* any unwanted impls outright.

r? @alexcrichton
rollup merge of #19973: vhbit/ios-no-copy