Rust Error Handling Cheat Sheet, Result manipulation functions

gistfile1.txt

# Rust Error Handling Cheatsheet - Result handling functions

| What to do with               |                                             | Code                              |
| Ok t:T                        | Err e:E                                     | r: Result<T, E>                   | Description
|-------------------------------|---------------------------------------------|-----------------------------------|----------
| ## mapping result to result   |                                             |                                   |
| t -> Result::Ok(t2)           | e -> e2                                     | r.map_or_else(|e| g(e), |t| f(t)) | Map both Ok and Err with function, function can not return Result (errror), note that Err mapping function is first (it is considered as a default like in the map_or)
| t -> t2 (Ok or Err)           | Literal (default)                           | r.map_or(literal, |t| f(t))       | Map with literal but if error, use default literal, mapping function can be any that has returns the same type as the literal, so it can also return Result
| t -> Result::Ok(t2)           | Result::Err(e) unchanged                    | r.map(|t| f(t))                   | Map ok with function, error as is, mapping can not result error
| Result of t -> t2 (Ok or Err) | Result::Err(e) unchanged                    | r.and_then(|t| f(t))              | Calls function for Ok value and propagates errors. F(t) may result Result::Err, many r.and_else().and_else()  return result of last function or first happened error
| Result::Ok(t)                 | Unchanged  Argument func Result (Ok or Err) | r.or_else(|t| f(t))               | In chain r.or_else(f).or_else(f2) calls functions until one succeeds, does not call after first success, argument must return Result type
| Argument Result (Ok or Err)   | Result::Err(e) unchanged                    | r.and(r2)                         | In chain r.and(r2).and(r3) return last ok result or first error
| Result::Ok(t)                 | Unchanged  Argument Result (Ok or Err)      | r.or(r2)                          | In chain r.or(r2).or(r3) return value of first Ok or last error, evaluates all or values
| Result::Ok(t) unchanged       |  e -> Result::Err(e2)                       | r.map_err(|e| g(e))               | Map error with g(e), ok value unchanged
|                               |                                             |                                   |
| ## extract Ok value           |                                             |                                   |
| t                             | return Result::Err(e) from function         | r?                                | If error, return from the function using this same result. Function result must be compatible
| t                             | panic                                       | r.unwrap()                        | Panics with error, may use Err as panic message
| t                             | panic with message                          | r.expect("string")                | nwrap() with given panic message
| t                             | Literal as T                                | r.unwrap_or(literal)              | Extract value or given literal as default if error
| t                             | E -> T                                      | r.unwrap_or_else(|e| g(e))        | Extract value or derive it from error with function
| t                             | Default for T                               | r.unwrap_or_default()             | Returns value or default for that type (if set)
| true                          | false                                       | r.is_ok()                         | True if ok
| Option::Some(T)               | Option::None                                | r.ok()                            | If Ok, return Option::Some(t), in case of error returns Option::None
|                               |                                             |                                   |
| ## extract error              |                                             |                                   |
| panic                         | Result::Err(e) unchanged                    | r.unwrap_err()                    | Panics, may show panic message from Ok()
| panic                         | Result::Err(e) unchanged                    | r.expect_err("message")           | Panics if ok, with set panic message, may also print value of T
| false                         | true                                        | r.is_err()                        | True if error
| Option::None                  | Option::Some(e)                             | r.err()                           | Option<E> (Ok(e) or None if no error)
|                               |                                             |                                   |
| ## convert                    |                                             |                                   |
| T<Option> -> Option::Some(T)  | E<Option> -> Option::Some(E)                | r.transpose()                     | Take Option (especially Option::None) out from Result

## Notes:
* To use r?, function must return compatible Result type
* For testing, the main fuction and tests can return Result type (Rust 2018)
* It is customary to define your own Error type for your program: pub struct Error {};
* Make special Result for your program: pub type Result<T> = result::Result<T, Error>;
* Define formatting and debug formatting for your error: impl fmt::Debug for Error { fn fmt(&self, .... }