Trait frame_support::traits::Imbalance [−][src]
A trait for a not-quite Linear Type that tracks an imbalance.
Functions that alter account balances return an object of this trait to
express how much account balances have been altered in aggregate. If
dropped, the currency system will take some default steps to deal with
the imbalance (balances
module simply reduces or increases its
total issuance). Your module should generally handle it in some way,
good practice is to do so in a configurable manner using an
OnUnbalanced
type for each situation in which your module needs to
handle an imbalance.
Imbalances can either be Positive (funds were added somewhere without being subtracted elsewhere - e.g. a reward) or Negative (funds deducted somewhere without an equal and opposite addition - e.g. a slash or system fee payment).
Since they are unsigned, the actual type is always Positive or Negative.
The trait makes no distinction except to define the Opposite
type.
New instances of zero value can be created (zero
) and destroyed
(drop_zero
).
Existing instances can be split
and merged either consuming self
with
merge
or mutating self
with subsume
. If the target is an Option
,
then maybe_merge
and maybe_subsume
might work better. Instances can
also be offset
with an Opposite
that is less than or equal to in value.
You can always retrieve the raw balance value using peek
.
Associated Types
Loading content...Required methods
fn zero() -> Self
[src]
The zero imbalance. Can be destroyed with drop_zero
.
fn drop_zero(self) -> Result<(), Self>
[src]
Drop an instance cleanly. Only works if its self.value()
is zero.
fn split(self, amount: Balance) -> (Self, Self)
[src]
Consume self
and return two independent instances; the first
is guaranteed to be at most amount
and the second will be the remainder.
fn merge(self, other: Self) -> Self
[src]
Consume self
and an other
to return a new instance that combines
both.
fn subsume(&mut self, other: Self)
[src]
Consume an other
to mutate self
into a new instance that combines
both.
fn offset(self, other: Self::Opposite) -> Result<Self, Self::Opposite>
[src]
Consume self and along with an opposite counterpart to return a combined result.
Returns Ok
along with a new instance of Self
if this instance has a
greater value than the other
. Otherwise returns Err
with an instance of
the Opposite
. In both cases the value represents the combination of self
and other
.
fn peek(&self) -> Balance
[src]
The raw value of self.
Provided methods
fn ration(self, first: u32, second: u32) -> (Self, Self) where
Balance: From<u32> + Saturating + Div<Output = Balance>,
[src]
Balance: From<u32> + Saturating + Div<Output = Balance>,
Consume self
and return two independent instances; the amounts returned will be in
approximately the same ratio as first
:second
.
NOTE: This requires up to first + second
room for a multiply, and first + second
should
fit into a u32
. Overflow will safely saturate in both cases.
fn split_merge(self, amount: Balance, others: (Self, Self)) -> (Self, Self)
[src]
Consume self and add its two components, defined by the first component’s balance, element-wise to two pre-existing Imbalances.
A convenient replacement for split
and merge
.
fn ration_merge(
self,
first: u32,
second: u32,
others: (Self, Self)
) -> (Self, Self) where
Balance: From<u32> + Saturating + Div<Output = Balance>,
[src]
self,
first: u32,
second: u32,
others: (Self, Self)
) -> (Self, Self) where
Balance: From<u32> + Saturating + Div<Output = Balance>,
Consume self and add its two components, defined by the ratio first
:second
,
element-wise to two pre-existing Imbalances.
A convenient replacement for split
and merge
.
fn split_merge_into(self, amount: Balance, others: &mut (Self, Self))
[src]
Consume self and add its two components, defined by the first component’s balance, element-wise into two pre-existing Imbalance refs.
A convenient replacement for split
and subsume
.
fn ration_merge_into(self, first: u32, second: u32, others: &mut (Self, Self)) where
Balance: From<u32> + Saturating + Div<Output = Balance>,
[src]
Balance: From<u32> + Saturating + Div<Output = Balance>,
Consume self and add its two components, defined by the ratio first
:second
,
element-wise to two pre-existing Imbalances.
A convenient replacement for split
and merge
.
fn merge_into(self, other: &mut Self)
[src]
Consume self to mutate other
so that it combines both. Just like subsume
, only with
reversed arguments.
fn maybe_merge(self, other: Option<Self>) -> Self
[src]
Consume self
and maybe an other
to return a new instance that combines
both.
fn maybe_subsume(&mut self, other: Option<Self>)
[src]
Maybe consume an other
to mutate self
into a new instance that combines
both.