RFC: let-else statements

[Fishrock123]

Tracking issue: rust-lang/rust#87335

Introduce a new let PATTERN: TYPE = EXPRESSION else DIVERGING_BLOCK; construct (informally called a
let-else statement), the counterpart of if-let expressions.

If the pattern match from the assigned expression succeeds, its bindings are introduced into the
surrounding scope. If it does not succeed, it must diverge (return !, e.g. return or break).
Technically speaking, let-else statements are refutable let statements.
The expression has some restrictions, notably it may not be an ExpressionWithBlock or LazyBooleanExpression.

This RFC is a modernization of a 2015 RFC (pull request 1303) for an almost identical feature.

Rendered

---

Thanks to all the folks on Zulip who were willing to discuss this proposal once again and helped me draft this RFC.
In particular: Josh Triplett, scottmcm, Mario Carneiro, Frank Steffahn, Dirkjan Ochtman, and bstrie.

Zulip topic: https://rust-lang.zulipchat.com/#narrow/stream/213817-t-lang/topic/.60let.20pattern.20.3D.20expr.20else.20.7B.20.2E.2E.2E.20.7D.60.20statements

[burdges]

It's be more readable if else were replaced by otherwise, or really anything besides else since rust lacks then.

[lebensterben]

The example

if let Some(a) = x {
    if let Some(b) = y {
        if let Some(c) = z {
            // ...
            do_something_with(a, b, c);
            // ...
        } else {
            return Err("bad z");
        }
    } else {
        return Err("bad y");
    }
} else {
    return Err("bad x");
}

can be written as

