core: Move 'unreachable' to util. Improve docs

src/libcore/core.rs

@@ -22,7 +22,7 @@
 use to_str::ToStr;
 
 export Path, WindowsPath, PosixPath, GenericPath;
-export Option, Some, None, unreachable;
+export Option, Some, None;
 export Result, Ok, Err;
 export extensions;
 // The following exports are the extension impls for numeric types
@@ -96,13 +96,3 @@ mod std {
     extern mod std(vers = "0.4");
     use std::test;
 }
-
-/**
- * A standard function to use to indicate unreachable code. Because the
- * function is guaranteed to fail typestate will correctly identify
- * any code paths following the appearance of this function as unreachable.
- */
-fn unreachable() -> ! {
-    fail ~"Internal error: entered unreachable code";
-}
-

src/libcore/rand.rs

@@ -206,7 +206,7 @@ fn choose_weighted_option<T:Copy>(v: &[Weighted<T>]) -> Option<T> {
                 return Some(item.item);
             }
         }
-        unreachable();
+        util::unreachable();
     }
 
     /**

src/libcore/util.rs

@@ -64,6 +64,34 @@ struct NonCopyable {
 
 fn NonCopyable() -> NonCopyable { NonCopyable { i: () } }
 
+/**
+A utility function 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
+
+~~~
+fn choose_weighted_item(v: &[Item]) -> Item {
+    assert v.is_not_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
+    util::unreachable();
+}
+~~~
+
+*/
+fn unreachable() -> ! {
+    fail ~"internal error: entered unreachable code";
+}
+
 mod tests {
     #[test]
     fn identity_crisis() {

src/rustc/back/rpath.rs

@@ -106,7 +106,7 @@ fn get_rpath_relative_to_output(os: session::os,
     let prefix = match os {
         session::os_linux | session::os_freebsd => "$ORIGIN",
         session::os_macos => "@executable_path",
-        session::os_win32 => core::unreachable()
+        session::os_win32 => core::util::unreachable()
     };
 
     Path(prefix).push_rel(&get_relative_to(&os::make_absolute(output),

src/rustc/middle/trans/alt.rs

@@ -170,7 +170,7 @@ fn variant_opt(tcx: ty::ctxt, pat_id: ast::node_id) -> Opt {
     for vec::each(*variants) |v| {
         if vdef.var == v.id { return var(v.disr_val, vdef); }
     }
-    core::unreachable();
+    core::util::unreachable();
 }
 
 enum TransBindingMode {