Struct massa_models::amount::Amount

pub struct Amount(u64);

A structure representing a decimal Amount of coins with safe operations this allows ensuring that there is never an uncontrolled overflow or precision loss while providing a convenient decimal interface for users The underlying u64 raw representation if a fixed-point value with factor AMOUNT_DECIMAL_FACTOR The minimal value is 0 and the maximal value is 18446744073.709551615(std::u64::MAX/1e9)

Tuple Fields

0: u64

Implementations

impl Amount

pub const MIN: Amount = _

Minimum amount

pub const MAX: Amount = _

Maximum amount

pub const fn zero() -> Self

Create a zero Amount

fn to_decimal(self) -> Decimal

Convert to decimal

fn from_decimal(dec: Decimal) -> Result<Self, ModelsError>

Create an Amount from a Decimal

pub const fn const_init(mantissa: u64, scale: u32) -> Self

Create an Amount from the form mantissa / (10^scale) in a const way. WARNING: Panics on any error. Used only for constant initialization.

let amount_1: Amount = Amount::from_str("0.042").unwrap();
let amount_2: Amount = Amount::const_init(42, 3);
assert_eq!(amount_1, amount_2);
let amount_1: Amount = Amount::from_str("1000").unwrap();
let amount_2: Amount = Amount::const_init(1000, 0);
assert_eq!(amount_1, amount_2);

pub fn to_mantissa_scale(&self) -> (u64, u32)

Returns the value in the (mantissa, scale) format where amount = mantissa * 10^(-scale)

let amount = Amount::from_str("0.123456789").unwrap();
let (mantissa, scale) = amount.to_mantissa_scale();
assert_eq!(mantissa, 123456789);
assert_eq!(scale, AMOUNT_DECIMAL_SCALE);

pub fn from_mantissa_scale( mantissa: u64, scale: u32, ) -> Result<Self, ModelsError>

Creates an amount in the format mantissa*10^(-scale).

let a = Amount::from_mantissa_scale(123, 2).unwrap();
assert_eq!(a.to_string(), "1.23");
let a = Amount::from_mantissa_scale(123, 100);
assert!(a.is_err());

pub const fn to_raw(&self) -> u64

Obtains the underlying raw u64 representation Warning: do not use this unless you know what you are doing because the raw value does not take the AMOUNT_DECIMAL_FACTOR into account.

pub const fn from_raw(raw: u64) -> Self

constructs an Amount from the underlying raw u64 representation Warning: do not use this unless you know what you are doing because the raw value does not take the AMOUNT_DECIMAL_FACTOR into account In most cases, you should be using Amount::from_str("11.23")

pub fn saturating_add(self, amount: Amount) -> Self

safely add self to another amount, saturating the result on overflow

pub fn saturating_sub(self, amount: Amount) -> Self

safely subtract another amount from self, saturating the result on underflow

pub fn is_zero(&self) -> bool

returns true if the amount is zero

pub fn checked_sub(self, amount: Amount) -> Option<Self>

safely subtract another amount from self, returning None on underflow

let amount_1 : Amount = Amount::from_str("42").unwrap();
let amount_2 : Amount = Amount::from_str("7").unwrap();
let res : Amount = amount_1.checked_sub(amount_2).unwrap();
assert_eq!(res, Amount::from_str("35").unwrap())

pub fn checked_add(self, amount: Amount) -> Option<Self>

safely add self to another amount, returning None on overflow

let amount_1 : Amount = Amount::from_str("42").unwrap();
let amount_2 : Amount = Amount::from_str("7").unwrap();
let res : Amount = amount_1.checked_add(amount_2).unwrap();
assert_eq!(res, Amount::from_str("49").unwrap())

pub fn checked_mul_u64(self, factor: u64) -> Option<Self>

safely multiply self with a u64, returning None on overflow

let amount_1 : Amount = Amount::from_str("42").unwrap();
let res : Amount = amount_1.checked_mul_u64(7).unwrap();
assert_eq!(res, Amount::from_str("294").unwrap())

pub const fn saturating_mul_u64(self, factor: u64) -> Self

safely multiply self with a u64, saturating the result on overflow

let amount_1 : Amount = Amount::from_str("42").unwrap();
let res : Amount = amount_1.saturating_mul_u64(7);
assert_eq!(res, Amount::from_str("294").unwrap());

