Rust Tutorial : Error Handling
from tutorialspoint.com

Types of Errors
errors can be classified into two major categories

TypeDescriptionUsage
Recoverableerrors which can be handledResult enum
Unrecoverableerrors which cannot be handledpanic macro

a recoverable error is an error that can be corrected
a program can retry the failed operation or specify an alternate course of action when it encounters a recoverable error
recoverable errors do not cause a program to fail abruptly
an example of a recoverable error is File Not Found error

unrecoverable errors cause a program to fail abruptly
a program cannot revert to its normal state if an unrecoverable error occurs
cannot retry the failed operation or undo the error
an example of an unrecoverable error is trying to access a location beyond the end of an array

Rust does not have exceptions
returns an enum Result<T, E> for recoverable errors
calls the panic macro if the program encounters an unrecoverable error
the panic macro causes the program to exit abruptly

Panic Macro and Unrecoverable Errors
panic! macro allows a program to terminate immediately and provide feedback to the caller of the program
it should be used when a program reaches an unrecoverable state
exampleshows the program will terminate immediately when it encounters the panic! macro 
fn main() {
   panic!("Hello");
   println!("End of main"); //unreachable statement
}
output 
thread 'main' panicked at 'Hello', main.rs:3
another example of app failure causing the panic! macro
compiler will raise the error 
fn main() {
   let a = [10,20,30];
   a[10]; // invokes a panic since index 10 cannot be reached
}
output 
warning: this expression will panic at run-time
--> main.rs:4:4
  |
4 | a[10];
  | ^^^^^ index out of bounds: the len is 3 but the index is 10

$main
thread 'main' panicked at 'index out of bounds: the len 
is 3 but the index is 10', main.rs:4
note: Run with 'RUST_BACKTRACE=1' for a backtrace.
app can invoke the panic! macro if business rules are violated 
fn main() {
   let no = 13; 
   // try with odd and even
   if no%2 == 0 {
      println!("Thank you , number is even");
   } else {
      panic!("NOT_AN_EVEN"); 
   }
   println!("End of main");
}
output 
thread 'main' panicked at 'NOT_AN_EVEN', main.rs:9
note: Run with 'RUST_BACKTRACE=1' for a backtrace.
Result Enum and Recoverable Errors
enum Result can be used to handle recoverable errors
has two variants : OK and Err
T and E are generic type parameters
T represents the type of the value that will be returned in a success case within the OK variant
E represents the type of the error that will be returned in a failure case within the Err variant 
enum Result {
   OK(T),
   Err(E)
}
example returns OK(File) if the file already exists and Err(Error) if the file is not found. 
use std::fs::File;
fn main() {
   let f = File::open("main.jpg"); 
   // this file does not exist
   println!("{:?}",f);
}
output 
Err(Error { repr: Os { code: 2, message: "No such file or directory" } })
how to handle the Err variant
example handles an error returned while opening file using the match statement 
use std::fs::File;
fn main() {
   let f = File::open("main.jpg");   // main.jpg doesn't exist
   match f {
      Ok(f)=> {
         println!("file found {:?}",f);
      },
      Err(e)=> {
         println!("file not found \n{:?}",e);   // handled error
      }
   }
   println!("end of main");
}
program prints end of the main event though file was not found
the program has handled error gracefully
output 
file not found
Os { code: 2, kind: NotFound, message: "The system cannot find the file specified." }
end of main
creating the Err variant
is_even() function returns an error if the number is not an even number
the main() function handles this error 
fn main(){
   let result = is_even(13);
   match result {
      Ok(d)=>{
         println!("no is even {}",d);
      },
      Err(msg)=>{
         println!("Error msg is {}",msg);
      }
   }
   println!("end of main");
}
fn is_even(no:i32)->Result<bool,String> {
   if no%2==0 {
      return Ok(true);
   } else {
      return Err("NOT_AN_EVEN".to_string());
   }
}
output 
Error msg is NOT_AN_EVEN
end of main
unwrap() and expect()
Description
standard library contains a couple of helper methods that both enums − Result<T,E> and Option<T> implement
can use them to simplify error cases where you really do not expect things to fail
in case of success from a method, the "unwrap" function is used to extract the actual result

MethodSignatureDescription
unwrap unwrap(self): T expects self to be Ok/Some and returns the value contained within
if it is Err or None instead, it raises a panic with the contents of the error displayed
expect expect(self, msg: &str): T behaves like unwrap, except that it outputs a custom message before panicking in addition to the contents of the error

unwrap()
the unwrap() function returns the actual result an operation succeeds
returns a panic with a default error message if an operation fails
function is a shorthand for match statement 
fn main(){
   let result = is_even(10).unwrap();
   println!("result is {}",result);
   println!("end of main");
}
fn is_even(no:i32)->Result {
   if no%2==0 {
      return Ok(true);
   } else {
      return Err("NOT_AN_EVEN".to_string());
   }
}
output 
result is true
end of main
if an odd number is passed the unwrap() function will panic and return a default error message 
thread 'main' panicked at 'called 'Result::unwrap()' on 
an 'Err' value: "NOT_AN_EVEN"', libcore\result.rs:945:5
note: Run with 'RUST_BACKTRACE=1' for a backtrace
expect()
app can return a custom error message in case of a panic
expect() is similar to unwrap()
only difference is that a custom error message can be displayed using expect() 
use std::fs::File;
fn main(){
   let f = File::open("pqr.txt").expect("File not able to open");
   // file does not exist
   println!("end of main");
}
output 
thread 'main' panicked at 'File not able to open: Error { repr: Os 
{ code: 2, message: "No such file or directory" } }', src/libcore/result.rs:860
note: Run with 'RUST_BACKTRACE=1' for a backtrace.
index