auto merge of #17894 : steveklabnik/rust/fail_to_panic, r=aturon

This in-progress PR implements https://github.com/rust-lang/rust/issues/17489.

I made the code changes in this commit, next is to go through alllllllll the documentation and fix various things.

- Rename column headings as appropriate, `# Panics` for panic conditions and `# Errors` for `Result`s.
- clean up usage of words like 'fail' in error messages

Anything else to add to the list, @aturon ? I think I should leave the actual functions with names like `slice_or_fail` alone, since you'll get to those in your conventions work?

I'm submitting just the code bits now so that we can see it separately, and I also don't want to have to keep re-building rust over and over again if I don't have to :wink: 

Listing all the bits so I can remember as I go:

- [x] compiler-rt
- [x] compiletest
- [x] doc
- [x] driver
- [x] etc
- [x] grammar
- [x] jemalloc
- [x] liballoc
- [x] libarena
- [x] libbacktrace
- [x] libcollections
- [x] libcore
- [x] libcoretest
- [x] libdebug
- [x] libflate
- [x] libfmt_macros
- [x] libfourcc
- [x] libgetopts
- [x] libglob
- [x] libgraphviz
- [x] libgreen
- [x] libhexfloat
- [x] liblibc
- [x] liblog
- [x] libnative
- [x] libnum
- [x] librand
- [x] librbml
- [x] libregex
- [x] libregex_macros
- [x] librlibc
- [x] librustc
- [x] librustc_back
- [x] librustc_llvm
- [x] librustdoc
- [x] librustrt
- [x] libsemver
- [x] libserialize
- [x] libstd
- [x] libsync
- [x] libsyntax
- [x] libterm
- [x] libtest
- [x] libtime
- [x] libunicode
- [x] liburl
- [x] libuuid
- [x] llvm
- [x] rt
- [x] test

15 files changed, 184 insertions, 137 deletions

diff --git a/src/libcore/atomic.rs b/src/libcore/atomic.rs
index cc6fe06665b..f272465e796 100644
--- a/src/libcore/atomic.rs
+++ b/src/libcore/atomic.rs
@@ -599,8 +599,8 @@ unsafe fn atomic_store<T>(dst: *mut T, val: T, order:Ordering) {
         Release => intrinsics::atomic_store_rel(dst, val),
         Relaxed => intrinsics::atomic_store_relaxed(dst, val),
         SeqCst  => intrinsics::atomic_store(dst, val),
-        Acquire => fail!("there is no such thing as an acquire store"),
-        AcqRel  => fail!("there is no such thing as an acquire/release store"),
+        Acquire => panic!("there is no such thing as an acquire store"),
+        AcqRel  => panic!("there is no such thing as an acquire/release store"),
     }
 }
 
@@ -610,8 +610,8 @@ unsafe fn atomic_load<T>(dst: *const T, order:Ordering) -> T {
         Acquire => intrinsics::atomic_load_acq(dst),
         Relaxed => intrinsics::atomic_load_relaxed(dst),
         SeqCst  => intrinsics::atomic_load(dst),
-        Release => fail!("there is no such thing as a release load"),
-        AcqRel  => fail!("there is no such thing as an acquire/release load"),
+        Release => panic!("there is no such thing as a release load"),
+        AcqRel  => panic!("there is no such thing as an acquire/release load"),
     }
 }
 
@@ -737,7 +737,7 @@ pub fn fence(order: Ordering) {
             Release => intrinsics::atomic_fence_rel(),
             AcqRel  => intrinsics::atomic_fence_acqrel(),
             SeqCst  => intrinsics::atomic_fence(),
-            Relaxed => fail!("there is no such thing as a relaxed fence")
+            Relaxed => panic!("there is no such thing as a relaxed fence")
         }
     }
 }
diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs
index 8a4b9f6e51b..9d3fa9deed7 100644
--- a/src/libcore/cell.rs
+++ b/src/libcore/cell.rs
@@ -31,7 +31,7 @@
 //! tracked statically, at compile time. Because `RefCell` borrows are
 //! dynamic it is possible to attempt to borrow a value that is
 //! already mutably borrowed; when this happens it results in task
-//! failure.
+//! panic.
 //!
 //! # When to choose interior mutability
 //!
@@ -109,7 +109,7 @@
 //!         // Recursive call to return the just-cached value.
 //!         // Note that if we had not let the previous borrow
 //!         // of the cache fall out of scope then the subsequent
