auto merge of #8992 : chris-morgan/rust/unreachable-macro, r=brson

Rationale: having a function which fails means that the location of
failure which is output is that of the unreachable() function, rather
than the caller.

This is part of #8991 but is not all of it; current usage of
``std::util::unreachable()`` must remain so for the moment, until a new
snapshot is made; then I will remove that function entirely in favour of
using this macro.

Author: bors

src/libsyntax/ext/expand.rs

@@ -884,6 +884,36 @@ pub fn std_macros() -> @str {
         )
     )
 
+    // FIXME(#6266): change the /* to /** when attributes are supported on macros
+    // (Though even then—is it going to work according to the clear intent here?)
+    /*
+    A utility macro for indicating unreachable code. It will fail if
+    executed. This is occasionally useful to put after loops that never
+    terminate normally, but instead directly return from a function.
+
+    # Example
+
+    ~~~ {.rust}
+    fn choose_weighted_item(v: &[Item]) -> Item {
+        assert!(!v.is_empty());
+        let mut so_far = 0u;
+        for v.each |item| {
+            so_far += item.weight;
+            if so_far > 100 {
+                return item;
+            }
+        }
+        // The above loop always returns, so we must hint to the
+        // type checker that it isn't possible to get down here
+        unreachable!();
+    }
+    ~~~
+
+    */
+    macro_rules! unreachable (() => (
+        fail!(\"internal error: entered unreachable code\");
+    ))
+
     macro_rules! condition (
 
         { pub $c:ident: $input:ty -> $out:ty; } => {