pub fn checked_div_u64(self, factor: u64) -> Option<Self>

safely divide self by a u64, returning None if the factor is zero

let amount_1 : Amount = Amount::from_str("42").unwrap();
let res : Amount = amount_1.checked_div_u64(7).unwrap();
assert_eq!(res, Amount::from_str("6").unwrap());

pub fn checked_div(self, divisor: Self) -> Option<u64>

safely divide self by an amount, returning None if the divisor is zero

let amount_1 : Amount = Amount::from_str("42").unwrap();
let amount_2 : Amount = Amount::from_str("7").unwrap();
let res : u64 = amount_1.checked_div(amount_2).unwrap();
assert_eq!(res, 6);

pub fn checked_rem(&self, divisor: &Amount) -> Option<Amount>

compute self % divisor, return None if divisor is zero

let amount_1 : Amount = Amount::from_str("42").unwrap();
let amount_2 : Amount = Amount::from_str("10").unwrap();
let res : Amount = amount_1.checked_rem(&amount_2).unwrap();
assert_eq!(res, Amount::from_str("2").unwrap());

pub fn checked_rem_u64(&self, divisor: u64) -> Option<Amount>

compute self % divisor, return None if divisor is zero

let amount_1 : Amount = Amount::from_str("42").unwrap();
let res : Amount = amount_1.checked_rem_u64(40000000000).unwrap();
assert_eq!(res, Amount::from_str("2").unwrap());

Trait Implementations

impl Clone for Amount

fn clone(&self) -> Amount

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Amount

Use display implementation in debug to get the decimal representation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Amount

fn default() -> Amount

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Amount

fn deserialize<D>(deserializer: D) -> Result<Amount, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Deserializer<Amount> for AmountDeserializer

fn deserialize<'a, E: ParseError<&'a [u8]> + ContextError<&'a [u8]>>( &self, buffer: &'a [u8], ) -> IResult<&'a [u8], Amount, E>

Example

use massa_models::amount::{Amount, AmountSerializer, AmountDeserializer};
use massa_serialization::{Serializer, Deserializer, DeserializeError};
use std::str::FromStr;
use std::ops::Bound::Included;

let amount = Amount::from_str("11.111").unwrap();
let serializer = AmountSerializer::new();
let deserializer = AmountDeserializer::new(Included(Amount::MIN), Included(Amount::MAX));
let mut serialized = vec![];
serializer.serialize(&amount, &mut serialized).unwrap();
let (rest, amount_deser) = deserializer.deserialize::<DeserializeError>(&serialized).unwrap();
assert!(rest.is_empty());
assert_eq!(amount_deser, amount);

impl Display for Amount

display an Amount in decimal string form (like “10.33”)

let value = Amount::from_str("11.111").unwrap();
assert_eq!(format!("{}", value), "11.111")

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Amount> for NativeAmount

fn from(value: Amount) -> Self

Converts to this type from the input type.

impl FromStr for Amount

build an Amount from decimal string form (like “10.33”) note that this will fail if the string format is invalid or if the conversion would cause an overflow, underflow or precision loss

assert!(Amount::from_str("11.1").is_ok());
assert!(Amount::from_str("11.1111111111111111111111").is_err());
assert!(Amount::from_str("1111111111111111111111").is_err());
assert!(Amount::from_str("-11.1").is_err());
assert!(Amount::from_str("abc").is_err());

type Err = ModelsError

The associated error which can be returned from parsing.

fn from_str(str_amount: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Ord for Amount

fn cmp(&self, other: &Amount) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Amount

fn eq(&self, other: &Amount) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Amount

fn partial_cmp(&self, other: &Amount) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Amount

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Serializer<Amount> for AmountSerializer

fn serialize( &self, value: &Amount, buffer: &mut Vec<u8>, ) -> Result<(), SerializeError>

Example

use massa_models::amount::{Amount, AmountSerializer};
use massa_serialization::Serializer;
use std::str::FromStr;
use std::ops::Bound::Included;

let amount = Amount::from_str("11.111").unwrap();
let serializer = AmountSerializer::new();
let mut serialized = vec![];
serializer.serialize(&amount, &mut serialized).unwrap();

impl Copy for Amount

impl Eq for Amount

impl StructuralPartialEq for Amount