-//!         // recursive borrow would cause a dynamic task failure.
+//!         // recursive borrow would cause a dynamic task panic.
 //!         // This is the major hazard of using `RefCell`.
 //!         self.minimum_spanning_tree()
 //!     }
@@ -281,7 +281,7 @@ impl<T> RefCell<T> {
     pub fn borrow<'a>(&'a self) -> Ref<'a, T> {
         match self.try_borrow() {
             Some(ptr) => ptr,
-            None => fail!("RefCell<T> already mutably borrowed")
+            None => panic!("RefCell<T> already mutably borrowed")
         }
     }
 
@@ -314,7 +314,7 @@ impl<T> RefCell<T> {
     pub fn borrow_mut<'a>(&'a self) -> RefMut<'a, T> {
         match self.try_borrow_mut() {
             Some(ptr) => ptr,
-            None => fail!("RefCell<T> already borrowed")
+            None => panic!("RefCell<T> already borrowed")
         }
     }
 
diff --git a/src/libcore/char.rs b/src/libcore/char.rs
index f507556909c..5d9553cbbbd 100644
--- a/src/libcore/char.rs
+++ b/src/libcore/char.rs
@@ -120,7 +120,7 @@ pub fn is_digit_radix(c: char, radix: uint) -> bool {
 #[inline]
 pub fn to_digit(c: char, radix: uint) -> Option<uint> {
     if radix > 36 {
-        fail!("to_digit: radix is too high (maximum 36)");
+        panic!("to_digit: radix is too high (maximum 36)");
     }
     let val = match c {
       '0' ... '9' => c as uint - ('0' as uint),
@@ -147,7 +147,7 @@ pub fn to_digit(c: char, radix: uint) -> Option<uint> {
 #[inline]
 pub fn from_digit(num: uint, radix: uint) -> Option<char> {
     if radix > 36 {
-        fail!("from_digit: radix is too high (maximum 36)");
+        panic!("from_digit: radix is to high (maximum 36)");
     }
     if num < radix {
         unsafe {
diff --git a/src/libcore/failure.rs b/src/libcore/failure.rs
deleted file mode 100644
index 9b63d325bc8..00000000000
--- a/src/libcore/failure.rs
+++ /dev/null
@@ -1,69 +0,0 @@
-// Copyright 2014 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.
-
-//! Failure support for libcore
-//!
-//! The core library cannot define failure, but it does *declare* failure. This
-//! means that the functions inside of libcore are allowed to fail, but to be
-//! useful an upstream crate must define failure for libcore to use. The current
-//! interface for failure is:
-//!
-//! ```ignore
-//! fn fail_impl(fmt: &fmt::Arguments, &(&'static str, uint)) -> !;
-//! ```
-//!
-//! This definition allows for failing with any general message, but it does not
-//! allow for failing with a `~Any` value. The reason for this is that libcore
-//! is not allowed to allocate.
-//!
-//! This module contains a few other failure functions, but these are just the
-//! necessary lang items for the compiler. All failure is funneled through this
-//! one function. Currently, the actual symbol is declared in the standard
-//! library, but the location of this may change over time.
-
-#![allow(dead_code, missing_doc)]
-
-use fmt;
-use intrinsics;
-
-#[cold] #[inline(never)] // this is the slow path, always
-#[lang="fail"]
-pub fn fail(expr_file_line: &(&'static str, &'static str, uint)) -> ! {
-    let (expr, file, line) = *expr_file_line;
-    let ref file_line = (file, line);
-    format_args!(|args| -> () {
-        fail_fmt(args, file_line);
-    }, "{}", expr);
-
-    unsafe { intrinsics::abort() }
-}
-
-#[cold] #[inline(never)]
-#[lang="fail_bounds_check"]
-fn fail_bounds_check(file_line: &(&'static str, uint),
-                     index: uint, len: uint) -> ! {
-    format_args!(|args| -> () {
-        fail_fmt(args, file_line);
-    }, "index out of bounds: the len is {} but the index is {}", len, index);
-    unsafe { intrinsics::abort() }
-}
-
-#[cold] #[inline(never)]
-pub fn fail_fmt(fmt: &fmt::Arguments, file_line: &(&'static str, uint)) -> ! {
-    #[allow(ctypes)]
-    extern {
-        #[lang = "fail_fmt"]
-        fn fail_impl(fmt: &fmt::Arguments, file: &'static str,
-                        line: uint) -> !;
-
-    }
-    let (file, line) = *file_line;
-    unsafe { fail_impl(fmt, file, line) }
-}
diff --git a/src/libcore/finally.rs b/src/libcore/finally.rs
index 9b59b410e7c..a17169f62c8 100644
--- a/src/libcore/finally.rs
+++ b/src/libcore/finally.rs
@@ -60,7 +60,7 @@ impl<T> Finally<T> for fn() -> T {
 
 /**
  * The most general form of the `finally` functions. The function
- * `try_fn` will be invoked first; whether or not it fails, the
+ * `try_fn` will be invoked first; whether or not it panics, the
  * function `finally_fn` will be invoked next. The two parameters
  * `mutate` and `drop` are used to thread state through the two
  * closures. `mutate` is used for any shared, mutable state that both
@@ -69,7 +69,7 @@ impl<T> Finally<T> for fn() -> T {
  *
  * **WARNING:** While shared, mutable state between the try and finally
  * function is often necessary, one must be very careful; the `try`
- * function could have failed at any point, so the values of the shared
+ * function could have panicked at any point, so the values of the shared
  * state may be inconsistent.
  *
  * # Example
diff --git a/src/libcore/fmt/float.rs b/src/libcore/fmt/float.rs
index 343ab7cfd28..79191c5a2b4 100644
--- a/src/libcore/fmt/float.rs
+++ b/src/libcore/fmt/float.rs
@@ -94,7 +94,7 @@ pub fn float_to_str_bytes_common<T: Primitive + Float, U>(
     assert!(2 <= radix && radix <= 36);
     match exp_format {
         ExpDec if radix >= DIGIT_E_RADIX       // decimal exponent 'e'
-          => fail!("float_to_str_bytes_common: radix {} incompatible with \
+          => panic!("float_to_str_bytes_common: radix {} incompatible with \
                     use of 'e' as decimal exponent", radix),
         _ => ()
     }
@@ -127,7 +127,7 @@ pub fn float_to_str_bytes_common<T: Primitive + Float, U>(
         ExpDec => {
             let (exp, exp_base) = match exp_format {
                 ExpDec => (num.abs().log10().floor(), cast::<f64, T>(10.0f64).unwrap()),
-                ExpNone => fail!("unreachable"),
+                ExpNone => panic!("unreachable"),
             };
 
             (num / exp_base.powf(exp), cast::<T, i32>(exp).unwrap())
@@ -299,7 +299,7 @@ pub fn float_to_str_bytes_common<T: Primitive + Float, U>(
             buf[end] = match exp_format {
                 ExpDec if exp_upper => 'E',
                 ExpDec if !exp_upper => 'e',
-                _ => fail!("unreachable"),
+                _ => panic!("unreachable"),
             } as u8;
             end += 1;
 
diff --git a/src/libcore/fmt/num.rs b/src/libcore/fmt/num.rs
index e57c4999483..22d8ba63b20 100644
--- a/src/libcore/fmt/num.rs
+++ b/src/libcore/fmt/num.rs
@@ -92,7 +92,7 @@ macro_rules! radix {
             fn digit(&self, x: u8) -> u8 {
                 match x {
                     $($x => $conv,)+
-                    x => fail!("number not in the range 0..{}: {}", self.base() - 1, x),
+                    x => panic!("number not in the range 0..{}: {}", self.base() - 1, x),
                 }
             }
         }
@@ -126,7 +126,7 @@ impl GenericRadix for Radix {
         match x {
             x @  0 ... 9 => b'0' + x,
             x if x < self.base() => b'a' + (x - 10),
-            x => fail!("number not in the range 0..{}: {}", self.base() - 1, x),
+            x => panic!("number not in the range 0..{}: {}", self.base() - 1, x),
         }
     }
 }
diff --git a/src/libcore/lib.rs b/src/libcore/lib.rs
index 62a4fbd2e08..6370e55332e 100644
--- a/src/libcore/lib.rs
+++ b/src/libcore/lib.rs
@@ -40,8 +40,8 @@
 //!
 //! * `rust_begin_unwind` - This function takes three arguments, a
 //!   `&fmt::Arguments`, a `&str`, and a `uint`. These three arguments dictate
-//!   the failure message, the file at which failure was invoked, and the line.
-//!   It is up to consumers of this core library to define this failure
+//!   the panic message, the file at which panic was invoked, and the line.
+//!   It is up to consumers of this core library to define this panic
 //!   function; it is only required to never return.
 
 // Since libcore defines many fundamental lang items, all tests live in a
@@ -111,7 +111,7 @@ pub mod atomic;
 pub mod bool;
 pub mod cell;
 pub mod char;
-pub mod failure;
+pub mod panicking;
 pub mod finally;
 pub mod iter;
 pub mod option;
@@ -129,7 +129,7 @@ pub mod fmt;
 
 #[doc(hidden)]
 mod core {
-    pub use failure;
+    pub use panicking;
 }
 
 #[doc(hidden)]
diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs
index 17fcf025457..9ba67bb2e47 100644
--- a/src/libcore/macros.rs
+++ b/src/libcore/macros.rs
@@ -10,15 +10,15 @@
 
 #![macro_escape]
 
-/// Entry point of failure, for details, see std::macros
+/// Entry point of task panic, for details, see std::macros
 #[macro_export]
-macro_rules! fail(
+macro_rules! panic(
     () => (
-        fail!("{}", "explicit failure")
+        panic!("{}", "explicit panic")
     );
     ($msg:expr) => ({
         static _MSG_FILE_LINE: (&'static str, &'static str, uint) = ($msg, file!(), line!());
-        ::core::failure::fail(&_MSG_FILE_LINE)
+        ::core::panicking::panic(&_MSG_FILE_LINE)
     });
     ($fmt:expr, $($arg:tt)*) => ({
         // a closure can't have return type !, so we need a full
@@ -31,7 +31,7 @@ macro_rules! fail(
         // as returning !. We really do want this to be inlined, however,
         // because it's just a tiny wrapper. Small wins (156K to 149K in size)
         // were seen when forcing this to be inlined, and that number just goes
-        // up with the number of calls to fail!()
+        // up with the number of calls to panic!()
         //
         // The leading _'s are to avoid dead code warnings if this is
         // used inside a dead function. Just `#[allow(dead_code)]` is
@@ -40,7 +40,7 @@ macro_rules! fail(
         #[inline(always)]
         fn _run_fmt(fmt: &::std::fmt::Arguments) -> ! {
             static _FILE_LINE: (&'static str, uint) = (file!(), line!());
-            ::core::failure::fail_fmt(fmt, &_FILE_LINE)
+            ::core::panicking::panic_fmt(fmt, &_FILE_LINE)
         }
         format_args!(_run_fmt, $fmt, $($arg)*)
     });
@@ -51,12 +51,12 @@ macro_rules! fail(
 macro_rules! assert(
     ($cond:expr) => (
         if !$cond {
-            fail!(concat!("assertion failed: ", stringify!($cond)))
+            panic!(concat!("assertion failed: ", stringify!($cond)))
         }
     );
     ($cond:expr, $($arg:tt)*) => (
         if !$cond {
-            fail!($($arg)*)
+            panic!($($arg)*)
         }
     );
 )
@@ -78,7 +78,7 @@ macro_rules! assert_eq(
         let c1 = $cond1;
         let c2 = $cond2;
         if c1 != c2 || c2 != c1 {
-            fail!("expressions not equal, left: {}, right: {}", c1, c2);
+            panic!("expressions not equal, left: {}, right: {}", c1, c2);
         }
     })
 )
@@ -130,4 +130,4 @@ macro_rules! write(
 )
 
 #[macro_export]
-macro_rules! unreachable( () => (fail!("unreachable code")) )
+macro_rules! unreachable( () => (panic!("unreachable code")) )
diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs
index 3dceb42e206..525d588d70f 100644
--- a/src/libcore/num/mod.rs
+++ b/src/libcore/num/mod.rs
@@ -1349,7 +1349,7 @@ checked_impl!(CheckedMul, checked_mul, i16, intrinsics::i16_mul_with_overflow)
 checked_impl!(CheckedMul, checked_mul, i32, intrinsics::i32_mul_with_overflow)
 checked_impl!(CheckedMul, checked_mul, i64, intrinsics::i64_mul_with_overflow)
 
-/// Performs division that returns `None` instead of failing on division by zero and instead of
+/// Performs division that returns `None` instead of panicking on division by zero and instead of
 /// wrapping around on underflow and overflow.
 pub trait CheckedDiv: Div<Self, Self> {
     /// Divides two numbers, checking for underflow, overflow and division by zero. If any of that
diff --git a/src/libcore/option.rs b/src/libcore/option.rs
index dd55c92097e..522eb833637 100644
--- a/src/libcore/option.rs
+++ b/src/libcore/option.rs
@@ -291,9 +291,9 @@ impl<T> Option<T> {
 
     /// Unwraps an option, yielding the content of a `Some`
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the value is a `None` with a custom failure message provided by
+    /// Fails if the value is a `None` with a custom panic message provided by
     /// `msg`.
     ///
     /// # Example
@@ -312,19 +312,19 @@ impl<T> Option<T> {
     pub fn expect(self, msg: &str) -> T {
         match self {
             Some(val) => val,
-            None => fail!("{}", msg),
+            None => panic!("{}", msg),
         }
     }
 
     /// Returns the inner `T` of a `Some(T)`.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the self value equals `None`.
+    /// Panics if the self value equals `None`.
     ///
     /// # Safety note
     ///
-    /// In general, because this function may fail, its use is discouraged.
+    /// In general, because this function may panic, its use is discouraged.
     /// Instead, prefer to use pattern matching and handle the `None`
     /// case explicitly.
     ///
@@ -344,7 +344,7 @@ impl<T> Option<T> {
     pub fn unwrap(self) -> T {
         match self {
             Some(val) => val,
-            None => fail!("called `Option::unwrap()` on a `None` value"),
+            None => panic!("called `Option::unwrap()` on a `None` value"),
         }
     }
 
diff --git a/src/libcore/panicking.rs b/src/libcore/panicking.rs
new file mode 100644
index 00000000000..62c9d907cb2
--- /dev/null
+++ b/src/libcore/panicking.rs
@@ -0,0 +1,116 @@
+// Copyright 2014 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.
+
+//! Panic support for libcore
+//!
+//! The core library cannot define panicking, but it does *declare* panicking. This
+//! means that the functions inside of libcore are allowed to panic, but to be
+//! useful an upstream crate must define panicking for libcore to use. The current
+//! interface for panicking is:
+//!
+//! ```ignore
+//! fn panic_impl(fmt: &fmt::Arguments, &(&'static str, uint)) -> !;
+//! ```
+//!
+//! This definition allows for panicking with any general message, but it does not
+//! allow for failing with a `Box<Any>` value. The reason for this is that libcore
+//! is not allowed to allocate.
+//!
+//! This module contains a few other panicking functions, but these are just the
+//! necessary lang items for the compiler. All panics are funneled through this
+//! one function. Currently, the actual symbol is declared in the standard
+//! library, but the location of this may change over time.
+
+#![allow(dead_code, missing_doc)]
+
+use fmt;
+use intrinsics;
+
+// NOTE(stage0): remove after a snapshot
+#[cfg(stage0)]
+#[cold] #[inline(never)] // this is the slow path, always
+#[lang="fail"]
+pub fn panic(expr_file_line: &(&'static str, &'static str, uint)) -> ! {
+    let (expr, file, line) = *expr_file_line;
+    let ref file_line = (file, line);
+    format_args!(|args| -> () {
+        panic_fmt(args, file_line);
+    }, "{}", expr);
+
+    unsafe { intrinsics::abort() }
+}
+
+// NOTE(stage0): remove after a snapshot
+#[cfg(stage0)]
+#[cold] #[inline(never)]
+#[lang="fail_bounds_check"]
+fn panic_bounds_check(file_line: &(&'static str, uint),
+                     index: uint, len: uint) -> ! {
+    format_args!(|args| -> () {
+        panic_fmt(args, file_line);
+    }, "index out of bounds: the len is {} but the index is {}", len, index);
+    unsafe { intrinsics::abort() }
+}
+
+// NOTE(stage0): remove after a snapshot
+#[cfg(stage0)]
+#[cold] #[inline(never)]
+pub fn panic_fmt(fmt: &fmt::Arguments, file_line: &(&'static str, uint)) -> ! {
+    #[allow(ctypes)]
+    extern {
+        #[lang = "fail_fmt"]
+        fn panic_impl(fmt: &fmt::Arguments, file: &'static str,
+                        line: uint) -> !;
+
+    }
+    let (file, line) = *file_line;
+    unsafe { panic_impl(fmt, file, line) }
+}
+
+// NOTE(stage0): remove cfg after a snapshot
+#[cfg(not(stage0))]
+#[cold] #[inline(never)] // this is the slow path, always
+#[lang="panic"]
+pub fn panic(expr_file_line: &(&'static str, &'static str, uint)) -> ! {
+    let (expr, file, line) = *expr_file_line;
+    let ref file_line = (file, line);
+    format_args!(|args| -> () {
+        panic_fmt(args, file_line);
+    }, "{}", expr);
+
+    unsafe { intrinsics::abort() }
+}
+
+// NOTE(stage0): remove cfg after a snapshot
+#[cfg(not(stage0))]
+#[cold] #[inline(never)]
+#[lang="panic_bounds_check"]
+fn panic_bounds_check(file_line: &(&'static str, uint),
+                     index: uint, len: uint) -> ! {
+    format_args!(|args| -> () {
+        panic_fmt(args, file_line);
+    }, "index out of bounds: the len is {} but the index is {}", len, index);
+    unsafe { intrinsics::abort() }
+}
+
+// NOTE(stage0): remove cfg after a snapshot
+#[cfg(not(stage0))]
+#[cold] #[inline(never)]
+pub fn panic_fmt(fmt: &fmt::Arguments, file_line: &(&'static str, uint)) -> ! {
+    #[allow(ctypes)]
+    extern {
+        #[lang = "panic_fmt"]
+        fn panic_impl(fmt: &fmt::Arguments, file: &'static str,
+                        line: uint) -> !;
+
+    }
+    let (file, line) = *file_line;
+    unsafe { panic_impl(fmt, file, line) }
+}
diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs
index f0cd8402b14..5e2f5529e8d 100644
--- a/src/libcore/ptr.rs
+++ b/src/libcore/ptr.rs
@@ -76,7 +76,7 @@
 //!     unsafe {
 //!         let my_num: *mut int = libc::malloc(mem::size_of::<int>() as libc::size_t) as *mut int;
 //!         if my_num.is_null() {
-//!             fail!("failed to allocate memory");
+//!             panic!("failed to allocate memory");
 //!         }
 //!         libc::free(my_num as *mut libc::c_void);
 //!     }
diff --git a/src/libcore/result.rs b/src/libcore/result.rs
index 27bb649d1d9..82da972f68a 100644
--- a/src/libcore/result.rs
+++ b/src/libcore/result.rs
@@ -123,8 +123,8 @@
 //! warning (by default, controlled by the `unused_must_use` lint).
 //!
 //! You might instead, if you don't want to handle the error, simply
-//! fail, by converting to an `Option` with `ok`, then asserting
-//! success with `expect`. This will fail if the write fails, proving
+//! panic, by converting to an `Option` with `ok`, then asserting
+//! success with `expect`. This will panic if the write fails, proving
 //! a marginally useful message indicating why:
 //!
 //! ```{.no_run}
@@ -250,29 +250,29 @@
 //! let mut t = Timer::new().ok().expect("failed to create timer!");
 //! ```
 //!
-//! # `Result` vs. `fail!`
+//! # `Result` vs. `panic!`
 //!
-//! `Result` is for recoverable errors; `fail!` is for unrecoverable
-//! errors. Callers should always be able to avoid failure if they
+//! `Result` is for recoverable errors; `panic!` is for unrecoverable
+//! errors. Callers should always be able to avoid panics if they
 //! take the proper precautions, for example, calling `is_some()`
 //! on an `Option` type before calling `unwrap`.
 //!
-//! The suitability of `fail!` as an error handling mechanism is
+//! The suitability of `panic!` as an error handling mechanism is
 //! limited by Rust's lack of any way to "catch" and resume execution
-//! from a thrown exception. Therefore using failure for error
-//! handling requires encapsulating fallible code in a task. Calling
-//! the `fail!` macro, or invoking `fail!` indirectly should be
-//! avoided as an error reporting strategy. Failure is only for
-//! unrecoverable errors and a failing task is typically the sign of
+//! from a thrown exception. Therefore using panics for error
+//! handling requires encapsulating code that may panic in a task.
+//! Calling the `panic!` macro, or invoking `panic!` indirectly should be
+//! avoided as an error reporting strategy. Panics is only for
+//! unrecoverable errors and a panicking task is typically the sign of
 //! a bug.
 //!
 //! A module that instead returns `Results` is alerting the caller
-//! that failure is possible, and providing precise control over how
+//! that panics are possible, and providing precise control over how
 //! it is handled.
 //!
-//! Furthermore, failure may not be recoverable at all, depending on
-//! the context. The caller of `fail!` should assume that execution
-//! will not resume after failure, that failure is catastrophic.
+//! Furthermore, panics may not be recoverable at all, depending on
+//! the context. The caller of `panic!` should assume that execution
+//! will not resume after the panic, that a panic is catastrophic.
 
 #![stable]
 
@@ -764,9 +764,9 @@ impl<T, E> Result<T, E> {
 impl<T, E: Show> Result<T, E> {
     /// Unwraps a result, yielding the content of an `Ok`.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the value is an `Err`, with a custom failure message provided
+    /// Panics if the value is an `Err`, with a custom panic message provided
     /// by the `Err`'s value.
     ///
     /// # Example
@@ -778,7 +778,7 @@ impl<T, E: Show> Result<T, E> {
     ///
     /// ```{.should_fail}
     /// let x: Result<uint, &str> = Err("emergency failure");
-    /// x.unwrap(); // fails with `emergency failure`
+    /// x.unwrap(); // panics with `emergency failure`
     /// ```
     #[inline]
     #[unstable = "waiting for conventions"]
@@ -786,7 +786,7 @@ impl<T, E: Show> Result<T, E> {
         match self {
             Ok(t) => t,
             Err(e) =>
-                fail!("called `Result::unwrap()` on an `Err` value: {}", e)
+                panic!("called `Result::unwrap()` on an `Err` value: {}", e)
         }
     }
 }
@@ -794,16 +794,16 @@ impl<T, E: Show> Result<T, E> {
 impl<T: Show, E> Result<T, E> {
     /// Unwraps a result, yielding the content of an `Err`.
     ///
-    /// # Failure
+    /// # Panics
     ///
-    /// Fails if the value is an `Ok`, with a custom failure message provided
+    /// Panics if the value is an `Ok`, with a custom panic message provided
     /// by the `Ok`'s value.
     ///
     /// # Example
     ///
     /// ```{.should_fail}
     /// let x: Result<uint, &str> = Ok(2u);
-    /// x.unwrap_err(); // fails with `2`
+    /// x.unwrap_err(); // panics with `2`
     /// ```
     ///
     /// ```
@@ -815,7 +815,7 @@ impl<T: Show, E> Result<T, E> {
     pub fn unwrap_err(self) -> E {
         match self {
             Ok(t) =>
-                fail!("called `Result::unwrap_err()` on an `Ok` value: {}", t),
+                panic!("called `Result::unwrap_err()` on an `Ok` value: {}", t),
             Err(e) => e
         }
     }
diff --git a/src/libcore/str.rs b/src/libcore/str.rs
index 0c2415753fa..ff1db992844 100644
--- a/src/libcore/str.rs
+++ b/src/libcore/str.rs
@@ -1460,7 +1460,7 @@ pub trait StrSlice for Sized? {
     ///
     /// assert_eq!(s.slice(1, 9), "öwe 老");
     ///
-    /// // these will fail:
+    /// // these will panic:
     /// // byte 2 lies within `ö`:
     /// // s.slice(2, 3);
     ///
@@ -1832,7 +1832,7 @@ pub trait StrSlice for Sized? {
 #[inline(never)]
 fn slice_error_fail(s: &str, begin: uint, end: uint) -> ! {
     assert!(begin <= end);
-    fail!("index {} and/or {} in `{}` do not lie on character boundary",
+    panic!("index {} and/or {} in `{}` do not lie on character boundary",
           begin, end, s);
 }
 
@@ -1986,8 +1986,8 @@ impl StrSlice for str {
         if end_byte.is_none() && count == end { end_byte = Some(self.len()) }
 
         match (begin_byte, end_byte) {
-            (None, _) => fail!("slice_chars: `begin` is beyond end of string"),
-            (_, None) => fail!("slice_chars: `end` is beyond end of string"),
+            (None, _) => panic!("slice_chars: `begin` is beyond end of string"),
+            (_, None) => panic!("slice_chars: `end` is beyond end of string"),
             (Some(a), Some(b)) => unsafe { raw::slice_bytes(self, a, b) }
         }
     }