Struct Value 

pub struct Value<Quantity>(/* private fields */);

A multi-asset value, generic in its asset quantities.

Quantity will typically be instantiated to either u64 or i64 depending on whether it is represent an output value, or a mint value respectively.

Implementations

impl<Quantity> Value<Quantity>

pub fn new(lovelace: u64) -> Self

Construct a new value holding only lovelaces. Use Self::with_assets to add assets if needed.

examples

assert_eq!(Value::<u64>::new(123456789), value!(123_456_789));

See also value!.

pub fn with_lovelace(&mut self, lovelace: u64) -> &mut Self

Replace the amount of lovelaces currently attached to the value.

assert_eq!(
    Value::<u64>::new(14).with_lovelace(42).lovelace(),
    42,
)

impl<Quantity: Zero> Value<Quantity>

pub fn with_assets<AssetName>( self, assets: impl IntoIterator<Item = (Hash<28>, impl IntoIterator<Item = (AssetName, Quantity)>)>, ) -> Self

where AssetName: AsRef<[u8]>,

Attach native assets to the value, replacing any existing assets already set on the value.

examples

assert_eq!(
    Value::new(123456789)
        .with_assets([
            (
                hash!("279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f"),
                [( b"SNEK", 1_000_000)]
            ),
        ]),
    value!(
        123_456_789,
        (
            "279c909f348e533da5808898f87f9a14bb2c3dfbbacccd631d927a3f",
            "534e454b",
            1_000_000,
        ),
    ),
);

impl<Quantity: Num + CheckedSub + Copy + Display> Value<Quantity>

pub fn add(&mut self, rhs: &Self) -> &mut Self

Add two values together, removing any entries that results in a null quantity. The latter is possible when quantities can take negative values (e.g. i64).

pub fn checked_sub(&mut self, rhs: &Self) -> Result<&mut Self>

Subtract the right-hand side argument from the current value; returning an error if there’s not enough of a particular quantity on the left-hand side.

examples

assert!(Value::<u64>::new(10).checked_sub(&Value::new(20)).is_err());

let lhs: Value<u64> =
  Value::default()
    .with_assets([
      (
          hash!("b558ea5ecfa2a6e9701dab150248e94104402f789c090426eb60eb60"),
          vec![( Vec::from(b"Snekkie0903"), 1), ( Vec::from(b"Snekkie3556"), 1)],
      ),
      (
          hash!("a0028f350aaabe0545fdcb56b039bfb08e4bb4d8c4d7c3c7d481c235"),
          vec![( Vec::from(b"HOSKY"), 42_000_000)],
      ),
    ]);

assert!(lhs.clone().checked_sub(&lhs).is_ok_and(|value| value == &Value::default()));

let rhs_missing_asset =
  Value::default()
    .with_assets([
      (
          hash!("b558ea5ecfa2a6e9701dab150248e94104402f789c090426eb60eb60"),
          vec![( Vec::from(b"Snekkie9999"), 1)],
      ),
      (
          hash!("a0028f350aaabe0545fdcb56b039bfb08e4bb4d8c4d7c3c7d481c235"),
          vec![( Vec::from(b"HOSKY"), 42_000_000)],
      ),
    ]);

assert!(lhs.clone().checked_sub(&rhs_missing_asset).is_err());

let rhs_missing_script =
  Value::default()
    .with_assets([
      (
          hash!("dcb56b039bfb08e4bb4d8c4d7c3c7d481c235a0028f350aaabe0545f"),
          vec![( Vec::from(b"HOSKY"), 42_000_000)],
      ),
    ]);

assert!(lhs.clone().checked_sub(&rhs_missing_script).is_err());

let rhs_missing_quantity =
  Value::default()
    .with_assets([
      (
          hash!("b558ea5ecfa2a6e9701dab150248e94104402f789c090426eb60eb60"),
          vec![( Vec::from(b"Snekkie0903"), 2)],
      ),
    ]);

assert!(lhs.clone().checked_sub(&rhs_missing_quantity).is_err());

impl<Quantity> Value<Quantity>

pub fn lovelace(&self) -> u64

pub fn assets(&self) -> &BTreeMap<Hash<28>, BTreeMap<Vec<u8>, Quantity>>

pub fn is_empty(&self) -> bool

Trait Implementations

impl<Quantity: Clone> Clone for Value<Quantity>

fn clone(&self) -> Value<Quantity>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Quantity: Debug> Debug for Value<Quantity>

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

Formats the value using the given formatter.

impl<'d, C> Decode<'d, C> for Value<u64>

fn decode(d: &mut Decoder<'d>, ctx: &mut C) -> Result<Self, Error>

Decode a value using the given Decoder.

fn nil() -> Option<Self>

If possible, return a nil value of Self.

impl<Quantity> Default for Value<Quantity>

fn default() -> Self

Returns the “default value” for a type.

impl<Quantity: Debug + Copy> Display for Value<Quantity>

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

Formats the value using the given formatter.

impl<C> Encode<C> for Value<u64>

fn encode<W: Write>( &self, e: &mut Encoder<W>, ctx: &mut C, ) -> Result<(), Error<W::Error>>

Encode a value of this type using the given Encoder.

fn is_nil(&self) -> bool

Is this value of Self a nil value?

impl From<&NonEmptyKeyValuePairs<Hash<28>, NonEmptyKeyValuePairs<Bytes, NonZeroInt>>> for Value<i64>

fn from(assets: &Multiasset<NonZeroInt>) -> Self

Converts to this type from the input type.

impl From<&Value<i64>> for Option<Multiasset<NonZeroInt>>

fn from(value: &Value<i64>) -> Self

Converts to this type from the input type.

impl From<&Value<u64>> for Value

fn from(Value: &Value<u64>) -> Self

Converts to this type from the input type.

impl From<&Value> for Value<u64>

fn from(value: &Value) -> Self

Converts to this type from the input type.

impl From<&Value> for Value<u64>

fn from(value: &Value) -> Self

Converts to this type from the input type.

impl<Quantity: PartialEq> PartialEq for Value<Quantity>

fn eq(&self, other: &Value<Quantity>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<Quantity: Eq> Eq for Value<Quantity>

impl<Quantity> StructuralPartialEq for Value<Quantity>