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(100)?;
// 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");

§Failure in chained operations

In some instances one may wish to differentiate one math op failure from another.

// 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_u32(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.operation().is_division() => {
        // Do something when division fails (div by zero or perhaps MIN / -1).
        return Err(e);
    },
    NumOpResult::Error(e) => {
        // And something else if the addition overflowed.
        //
        // 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);
    }
};

If both operands of a binary op are already Error, only the left-hand error is returned.

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

§Failure in chained operations

Variants§

Valid(T)

Error(NumOpError)

Implementations§

impl<T> NumOpResult<T>

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

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

§Panics

pub fn unwrap(self) -> T

§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 from_result(result: Result<T, NumOpError>) -> Self

pub fn and_then<F>(self, op: F) -> Selfwhere F: FnOnce(T) -> Self,

pub fn is_valid(&self) -> bool

pub fn is_error(&self) -> bool

impl<T: Debug> NumOpResult<T>

pub fn unwrap_err(self) -> NumOpError

§Panics

Trait Implementations§

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

type Output = NumOpResult<T>

fn add(self, rhs: Self) -> Self::Output

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

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

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

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

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

fn add(self, rhs: &NumOpResult<SignedAmount>) -> Self::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>) -> Self::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) -> Self::Output

impl Add<&NumOpResult<Amount>> for Amount

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

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

impl Add<&NumOpResult<SignedAmount>> for SignedAmount

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

fn add(self, rhs: &NumOpResult<SignedAmount>) -> Self::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>) -> Self::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) -> Self::Output

impl Add<NumOpResult<Amount>> for Amount

type Output = NumOpResult<Amount>

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

impl Add<NumOpResult<Amount>> for &Amount

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

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

impl Add<NumOpResult<SignedAmount>> for SignedAmount

type Output = NumOpResult<SignedAmount>

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

impl Add<NumOpResult<SignedAmount>> for &SignedAmount

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

fn add(self, rhs: NumOpResult<SignedAmount>) -> Self::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>) -> Self::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) -> Self::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) -> Self::Output

impl AddAssign for NumOpResult<Amount>

fn add_assign(&mut self, rhs: Self)

impl AddAssign for NumOpResult<SignedAmount>

fn add_assign(&mut self, rhs: Self)

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

fn add_assign(&mut self, rhs: Self)

Enum NumOpResult

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

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

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

impl<'a, T> Add<&'a 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<&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<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>>,