Rename fail! to panic!

https://github.com/rust-lang/rfcs/pull/221

The current terminology of "task failure" often causes problems when
writing or speaking about code. You often want to talk about the
possibility of an operation that returns a Result "failing", but cannot
because of the ambiguity with task failure. Instead, you have to speak
of "the failing case" or "when the operation does not succeed" or other
circumlocutions.

Likewise, we use a "Failure" header in rustdoc to describe when
operations may fail the task, but it would often be helpful to separate
out a section describing the "Err-producing" case.

We have been steadily moving away from task failure and toward Result as
an error-handling mechanism, so we should optimize our terminology
accordingly: Result-producing functions should be easy to describe.

To update your code, rename any call to `fail!` to `panic!` instead.
Assuming you have not created your own macro named `panic!`, this
will work on UNIX based systems:

    grep -lZR 'fail!' . | xargs -0 -l sed -i -e 's/fail!/panic!/g'

You can of course also do this by hand.

[breaking-change]

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")
         }
     }
 }

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")
         }
     }
 

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 {

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

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;
 

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),
         }
     }
 }

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)]

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")) )

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

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"),
         }
     }
 

src/libcore/panicking.rs

@@ -8,23 +8,23 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Failure support for libcore
+//! Panic 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:
+//! 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 fail_impl(fmt: &fmt::Arguments, &(&'static str, uint)) -> !;
+//! fn panic_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
+//! 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 failure functions, but these are just the
-//! necessary lang items for the compiler. All failure is funneled through this
+//! 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.
 
@@ -34,36 +34,36 @@ 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)) -> ! {
+#[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| -> () {
-        fail_fmt(args, file_line);
+        panic_fmt(args, file_line);
     }, "{}", expr);
 
     unsafe { intrinsics::abort() }
 }
 
 #[cold] #[inline(never)]
-#[lang="fail_bounds_check"]
-fn fail_bounds_check(file_line: &(&'static str, uint),
+#[lang="panic_bounds_check"]
+fn panic_bounds_check(file_line: &(&'static str, uint),
                      index: uint, len: uint) -> ! {
     format_args!(|args| -> () {
-        fail_fmt(args, file_line);
+        panic_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)) -> ! {
+pub fn panic_fmt(fmt: &fmt::Arguments, file_line: &(&'static str, uint)) -> ! {
     #[allow(ctypes)]
     extern {
-        #[lang = "fail_fmt"]
-        fn fail_impl(fmt: &fmt::Arguments, file: &'static str,
+        #[lang = "panic_fmt"]
+        fn panic_impl(fmt: &fmt::Arguments, file: &'static str,
                         line: uint) -> !;
 
     }
     let (file, line) = *file_line;
-    unsafe { fail_impl(fmt, file, line) }
+    unsafe { panic_impl(fmt, file, line) }
 }

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);
 //!     }

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
         }
     }

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) }
         }
     }