Function core_extensions::utils::impossible

pub unsafe fn impossible() -> !

Use this function to mark to the compiler that this branch is impossible.

This function panics when debug assertions are enabled, if debug assertions are disabled then reaching this is undefined behaviour.

For a version which doesn’t panic in debug builds but instead always causes undefined behaviour when reached you can use std::hint::unreachable_unchecked.

Safety

It is undefined behaviour for this function to be reached at runtime at all.

The compiler is free to delete any code that reaches and depends on this function, on the assumption that this branch can’t be reached.

Example

use core_extensions::BoolExt;
use core_extensions::utils::impossible;

mod non_zero{
   use super::*;
   #[derive(Debug,Copy,Clone)]
   pub struct NonZero(usize);

   impl NonZero{
       pub fn new(value:usize) -> Option<NonZero> {
           (value!=0).if_true(|| NonZero(value))
       }
       pub fn value(&self)->usize{
           self.0
       }
   }
}
use self::non_zero::NonZero;


fn div(numerator: usize, denom: Option<NonZero>) -> usize{
   let denom = match denom {
       Some(v) if v.value() == 0 => unsafe{
           // unreachable: NonZero::value() can never be 0,
           impossible()
       },
       Some(v) => v.value(),
       None => 1,
   };
   numerator / denom
}

assert_eq!(div(60, NonZero::new(0)), 60);
assert_eq!(div(60, NonZero::new(1)), 60);
assert_eq!(div(60, NonZero::new(2)), 30);
assert_eq!(div(60, NonZero::new(3)), 20);
assert_eq!(div(60, NonZero::new(4)), 15);
assert_eq!(div(60, NonZero::new(5)), 12);
assert_eq!(div(60, NonZero::new(6)), 10);