Optional Propagation
Postfix ? on an optional removes one level of it. When the optional is present, value? is its payload and evaluation carries on. When it is absent, the enclosing function returns absence at once, and nothing after the ? runs.
propagate-expr = postfix-expr "?"
The ? is written tight against its operand. Rux has no conditional operator c ? a : b; a choice between two values is an if value — see Conditional values. ? never passes an error on: a throwing call is marked with try.
Semantics
func Parse(text: char8[..]) -> int32? {
if text.length == 0 {
return none;
}
var value = 0i32;
for c in text {
if c < c8'0' || c > c8'9' {
return none;
}
value = value * 10 + ((c - c8'0') as int32);
}
return value;
}
func Sum(left: char8[..], right: char8[..]) -> int32? {
return Parse(left)? + Parse(right)?;
}
Sum("12", "30") is 42. Sum("12", "x") is none: the second ? finds absence and returns it. Each ? operand is evaluated exactly once, from left to right, so in Sum("x", "30") the second Parse never runs.
value? means the same as this match, with the absent arm leaving the function:
match value {
.Some(v) => v,
none => return none
}
Leaving through ? is an ordinary return: deferred statements run and live locals are destroyed.
The enclosing function
Absence has to go somewhere, so the function containing the ? must be able to return it. Two return types qualify:
| The function declares | Absence leaves as |
|---|---|
-> U? | none |
-> U? throws F | none, returned — the function returns, it does not throw |
U need not be the payload type of the operand; only the absence is passed on. The second form lets one function pass on both absence and errors:
func ReadLine(ok: bool) -> char8[..]? throws IoError {
if !ok {
throw IoError { code: 5 };
}
return "42";
}
func FirstNumber(ok: bool) -> int32? throws IoError {
let line = try ReadLine(ok); // an error is thrown on
let text = line?; // absence returns none
return Parse(text);
}
Absence never becomes an error. In a function whose result is not optional, ? on an optional is rejected — whether or not the function throws — because there is no absent value to return and ? will not invent an error:
error: '?' propagates the absence of 'int32?', but the enclosing function returns 'int32'
help: declare an optional result, as in '-> T?', or supply a fallback with '??'
To turn absence into an error, say which error: value ?? throw NotFound {}. See Coalescing. The same message, with 'int' at the end, is what Main gets when it returns a plain int.
One level at a time
? removes exactly one level. On an int32?? the result is an int32?: a present absence is present, so it continues as none instead of leaving.
func Inner(present: bool) -> int32?? {
return if present { .Some(none) } else { none };
}
func Peel(present: bool) -> int32? {
let once: int32? = Inner(present)?;
return once;
}
Two levels need two propagations, and they must be grouped. ?? is a single token — the coalescing operator — so Inner(present)?? is a ?? missing its right operand (error: expected an expression after '??' before ';'). Write:
func PeelBoth(present: bool) -> int32? {
return (Inner(present)?)?;
}
? and ?? compose: Inner(present)? ?? 17 returns absence for an outer none, and uses 17 for a present absence.
Restrictions
- The operand must be a native optional. Anything else is
error: 'int32' cannot be propagated with '?' because it is not an optional. On a throwing call?iserror: '?' does not propagate errors, withhelp: write 'try' before the expression to pass the error on. A variant withSomeandNonecases, or Core'sResult, is an ordinary variant:?rejects it with a note saying so, and it is matched instead. - A borrowed optional is never an operand —
?moves the payload onward, and a reference owns nothing to move:error: '?' cannot consume the borrowed value '&(int32?)' help: match the borrowed value to inspect it, or propagate an owned value ?consumes its operand. A named copyable optional is copied; a named move-only one is written(move value)?. See Copy and move.- An optional reference
&T?cannot pass its absence on with?, because the payload left in the expression could not keep its source borrowed; match it, or use??. A payload whose move is prohibited is rejected too, including when a generic is instantiated.
See also
- Optionals — the type and its patterns
- Coalescing —
??when absence has a stand-in - Passing errors on —
try, which passes an error on - Learn: Optional propagate, Absence to error
Coalescing
The ?? operator: take the value of an optional, or evaluate a fallback — a value, or a jump out with return, break, continue, throw or Panic.
Overview
Typed throws: a function declares the error it can throw with throws E, sends one with throw, and every call that can throw is marked with try.