Enum NumOpResult

Source

pub enum NumOpResult<T> {
    Valid(T),
    Error(NumOpError),
}

Expand description

Result of a mathematical operation on two numeric types.

In order to prevent overflow we provide a custom result type that is similar to the normal core::result::Result but implements mathematical operations (e.g. core::ops::Add) so that math operations can be chained ergonomically. This is very similar to how NaN works.

NumOpResult is a monadic type that contains Valid and Error (similar to Ok and Err). It supports a subset of functions similar to Result (e.g. unwrap).

§Examples

The NumOpResult type provides protection against overflow and div-by-zero.

§Overflow protection

// Example UTXO value.
let a1 = Amount::from_sat(1_000_000)?;
// And another value from some other UTXO.
let a2 = Amount::from_sat(765_432)?;
// Just an example (typically one would calculate fee using weight and fee rate).
let fee = Amount::from_sat(1_00)?;
// The amount we want to send.
let spend = Amount::from_sat(1_200_000)?;

// We can error if the change calculation overflows.
//
// For example if the `spend` value comes from the user and the `change` value is later
// used then overflow here could be an attack vector.
let _change = (a1 + a2 - spend - fee).into_result().expect("handle this error");

// Or if we control all the values and know they are sane we can just `unwrap`.
let _change = (a1 + a2 - spend - fee).unwrap();
// `NumOpResult` also implements `expect`.
let _change = (a1 + a2 - spend - fee).expect("we know values don't overflow");

§Divide-by-zero (overflow in `Div` or `Rem`)

In some instances one may wish to differentiate div-by-zero from overflow.

// Two amounts that will be added to calculate the max fee.
let a = Amount::from_sat(123).expect("valid amount");
let b = Amount::from_sat(467).expect("valid amount");
// Fee rate for transaction.
let fee_rate = FeeRate::from_sat_per_vb(1);

// Somewhat contrived example to show addition operator chained with division.
let max_fee = a + b;
let _fee = match max_fee / fee_rate {
    NumOpResult::Valid(fee) => fee,
    NumOpResult::Error(e) if e.is_div_by_zero() => {
        // Do something when div by zero.
        return Err(e);
    },
    NumOpResult::Error(e) => {
        // We separate div-by-zero from overflow in case it needs to be handled separately.
        //
        // This branch could be hit since `max_fee` came from some previous calculation. And if
        // an input to that calculation was from the user then overflow could be an attack vector.
        return Err(e);
    }
};

Variants§

§

Valid(T)

Result of a successful mathematical operation.

§

Error(NumOpError)

Result of an unsuccessful mathematical operation.

Enum NumOpResult Copy item path

§Examples

§Overflow protection

§Divide-by-zero (overflow in Div or Rem)

Variants§

Valid(T)

Error(NumOpError)

Implementations§

impl<T> NumOpResult<T>

pub fn map<U, F>(self, op: F) -> NumOpResult<U>where F: FnOnce(T) -> U,

impl<T> NumOpResult<T>where T: Debug,

pub fn expect(self, msg: &str) -> T

§Panics

pub fn unwrap(self) -> T

§Panics

pub fn unwrap_err(self) -> NumOpError

§Panics

pub fn unwrap_or(self, default: T) -> T

pub fn unwrap_or_else<F>(self, f: F) -> Twhere F: FnOnce() -> T,

pub fn ok(self) -> Option<T>

pub fn into_result(self) -> Result<T, NumOpError>

pub fn and_then<F>(self, op: F) -> NumOpResult<T>where F: FnOnce(T) -> NumOpResult<T>,

pub fn is_valid(&self) -> bool

pub fn is_error(&self) -> bool

Trait Implementations§

impl<'a> Add<&'a NumOpResult<Amount>> for &Amount

type Output = <Amount as Add<NumOpResult<Amount>>>::Output

fn add( self, rhs: &NumOpResult<Amount>, ) -> <&Amount as Add<&'a NumOpResult<Amount>>>::Output

impl Add<&NumOpResult<Amount>> for Amount

type Output = <Amount as Add<NumOpResult<Amount>>>::Output

fn add( self, rhs: &NumOpResult<Amount>, ) -> <Amount as Add<&NumOpResult<Amount>>>::Output

impl<'a> Add<&'a NumOpResult<SignedAmount>> for &SignedAmount

type Output = <SignedAmount as Add<NumOpResult<SignedAmount>>>::Output

fn add( self, rhs: &NumOpResult<SignedAmount>, ) -> <&SignedAmount as Add<&'a NumOpResult<SignedAmount>>>::Output

impl Add<&NumOpResult<SignedAmount>> for SignedAmount

type Output = <SignedAmount as Add<NumOpResult<SignedAmount>>>::Output

fn add( self, rhs: &NumOpResult<SignedAmount>, ) -> <SignedAmount as Add<&NumOpResult<SignedAmount>>>::Output

impl<'a, T> Add<&'a NumOpResult<T>> for &NumOpResult<T>where T: Copy + Add<Output = NumOpResult<T>>,

type Output = <NumOpResult<T> as Add>::Output

fn add( self, rhs: &NumOpResult<T>, ) -> <&NumOpResult<T> as Add<&'a NumOpResult<T>>>::Output

impl<T> Add<&NumOpResult<T>> for NumOpResult<T>where T: Copy + Add<Output = NumOpResult<T>>,

type Output = <NumOpResult<T> as Add>::Output

