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

1 files changed, 22 insertions, 22 deletions

diff --git a/src/doc/reference.md b/src/doc/reference.md
index f723bbe30b7..fab46971230 100644
--- a/src/doc/reference.md
+++ b/src/doc/reference.md
@@ -818,15 +818,15 @@ mod math {
     type Complex = (f64, f64);
     fn sin(f: f64) -> f64 {
         /* ... */
-# fail!();
+# panic!();
     }
     fn cos(f: f64) -> f64 {
         /* ... */
-# fail!();
+# panic!();
     }
     fn tan(f: f64) -> f64 {
         /* ... */
-# fail!();
+# panic!();
     }
 }
 ```
@@ -1195,12 +1195,12 @@ output slot type would normally be. For example:
 ```
 fn my_err(s: &str) -> ! {
     println!("{}", s);
-    fail!();
+    panic!();
 }
 ```
 
 We call such functions "diverging" because they never return a value to the
-caller. Every control path in a diverging function must end with a `fail!()` or
+caller. Every control path in a diverging function must end with a `panic!()` or
 a call to another diverging function on every control path. The `!` annotation
 does *not* denote a type. Rather, the result type of a diverging function is a
 special type called $\bot$ ("bottom") that unifies with any type. Rust has no
@@ -1213,7 +1213,7 @@ were declared without the `!` annotation, the following code would not
 typecheck:
 
 ```
-# fn my_err(s: &str) -> ! { fail!() }
+# fn my_err(s: &str) -> ! { panic!() }
 
 fn f(i: int) -> int {
    if i == 42 {
@@ -2260,7 +2260,7 @@ These types help drive the compiler's analysis
   : Allocate memory on the exchange heap.
 * `closure_exchange_malloc`
   : ___Needs filling in___
-* `fail_`
+* `panic`
   : Abort the program with an error.
 * `fail_bounds_check`
   : Abort the program with a bounds check error.
@@ -2867,11 +2867,11 @@ be assigned to.
 
 Indices are zero-based, and may be of any integral type. Vector access is
 bounds-checked at run-time. When the check fails, it will put the task in a
-_failing state_.
+_panicked state_.
 
 ```{should-fail}
 ([1, 2, 3, 4])[0];
-(["a", "b"])[10]; // fails
+(["a", "b"])[10]; // panics
 ```
 
 ### Unary operator expressions
@@ -3301,9 +3301,9 @@ enum List<X> { Nil, Cons(X, Box<List<X>>) }
 let x: List<int> = Cons(10, box Cons(11, box Nil));
 
 match x {
-    Cons(_, box Nil) => fail!("singleton list"),
+    Cons(_, box Nil) => panic!("singleton list"),
     Cons(..)         => return,
-    Nil              => fail!("empty list")
+    Nil              => panic!("empty list")
 }
 ```
 
@@ -3374,7 +3374,7 @@ match x {
         return;
     }
     _ => {
-        fail!();
+        panic!();
     }
 }
 ```
@@ -3396,7 +3396,7 @@ fn is_sorted(list: &List) -> bool {
         Cons(x, ref r @ box Cons(_, _)) => {
             match *r {
                 box Cons(y, _) => (x <= y) && is_sorted(&**r),
-                _ => fail!()
+                _ => panic!()
             }
         }
     }
@@ -3460,7 +3460,7 @@ may refer to the variables bound within the pattern they follow.
 let message = match maybe_digit {
   Some(x) if x < 10 => process_digit(x),
   Some(x) => process_other(x),
-  None => fail!()
+  None => panic!()
 };
 ```
 
@@ -4092,7 +4092,7 @@ cause transitions between the states. The lifecycle states of a task are:
 
 * running
 * blocked
-* failing
+* panicked 
 * dead
 
 A task begins its lifecycle &mdash; once it has been spawned &mdash; in the
@@ -4104,21 +4104,21 @@ it makes a blocking communication call. When the call can be completed &mdash;
 when a message arrives at a sender, or a buffer opens to receive a message
 &mdash; then the blocked task will unblock and transition back to *running*.
 
-A task may transition to the *failing* state at any time, due being killed by
-some external event or internally, from the evaluation of a `fail!()` macro.
-Once *failing*, a task unwinds its stack and transitions to the *dead* state.
+A task may transition to the *panicked* state at any time, due being killed by
+some external event or internally, from the evaluation of a `panic!()` macro.
+Once *panicking*, a task unwinds its stack and transitions to the *dead* state.
 Unwinding the stack of a task is done by the task itself, on its own control
 stack. If a value with a destructor is freed during unwinding, the code for the
 destructor is run, also on the task's control stack. Running the destructor
 code causes a temporary transition to a *running* state, and allows the
 destructor code to cause any subsequent state transitions. The original task
-of unwinding and failing thereby may suspend temporarily, and may involve
+of unwinding and panicking thereby may suspend temporarily, and may involve
 (recursive) unwinding of the stack of a failed destructor. Nonetheless, the
 outermost unwinding activity will continue until the stack is unwound and the
 task transitions to the *dead* state. There is no way to "recover" from task
-failure. Once a task has temporarily suspended its unwinding in the *failing*
-state, failure occurring from within this destructor results in *hard* failure.
-A hard failure currently results in the process aborting.
+panics. Once a task has temporarily suspended its unwinding in the *panicking*
+state, a panic occurring from within this destructor results in *hard* panic.
+A hard panic currently results in the process aborting.
 
 A task in the *dead* state cannot transition to other states; it exists only to
 have its termination status inspected by other tasks, and/or to await