Error handling guide

[steveklabnik]

Now that we've done fail -> panic, I feel bringing back the error handling guide is a good idea. We had one long ago, but it was removed when conditions were removed.

This doesn't cover the new FromError stuff, but I feel like it's already useful in this state, so I'm sending this PR now.

[ghost]

I think it'd be better to use a different example for unreachable!(). In this one unreachable!() is used to work-around a compiler limitation and if I didn't know that when reading this, I'd be very confused by what it is you mean by something very, very wrong.

I'll try to be constructive and come up with a better example but essentially anything where unreachable!() specifies an invariant in the control flow that's not encoded in the types would do, I think.

[steveklabnik]

Is the compiler going to be able to figure this out eventually? How would it do it?

[ghost]

Most likely not, it'd after all require incorporating a complete SMT solver the way Liquid Haskell does and it'd only work for some subset of Rust. From the user's perspective it is still, however, a compiler limitation. Maybe it is useful to mention this unreachable!() use case separately, though. :)

[steveklabnik]

Then why is this a bad example? I guess I'm not seeing the distinction you're drawing here.

[ghost]

So for example in rustc we have the ast::Expr_ enum, which enumerates all the possible expression nodes. One of the variants is ExprIfLet, however, in most of the components of the compiler encountering a value of that variant is a contract violation because the if let construct is desugared at a very early stage, immediately after a program is parsed.

This is the sort of a thing that I tend to use unreachable!() for and I think it's good for: expressing paths in the control flow that should not be reached according to an implicit contract enforced in a different part of my program. This is a bit subtle but still different than using it for essentially "hacking" the compiler to accept your program.

Anyway, I am being slightly pedantic here, I just thought that we could do better here, how about something like this:

enum Event {
    Rust10ShipsIn2015
}

fn probability(_: &Event) -> f64 {
    0.95
}

fn descriptive_probability(event: Event) -> &'static str {
    match probability(&event) {
        1.00          => "certain",
        0.00          => "impossible",
        0.00 ... 0.25 => "very unlikely",
        0.25 ... 0.50 => "unlikely",
        0.50 ... 0.75 => "likely",
        0.75 ... 1.00  => "very likely",
        _ => unreachable!()
    }
}

fn main() {
    std::io::println(descriptive_probability(Rust10ShipsIn2015));
}

Feel free to cut down if you think it's a good fit.

[steveklabnik]

I changed things to add this :)

[ghost]

This looks very good, I think. I wonder if it'd also be useful to talk about downgrading panics to failures by isolating them in separate tasks. Or rather, elaborating more on the idea that tasks provide a natural boundary for panics to be isolated from other parts of a system.

[oli-obk]

why not use unwrap() directly?
see: http://doc.rust-lang.org/core/result/enum.Result.html#method.unwrap

[steveklabnik]

Ah! So, I forgot that unwrap is on Result too.

[oli-obk]

also, this guide overlaps with the result-docs. Maybe unify them?
http://doc.rust-lang.org/core/result/index.html

[steveklabnik]

It does overlap a bunch. We should pull some of the broader stuff out of the Result docs and put it here.

[steveklabnik]

This should be good to ship, r?

[ghost]

Nit: Could we maybe just point out why it is we've handled all possible cases (i.e. probability having a value between 0 and 1)?

[ghost]

@steveklabnik This looks very nice! A few more nits from me and I'm happy but maybe another pair of eyes would be useful too.

[steveklabnik]

Updated with everything but try!. I'm not opposed to it going in, but figured I'd get the rest up quick in case someone wants to look at it.

[ciarand]

s/differnet/different

[steveklabnik]

thanks, fixed

[steveklabnik]

We currently document try! in the Result module, and I think I'm just going to leave it there for now.