fn add( self, rhs: &NumOpResult<T>, ) -> <NumOpResult<T> as Add<&NumOpResult<T>>>::Output

impl<'a, T> Add<&'a T> for &NumOpResult<T>where T: Copy + Add<NumOpResult<T>, Output = NumOpResult<T>>,

type Output = <NumOpResult<T> as Add<T>>::Output

fn add(self, rhs: &T) -> <&NumOpResult<T> as Add<&'a T>>::Output

impl<T> Add<&T> for NumOpResult<T>where T: Copy + Add<NumOpResult<T>, Output = NumOpResult<T>>,

type Output = <NumOpResult<T> as Add<T>>::Output

fn add(self, rhs: &T) -> <NumOpResult<T> as Add<&T>>::Output

impl Add<NumOpResult<Amount>> for &Amount

type Output = <Amount as Add<NumOpResult<Amount>>>::Output

fn add( self, rhs: NumOpResult<Amount>, ) -> <&Amount as Add<NumOpResult<Amount>>>::Output

impl Add<NumOpResult<Amount>> for Amount

type Output = NumOpResult<Amount>

fn add( self, rhs: NumOpResult<Amount>, ) -> <Amount as Add<NumOpResult<Amount>>>::Output

impl Add<NumOpResult<SignedAmount>> for &SignedAmount

type Output = <SignedAmount as Add<NumOpResult<SignedAmount>>>::Output

fn add( self, rhs: NumOpResult<SignedAmount>, ) -> <&SignedAmount as Add<NumOpResult<SignedAmount>>>::Output

impl Add<NumOpResult<SignedAmount>> for SignedAmount

type Output = NumOpResult<SignedAmount>

fn add( self, rhs: NumOpResult<SignedAmount>, ) -> <SignedAmount as Add<NumOpResult<SignedAmount>>>::Output

impl<T> Add<NumOpResult<T>> for &NumOpResult<T>where T: Copy + Add<Output = NumOpResult<T>>,

type Output = <NumOpResult<T> as Add>::Output

fn add( self, rhs: NumOpResult<T>, ) -> <&NumOpResult<T> as Add<NumOpResult<T>>>::Output

impl<T> Add<T> for &NumOpResult<T>where T: Copy + Add<NumOpResult<T>, Output = NumOpResult<T>>,

type Output = <NumOpResult<T> as Add<T>>::Output

fn add(self, rhs: T) -> <&NumOpResult<T> as Add<T>>::Output

impl<T> Add<T> for NumOpResult<T>where T: Copy + Add<NumOpResult<T>, Output = NumOpResult<T>>,

type Output = NumOpResult<T>

fn add(self, rhs: T) -> <NumOpResult<T> as Add<T>>::Output

impl<T> Add for NumOpResult<T>where T: Copy + Add<Output = NumOpResult<T>>,

type Output = NumOpResult<T>

fn add(self, rhs: NumOpResult<T>) -> <NumOpResult<T> as Add>::Output

impl AddAssign<Amount> for NumOpResult<Amount>

fn add_assign(&mut self, rhs: Amount)

impl AddAssign<SignedAmount> for NumOpResult<SignedAmount>

fn add_assign(&mut self, rhs: SignedAmount)

impl<T> AddAssign<T> for NumOpResult<T>where T: AddAssign,

fn add_assign(&mut self, rhs: T)

impl AddAssign for NumOpResult<Amount>

Enum NumOpResult

§Divide-by-zero (overflow in `Div` or `Rem`)

pub fn map<U, F>(self, op: F) -> NumOpResult<U>
where F: FnOnce(T) -> U,

impl<T> NumOpResult<T>
where T: Debug,

pub fn unwrap_or_else<F>(self, f: F) -> T
where F: FnOnce() -> T,

pub fn and_then<F>(self, op: F) -> NumOpResult<T>
where F: FnOnce(T) -> NumOpResult<T>,

impl<'a, T> Add<&'a NumOpResult<T>> for &NumOpResult<T>
where T: Copy + Add<Output = NumOpResult<T>>,

impl<T> Add<&NumOpResult<T>> for NumOpResult<T>
where T: Copy + Add<Output = NumOpResult<T>>,

impl<'a, T> Add<&'a T> for &NumOpResult<T>
where T: Copy + Add<NumOpResult<T>, Output = NumOpResult<T>>,

impl<T> Add<&T> for NumOpResult<T>
where T: Copy + Add<NumOpResult<T>, Output = NumOpResult<T>>,

impl<T> Add<NumOpResult<T>> for &NumOpResult<T>
where T: Copy + Add<Output = NumOpResult<T>>,

impl<T> Add<T> for &NumOpResult<T>
where T: Copy + Add<NumOpResult<T>, Output = NumOpResult<T>>,

impl<T> Add<T> for NumOpResult<T>
where T: Copy + Add<NumOpResult<T>, Output = NumOpResult<T>>,

impl<T> Add for NumOpResult<T>
where T: Copy + Add<Output = NumOpResult<T>>,

impl<T> AddAssign<T> for NumOpResult<T>
where T: AddAssign,

impl<T> AddAssign for NumOpResult<T>
where T: AddAssign + Copy,

impl<'a, T> Arbitrary<'a> for NumOpResult<T>
where T: Arbitrary<'a>,

impl<T> Clone for NumOpResult<T>
where T: Clone,

impl<T> Debug for NumOpResult<T>
where T: Debug,