match (x, y, z) {
  ((Some(a), Some(b), Some(c)) => do_something_with(a, b, c),
  ((Some(a), Some(b), _)) => return Err("bad z"),
  ((Some(a), _ , _)) => return Err("bad y"),
  _ => return Err("bad x"),
}

which doesn't seem bad comparing to the proposed

let Some(a) = x else {
    return Err("bad x");
};
let Some(b) = y else {
    return Err("bad y");
};
let Some(c) = z else {
    return Err("bad z");
};
// ...
do_something_with(a, b, c);

---

The real-world example can just use if-let and I don't understand

consider how the following code would look without let-else

[burdges]

You meant

match (x, y, z) {
  ((Some(a), Some(b), Some(c)) => do_something_with(a, b, c),
  ((_, _, None)) => return Err("bad z"),
  ((_, None, _)) => return Err("bad y"),
  _ => return Err("bad x"),
}

but simpler competition exists, like

let a = if let Some(a) = x { a } else { return Err("bad x"); };
...

If you're doing anything with Result conversions like Option then idiomatic Rust code goes

let a = x.ok_or("bad x) ?;
let b = y.ok_or("bad y) ?;
let c = z.ok_or("bad z) ?;
do_something_with(a, b, c);

or

do_something_with(
    x.ok_or("bad x) ?,
    y.ok_or("bad y) ?,
    z.ok_or("bad z) ?
)

I'd say remove Option entirely from the RFC to avoid confusion. Another enum like Cow works better, maybe combined with Vec::reserve instead of returns because otherwise

let owned_or = |moo,err| if moo.is_owned() { Ok(moo.into_owned()) } else { Err(err) };
do_something_with(
    x.owned_or("bad x) ?,
    y.owned_or("bad y) ?,
    z.owned_or("bad z) ?
)

In reality, this shortcut would exist exclusively for custom enums and should probably never be used with anything from std.

[lebensterben]

@burdges
let a = if let Some(a) = x { a } else { return Err("bad x"); }; is not simpler.
When it's properly formatted it takes more lines than mine example, which is bad if concise source code is an objective.

Option doesn't cause any particular confusion to me. What I'm confused is why the proposed let-else is considered better than if-let and match.

If there's one refutable pattern to match, then if-let is good enough and let-else adds no utility to it.
If there are multiple refutable patterns to match, just use match and you will get concise and readable code.

[Fishrock123]

match (x, y, z) {
  ((Some(a), Some(b), Some(c)) => do_something_with(a, b, c),
  ((Some(a), Some(b), _)) => return Err("bad z"),
  ((Some(a), _ , _)) => return Err("bad y"),
  _ => return Err("bad x"),
}

That basic example may need to be improved a bit. Often times in practical use there is other code between the previous and next if statement, which cannot be represented by this match example. Keep in mind no example can perfectly represent all the possibilities in real-world code, which is why there are multiple examples.

If there's one refutable pattern to match, then if-let is good enough and let-else adds no utility to it.

It can in fact add practical utility. Please see the practical refactor section of the RFC.

If you're doing anything with Result conversions like Option then idiomatic Rust code goes

This is already covered in the RFC in more detail. See the alternatives section which notes that ok_or/ok_or_else + ? is great for Result/Option but untenable for other enums, particularly non-stdlib enums.

[lebensterben]

Also consider the following case

enum Fruit {
    Apple(u32),
    Banana(u32),
}

struct AppleJuice;

fn make_apple_juice(fruit: &Fruit) -> Result<AppleJuice, String> {
    match fruit {
        Fruit::Apple(v) => Ok(AppleJuice),
        Fruit::Banana(v) => Err(String::from("Require apple, found %s bananas", v)),
    }
}

This cannot be written with the proposed let-else construct or if-let construct.
So usage of let-else is really limited.

[Fishrock123]

enum Fruit {
    Apple(u32),
    Banana(u32),
}

Enums with multiple value-bearing variants do not necessarily need or want other variant values to be accessed in case of a failed match. The examples section does cover this. Also if it helps, the GeoJson enum used in the one example is this: https://docs.rs/geojson/0.22.2/geojson/enum.GeoJson.html

[lebensterben]

@Fishrock123

It can in fact add practical utility. Please see the practical refactor section of the RFC.

This refactor is not a fair comparison.
How's

let GeoJson::FeatureCollection(features) = geojson else {
    return Err(format_err_status!(
        422,
        "GeoJSON was not a Feature Collection",
    ));
};

any better than

let features = if let GeoJson::FeatureCollection(features) = geojson {
    features
} else {
    return Err(format_err_status!(
        422,
        "GeoJSON was not a Feature Collection",
    ));
};

It merely removed two lines. Does this justify adding the new constuct let-else?

[Fishrock123]

Does this justify adding the new constuct let-else?

let x = if let Pattern(x) = y { x } else {
    // return or something
};

Any real-world code I've seen uses match over the if let such as the above. The if let like this reads especially poor.
It would be better if people were not likely to use the same variable name in the intermediate binding, but all examples that exist seem to do that.

That being said, yes I do think the few lines of elimination bring enhanced clarity and newcomer discoverability, especially for something which can be pretty common, and which desugars into something pretty simple without much complexity.

Quoting myself from the RFC:

While that refactor was positive, it should be noted that such alternatives were unclear the authors when they were less experienced rust programmers, and also that the resulting match code includes syntax boilerplate (e.g. the block) that could theoretically be reduced today but also interferes with rustfmt's rules:

[joshtriplett]

@lebensterben wrote:

can be written as

match (x, y, z) {
  ((Some(a), Some(b), Some(c)) => do_something_with(a, b, c),
  ((Some(a), Some(b), _)) => return Err("bad z"),
  ((Some(a), _ , _)) => return Err("bad y"),
  _ => return Err("bad x"),
}

This is assuming that the actual expressions involved in y and z (which are examples) don't involve any previous bindings. If y is actually f(x) this doesn't work. And that's a common pattern: refutably bind x or fail, then refutably bind y or fail...

[nielsle]

The best use case for let-else is probably something like the following (where foo and bar are functions with side effects)

let Some(a) = foo() else {
    log("Bad foo");
    return Err("foo failed");
};

let Some(b) = bar() else {
    log("Bad bar");
    return Err("bar failed");
};

This example can also be rewritten using if-else or map_err()? or two separate match statements, but admittedly the version with let-else is slightly prettier.

[burdges]

Does this justify adding the new constuct let-else?

I think only the word else adds confusion here. If another word gets used, ala let x = y otherwise { z };, then one conceptualizes this roughly like let x = y? ala let x = y otherwise { return None; }; or whatever.

[Pzixel]

If the pattern match from the assigned expression succeeds, its bindings are introduced into the
surrounding scope. If it does not succeed, it must diverge (return !, e.g. return or break).

Should this be the case? From C# experience we know that it may be used like this:

if (new object() is not int x) {
	x = 10;
}
Console.WriteLine(x); // prints 10

So if value is NOT matched then if block gets executed.

I think that it coul be applied here as well: instead of returning/breaking/... it may actually set the variable. You may do this with unwrap_or_else(..) combinator but sometimes it's quite awkward to use.

[mqudsi]

The C# sample is closer to a match block (indeed, that's referred to as pattern matching in C#).

if (new object() is not int x) {
	x = 10;
}
Console.WriteLine(x); // prints 10

is equivalent to rust's

let x = match Object::new() {
    Some(x) => x,
    None => 10,
}

(Except it's not an Option<T> but rather an unboxing operation which isn't something rust supports.)

The important bit is that commenting out x = 10; will result in a hard compile-time error ("Use of unassigned local variable x").

[Pzixel]

Nope, it's not the equivalent. Your rust code is equivalent to

var x = (new object()) switch {
  int x => x,
  _ => 10
};

But it's not what I've written. This code creates a scope (and indentation) which is what we're trying to avoid here. Consider that instead of Console.WriteLine there are dozens of lines. Instead of linear happy path with guardian checks you get a huge nested pile of code which isn't pleasant to read.

The important bit is that commenting out x = 10; will result in a hard compile-time error ("Use of unassigned local variable x").

Right, this is what I meant, but I missed this, thanks. Rust shouldn't require block do diverge but it should treat binding as unassigned instead (because well it is), and that's it

[mqudsi]

@Pzixel I wasn't disagreeing with you and I wasn't posting an equivalent developer UX but rather an equivalent compilation to clarify the behavior for those not familiar with C#. Especially the bit about C# not letting you just escape the typeguard willy-nilly, for those that don't/didn't realize how strictly typed C# was in that regard.

[digama0]

The approach with x = 10 in the body was discussed and rejected earlier in the zulip thread. You can't just use 10 in the body because this gets messy when there are multiple variables being bound in the pattern, and while x = 10 works, it is misleading in the very common case that the newly introduced variable shadows another one:

let x: Result<usize, usize> = Err(2);
let Ok(x) = x else {
    x = x.unwrap_err(); // error: using uninitialized variable `x: usize`
};

[Pzixel]

I'm not sure how is it misleading. It works just in the same way:

if (default(int[]) is not { Length: 5, LongLength: var y } x)
{
	x = new int[] { 10 };
	y = 1;
}
Console.WriteLine(x);
Console.WriteLine(y);

Is variable was not set it's just unbinded and causes CS0165 Use of unassigned local variable if you're trying to use it. It makes total sense to me.

In your example you won't be able to use the shadowed x because, well, it's shadowed but I don't see this as a problem. This approaches allows some use cases that current approach doesn't but not the other way around. This code wouldn't be valid with current specification as well. But approach with unitialized variables allows some subset of operations that is forbidden with "should diverge" approach

[teohhanhui]

What does this do that if let ... else doesn't provide?

EDIT: Uhh, okay, it doesn't create another level of nesting.

[digama0]

In your example you won't be able to use the shadowed x because, well, it's shadowed but I don't see this as a problem. This approaches allows some use cases that current approach doesn't but not the other way around. This code wouldn't be valid with current specification as well. But approach with unitialized variables allows some subset of operations that is forbidden with "should diverge" approach

What is misleading is that there are two somewhat reasonable options for the binding structure, and people will have different predispositions to one or the other, and if they stumble on some code like this without having read the RFC carefully they might be mislead. Personally, I am predisposed to expect that a variable should not be in scope in a different branch from where it is introduced - nothing else in rust is like that - so in let Some(x) = ... else { <here> }; I would not expect x to be in scope. It isn't in scope in if let which is the nearest other grammar construction in rust, so even for people who have come to learn the rules it will feel inconsistent.

The idea behind forced divergence here is that you don't have to make a choice - you don't need to know what happens after the block completes, where it goes and what values are assigned - because it never gets there and we ensure this is always the case.

The situation with using the shadowed variable seems rather likely to me, for example:

let Foo::Bar(x) = x else { panic!("unexpected: {:?}", x) };

I'm using only rust examples here, not C#, because I think the intuitions might differ, since unboxing has a significantly different syntactic expression, and I think shadowing is quite a bit less common. (Actually I just tested, and variable shadowing in the direct sense of int x = 1; int x = 2; is outright banned, and there are more complex shadowing situations that are allowed but strongly discouraged. So indeed the intuitions will be very different coming from a C# background.)

[Pzixel]

I'm using only rust examples here, not C#, because I think the intuitions might differ, since unboxing has a significantly different syntactic expression, and I think shadowing is quite a bit less common.

C# has (un)boxing and stuff, right, but this is beside the point. What I'm saying that assigning variable that wasn't bind may be useful. Of course if you want to do so you need to assign this to another name otherwise the old one would be shadowed.

I think both approaches has pros and cons, and I'm sharing my usage examples to help making proper decision.

(Actually I just tested, and variable shadowing in the direct sense of int x = 1; int x = 2; is outright banned, and there are more complex shadowing situations that are allowed but strongly discouraged. So indeed the intuitions will be very different coming from a C# background.)

This is also true but also beside the point: C# doesn't have shadowing of locals but we still can imagine how would it work in Rust. For example:

let Foo::Bar(x) = x else { panic!("unexpected: {:?}", x) }; // is not allowed: x is not assigned
let Foo::Bar(y) = x else { panic!("unexpected: {:?}", x) }; // ok
let Foo::Bar(y) = x else { y = 15 }; // ok

[Fishrock123]

Please see the fallback assignment part of the RFC discussed under rationale and also mentioned in future possibilities:
https://github.com/Fishrock123/rfcs/blob/let-else/text/0000-let-else.md#else-block-fall-back-assignment &
https://github.com/Fishrock123/rfcs/blob/let-else/text/0000-let-else.md#fall-back-assignment

[Pzixel]

I'm not sure if this issue was closed for good but I have a question if expansion of the syntax is considered to be implemented. I was actively using let else for cases when I don't care about errors, and it worked wonders, until I realized that even I Don't care about it I still want to log it. So for example:

let Ok((ws_stream, _)) = tokio_tungstenite::connect_async(&url).await else {
   tracing::warn!("[wss] Cannot connect to RPC endpoint. Waiting and reconnecting");
   tokio::time::sleep(reconnect_delay).await;
   continue;
 };

It's cool and beans but at some point you realize that you want to know why it is failing, so in order to do so you need to write:

let ws_stream = match tokio_tungstenite::connect_async(&url).await {
    Ok((ws_stream, _)) => ws_stream,
    Err(e) => {
        tracing::warn!("[wss] Cannot connect to RPC endpoint: {}. Waiting and reconnecting", e);
        tokio::time::sleep(reconnect_delay).await;
        continue;
    }
};

Which is quite verbose for such a simple task. Add some more logic and suddenly out of the function for 100 lines you have 10-20 eaten just by the following pattern, with a lot of foos like in let foo = match Ok(foo) => foo.

Approach with map_err looks really bad for any real error handling:

let Ok((ws_stream, _)) = tokio_tungstenite::connect_async(&url).await
    .map_err(|e| tracing::warn!("[wss] Cannot connect to RPC endpoint: {}. Waiting and reconnecting", e)) else {
   tokio::time::sleep(reconnect_delay).await;
   continue;
 };

It also splits error handling in multiple blocks which is harder to read (and write).

So for now the only way to use let else is when you don't care about non-matched value at all, which isn't the case in almost every scenario except for Option where you just know in advance it is None (just because of the type inhabitance).

Honestly I would like to have an optional binding so both programs I wrote below would be accepted:

let Ok((ws_stream, _)) = tokio_tungstenite::connect_async(&url).await else {
   tracing::warn!("[wss] Cannot connect to RPC endpoint. Waiting and reconnecting");
   tokio::time::sleep(reconnect_delay).await;
   continue;
 };

and

let Ok((ws_stream, _)) = tokio_tungstenite::connect_async(&url).await else e {
   tracing::warn!("[wss] Cannot connect to RPC endpoint: {:?}. Waiting and reconnecting", e);
   tokio::time::sleep(reconnect_delay).await;
   continue;
 };

Since it is currently an invalid program this feature can be added in backward-compatible manner. I know this was covered in https://github.com/Fishrock123/rfcs/blob/let-else/text/0000-let-else.md#let-else-match but I suggest to reiterate and see if it can be added as an optional feature.

[clarfonthey]

One other thing to consider as a limitation of let-else is the fact that the new destructuring assignment doesn't work with it, meaning that if you wanted to do the same as the above without the let (assigning to an existing ws_stream variable, and not binding a new one), it would not be possible.

[Fishrock123]

@Pzixel The answer to this is suggested to be to use match as you mentioned.

The problem with e.g. let PATTERN: TYPE = EXPRESSION else (PATTERN) DIVERGING_BLOCK; is that, is short, it implicitly can only work for patterns with two possible variants.

There could be an argument that this is still useful, however it mostly seems that this happens with Option and Result and in my experience there is usually a better / more idiomatic option available (via chaining operations, ?, or match). I do not think it would be useful to extend support for this to multiple else clauses - the code is not going to be more succinct than just using match.

I do agree with this sentiment regarding map_err:

It also splits error handling in multiple blocks which is harder to read (and write).