Struct Coins

pub struct Coins(/* private fields */);

A collection of coins, similar to Cosmos SDK’s sdk.Coins struct.

Differently from sdk.Coins, which is a vector of sdk.Coin, here we implement Coins as a BTreeMap that maps from coin denoms to Coin. This has a number of advantages:

• coins are naturally sorted alphabetically by denom
• duplicate denoms are automatically removed
• cheaper for searching/inserting/deleting: O(log(n)) compared to O(n)

Implementations

impl Coins

pub fn to_vec(&self) -> Vec<Coin>

Conversion to Vec, while NOT consuming the original object.

This produces a vector of coins that is sorted alphabetically by denom with no duplicate denoms.

pub fn into_vec(self) -> Vec<Coin>

Conversion to Vec, consuming the original object.

This produces a vector of coins that is sorted alphabetically by denom with no duplicate denoms.

pub fn len(&self) -> usize

Returns the number of different denoms in this collection.

pub fn is_empty(&self) -> bool

Returns true if this collection contains no coins.

pub fn denoms(&self) -> Vec<String>

Returns the denoms as a vector of strings. The vector is guaranteed to not contain duplicates and sorted alphabetically.

pub fn amount_of(&self, denom: &str) -> Uint128

Returns the amount of the given denom or zero if the denom is not present.

pub fn contains_only(&self, denom: &str) -> Option<Uint128>

Returns the amount of the given denom if and only if this collection contains only the given denom. Otherwise None is returned.

Examples

use cosmwasm_std::{Coin, Coins, coin};

let coins: Coins = [coin(100, "uatom")].try_into().unwrap();
assert_eq!(coins.contains_only("uatom").unwrap().u128(), 100);
assert_eq!(coins.contains_only("uluna"), None);

use cosmwasm_std::{Coin, Coins, coin};

let coins: Coins = [coin(100, "uatom"), coin(200, "uusd")].try_into().unwrap();
assert_eq!(coins.contains_only("uatom"), None);

pub fn add(&mut self, coin: Coin) -> StdResult<()>

Adds the given coin to this Coins instance. Errors in case of overflow.

pub fn sub(&mut self, coin: Coin) -> StdResult<()>

Subtracts the given coin from this Coins instance. Errors in case of overflow or if the denom is not present.

pub fn iter(&self) -> CoinsIter<'_>

Returns an iterator over the coins.

Examples

let mut coins = Coins::default();
coins.add(coin(500, "uluna")).unwrap();
coins.add(coin(1000, "uatom")).unwrap();
let mut iterator = coins.iter();

let uatom = iterator.next().unwrap();
assert_eq!(uatom.denom, "uatom");
assert_eq!(uatom.amount.u128(), 1000);

let uluna = iterator.next().unwrap();
assert_eq!(uluna.denom, "uluna");
assert_eq!(uluna.amount.u128(), 500);

assert_eq!(iterator.next(), None);

Trait Implementations

impl Clone for Coins

fn clone(&self) -> Coins

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Coins

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

Formats the value using the given formatter.

impl Default for Coins

fn default() -> Coins

Returns the “default value” for a type.

impl Display for Coins

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

Formats the value using the given formatter.

impl From<Coin> for Coins

fn from(value: Coin) -> Self

Converts to this type from the input type.

impl From<Coins> for Vec<Coin>

fn from(value: Coins) -> Self

Converts to this type from the input type.

impl FromStr for Coins

type Err = StdError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> StdResult<Self>

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

impl<'a> IntoIterator for &'a Coins

type Item = &'a Coin

The type of the elements being iterated over.

type IntoIter = CoinsIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Coins

type Item = Coin

The type of the elements being iterated over.

type IntoIter = CoinsIntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Coins

fn eq(&self, other: &Coins) -> 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 TryFrom<&[Coin]> for Coins

type Error = CoinsError

The type returned in the event of a conversion error.

fn try_from(slice: &[Coin]) -> Result<Self, CoinsError>

Performs the conversion.

impl<const N: usize> TryFrom<[Coin; N]> for Coins

type Error = CoinsError

The type returned in the event of a conversion error.

fn try_from(slice: [Coin; N]) -> Result<Self, CoinsError>

Performs the conversion.

impl TryFrom<Vec<Coin>> for Coins

Casting a Vec to Coins. The Vec can be out of order, but must not contain duplicate denoms. If you want to sum up duplicates, create an empty instance using Coins::default and use Coins::add to add your coins.

type Error = CoinsError

The type returned in the event of a conversion error.

fn try_from(vec: Vec<Coin>) -> Result<Self, CoinsError>

Performs the conversion.

impl Eq for Coins

impl StructuralPartialEq for Coins