currency_collection.rs

Overview

This file defines the SignedCurrencyCollection struct and its associated methods for managing collections of currency amounts that may include both positive and negative values. It primarily facilitates operations on a signed collection of currencies, with support for a base currency ("grams") and multiple other currencies identified by u32 keys.

The core functionality includes constructing a signed currency collection from an unsigned CurrencyCollection, and performing arithmetic operations such as addition and subtraction on these collections. This is useful in contexts where currency amounts may increase or decrease, requiring signed arithmetic.

This file depends on external crates and modules such as num_bigint for arbitrary precision integer arithmetic, and tvm_block and tvm_types for blockchain-specific data structures and utilities.

SignedCurrencyCollection Struct

pub(crate) struct SignedCurrencyCollection {
    pub grams: BigInt,
    pub other: HashMap<u32, BigInt>,
}

• Purpose: Represents a collection of signed currency amounts.

• Fields:

  • grams: BigInt — The amount of the base currency ("grams"), stored as a BigInt to support arbitrary size and signed values.

  • other: HashMap<u32, BigInt> — A map of other currencies indexed by a u32 currency identifier, each with a signed BigInt amount.

Methods

new() -> Self

Creates a new, empty SignedCurrencyCollection with zero grams and an empty other map.

• Returns: A SignedCurrencyCollection initialized with default values (grams zero, empty other).

Usage example:

let collection = SignedCurrencyCollection::new();

from_cc(cc: &CurrencyCollection) -> tvm_types::Result<Self>

Constructs a SignedCurrencyCollection from a reference to an unsigned CurrencyCollection.

• Parameters:

  • cc: &CurrencyCollection — An unsigned currency collection containing base and other currencies.

• Returns: Result<SignedCurrencyCollection, tvm_types::Error> — a SignedCurrencyCollection on success; otherwise an error.

• Details:

  • Converts the base currency amount (grams) from u128 to BigInt.

  • Iterates over the other currencies in the CurrencyCollection by reading serialized key-value slices.

  • Keys are extracted as u32 values.

  • Values are deserialized as VarUInteger32 and converted to BigInt.

  • Populates the other map with these key-value pairs.

Usage example:

let signed_collection = SignedCurrencyCollection::from_cc(&currency_collection)?;

add(&mut self, other: &Self)

Adds another SignedCurrencyCollection to this one, updating this collection in place.

• Parameters:

  • other: &Self — The other signed currency collection to add.

• Returns: None.

• Implementation details:

  • Adds the grams value of the other collection to this one's grams.

  • For each entry in other.other, adds the amounts to the corresponding keys in self.other.

  • If a key does not exist in self.other, it is inserted with the other collection's value.

Usage example:

collection1.add(&collection2);

sub(&mut self, other: &Self)

Subtracts another SignedCurrencyCollection from this one, updating this collection in place.

• Parameters:

  • other: &Self — The other signed currency collection to subtract.

• Returns: None.

• Implementation details:

  • Subtracts the grams value of the other collection from this one's grams.

  • For each entry in other.other, subtracts the amounts from the corresponding keys in self.other.

  • If a key does not exist in self.other, it is inserted with the negated other collection's value.

Usage example:

collection1.sub(&collection2);

Implementation Details

• Uses BigInt from the num_bigint crate to handle arbitrarily large and signed currency amounts.

• Interacts with the CurrencyCollection type from tvm_block, which represents unsigned currency amounts.

• Converts unsigned currency data into signed form for flexible arithmetic operations.

• Uses the HashMap to efficiently map currency identifiers to their amounts.

• The methods add and sub ensure proper signed arithmetic on both the base currency and all other currencies in the collection.

• The from_cc method uses an iterator pattern to deserialize key-value pairs from serialized slices, demonstrating handling of low-level blockchain data structures.

Interaction with Other System Components

• CurrencyCollection: This file depends on the CurrencyCollection struct to create signed equivalents of unsigned currency holdings. It converts unsigned amounts into signed BigInt representations.

• tvm_types::Result: Uses this result type for error handling related to deserialization and data conversion.

• VarUInteger32: Utilized to deserialize variable-length unsigned integers from serialized data slices.

• The file fits into a broader system that manages blockchain currencies, supporting operations where currency amounts can be positive or negative, for example in balance calculations or transaction adjustments.

Structure Diagram

classDiagram
class SignedCurrencyCollection {
+grams: BigInt
+other: HashMap<u32, BigInt>
+new()
+from_cc(cc: &CurrencyCollection) Result<Self>
+add(other: &Self)
+sub(other: &Self)
}

This diagram illustrates the SignedCurrencyCollection struct with its properties and main methods, showing the encapsulation of signed currency data and arithmetic operations.