Safe Haskell | None |
---|---|
Language | Haskell2010 |
Cardano.Wallet.Primitive.Types.TokenMap
Description
Provides the
TokenMap
type, which represents a map of named non-ada
token quantities scoped by token policy.
The
TokenMap
type does not provide a way to store ada quantities. If you
also need to store ada quantities, use the
TokenBundle
type.
This module is meant to be imported qualified. For example:
>>>
import qualified Cardano.Wallet.Primitive.Types.TokenMap as TM
Synopsis
- data TokenMap
-
data
AssetId
=
AssetId
{
- tokenPolicyId :: ! TokenPolicyId
- tokenName :: ! TokenName
- empty :: TokenMap
- singleton :: AssetId -> TokenQuantity -> TokenMap
- fromFlatList :: [( AssetId , TokenQuantity )] -> TokenMap
- fromNestedList :: [( TokenPolicyId , NonEmpty ( TokenName , TokenQuantity ))] -> TokenMap
- fromNestedMap :: Map TokenPolicyId ( NonEmptyMap TokenName TokenQuantity ) -> TokenMap
- toFlatList :: TokenMap -> [( AssetId , TokenQuantity )]
- toNestedList :: TokenMap -> [( TokenPolicyId , NonEmpty ( TokenName , TokenQuantity ))]
- toNestedMap :: TokenMap -> Map TokenPolicyId ( NonEmptyMap TokenName TokenQuantity )
- filter :: ( AssetId -> Bool ) -> TokenMap -> TokenMap
- add :: TokenMap -> TokenMap -> TokenMap
- subtract :: TokenMap -> TokenMap -> Maybe TokenMap
- difference :: TokenMap -> TokenMap -> TokenMap
- intersection :: TokenMap -> TokenMap -> TokenMap
- size :: TokenMap -> Int
- isEmpty :: TokenMap -> Bool
- isNotEmpty :: TokenMap -> Bool
- getQuantity :: TokenMap -> AssetId -> TokenQuantity
- setQuantity :: TokenMap -> AssetId -> TokenQuantity -> TokenMap
- hasQuantity :: TokenMap -> AssetId -> Bool
- adjustQuantity :: TokenMap -> AssetId -> ( TokenQuantity -> TokenQuantity ) -> TokenMap
- removeQuantity :: TokenMap -> AssetId -> TokenMap
- maximumQuantity :: TokenMap -> TokenQuantity
- equipartitionAssets :: TokenMap -> NonEmpty a -> NonEmpty TokenMap
- equipartitionQuantities :: TokenMap -> NonEmpty a -> NonEmpty TokenMap
- equipartitionQuantitiesWithUpperBound :: TokenMap -> TokenQuantity -> NonEmpty TokenMap
-
newtype
Lexicographic
a =
Lexicographic
{
- unLexicographic :: a
-
newtype
Flat
a =
Flat
{
- getFlat :: a
-
newtype
Nested
a =
Nested
{
- getNested :: a
- getAssets :: TokenMap -> Set AssetId
- mapAssetIds :: ( AssetId -> AssetId ) -> TokenMap -> TokenMap
- unsafeSubtract :: TokenMap -> TokenMap -> TokenMap
Types
A map of named token quantities, grouped by token policy.
The token map data structure has an important invariant: all token quantities held within a map are non-zero.
This means that:
-
using the
setQuantity
function to add a zero-valued quantity to a map is equivalent to applying the identity operation to that map. -
using the
setQuantity
function to change an existing quantity to zero is equivalent to removing that quantity from the map.
As a consequence of this invariant, the token map data structure is always in its canonical form: we can perform an equality check without needing any extra canonicalization steps.
Instances
Eq TokenMap Source # | |
( TypeError (' Text "Ord not supported for token maps") :: Constraint ) => Ord TokenMap Source # |
Token maps can be partially ordered, but there is no total ordering of token maps that's consistent with their arithmetic properties.
In the event that someone attempts to define an
If some arbitrary ordering is needed (for example, so that token maps can
be included in an ordered set), the recommended course of action is to
define a newtype with its own dedicated
|
Defined in Cardano.Wallet.Primitive.Types.TokenMap |
|
Read TokenMap Source # | |
Show TokenMap Source # | |
Generic TokenMap Source # | |
Semigroup TokenMap Source # | |
Monoid TokenMap Source # | |
NFData TokenMap Source # | |
Defined in Cardano.Wallet.Primitive.Types.TokenMap |
|
Hashable TokenMap Source # | |
PartialOrd TokenMap Source # |
Partial ordering for token maps. There is no total ordering of token maps that's consistent with their arithmetic properties. To see why this is true, consider how we might order the following maps:
One possibility would be to use a lexicographic ordering, but this is not arithmetically useful.
Instead, we define a partial order, where map
For example, consider the following pair of maps:
In the above example, map
|
Ord ( Lexicographic TokenMap ) Source # | |
Defined in Cardano.Wallet.Primitive.Types.TokenMap Methods compare :: Lexicographic TokenMap -> Lexicographic TokenMap -> Ordering Source # (<) :: Lexicographic TokenMap -> Lexicographic TokenMap -> Bool Source # (<=) :: Lexicographic TokenMap -> Lexicographic TokenMap -> Bool Source # (>) :: Lexicographic TokenMap -> Lexicographic TokenMap -> Bool Source # (>=) :: Lexicographic TokenMap -> Lexicographic TokenMap -> Bool Source # max :: Lexicographic TokenMap -> Lexicographic TokenMap -> Lexicographic TokenMap Source # min :: Lexicographic TokenMap -> Lexicographic TokenMap -> Lexicographic TokenMap Source # |
|
Ord ( AssetCount TokenMap ) Source # |
A total ordering on token maps based on the number of assets in each map. If two maps have the same number of assets, then we fall back to ordinary lexicographic ordering as a tie-breaker. |
Defined in Cardano.Wallet.CoinSelection.Internal.Balance Methods compare :: AssetCount TokenMap -> AssetCount TokenMap -> Ordering Source # (<) :: AssetCount TokenMap -> AssetCount TokenMap -> Bool Source # (<=) :: AssetCount TokenMap -> AssetCount TokenMap -> Bool Source # (>) :: AssetCount TokenMap -> AssetCount TokenMap -> Bool Source # (>=) :: AssetCount TokenMap -> AssetCount TokenMap -> Bool Source # max :: AssetCount TokenMap -> AssetCount TokenMap -> AssetCount TokenMap Source # min :: AssetCount TokenMap -> AssetCount TokenMap -> AssetCount TokenMap Source # |
|
ToJSON ( Nested TokenMap ) Source # | |
ToJSON ( Flat TokenMap ) Source # | |
ToJSON ( ApiT TokenMap ) Source # | |
FromJSON ( Nested TokenMap ) Source # | |
FromJSON ( Flat TokenMap ) Source # | |
FromJSON ( ApiT TokenMap ) Source # | |
Buildable ( Nested TokenMap ) Source # | |
Buildable ( Flat TokenMap ) Source # | |
type Rep TokenMap Source # | |
Defined in Cardano.Wallet.Primitive.Types.TokenMap
type
Rep
TokenMap
=
D1
('
MetaData
"TokenMap" "Cardano.Wallet.Primitive.Types.TokenMap" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" '
True
) (
C1
('
MetaCons
"TokenMap" '
PrefixI
'
True
) (
S1
('
MetaSel
('
Just
"unTokenMap") '
NoSourceUnpackedness
'
NoSourceStrictness
'
DecidedLazy
) (
Rec0
(
Map
TokenPolicyId
(
NonEmptyMap
TokenName
TokenQuantity
)))))
|
A combination of a token policy identifier and a token name that can be used as a compound identifier.
Constructors
AssetId | |
Fields
|
Instances
Eq AssetId Source # | |
Ord AssetId Source # | |
Defined in Cardano.Wallet.Primitive.Types.TokenMap |
|
Read AssetId Source # | |
Show AssetId Source # | |
Generic AssetId Source # | |
NFData AssetId Source # | |
Defined in Cardano.Wallet.Primitive.Types.TokenMap |
|
type Rep AssetId Source # | |
Defined in Cardano.Wallet.Primitive.Types.TokenMap
type
Rep
AssetId
=
D1
('
MetaData
"AssetId" "Cardano.Wallet.Primitive.Types.TokenMap" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" '
False
) (
C1
('
MetaCons
"AssetId" '
PrefixI
'
True
) (
S1
('
MetaSel
('
Just
"tokenPolicyId") '
NoSourceUnpackedness
'
SourceStrict
'
DecidedStrict
) (
Rec0
TokenPolicyId
)
:*:
S1
('
MetaSel
('
Just
"tokenName") '
NoSourceUnpackedness
'
SourceStrict
'
DecidedStrict
) (
Rec0
TokenName
)))
|
Construction
singleton :: AssetId -> TokenQuantity -> TokenMap Source #
Creates a singleton token map with just one token quantity.
If the specified token quantity is zero, then the resultant map will be
equal to the
empty
map.
fromFlatList :: [( AssetId , TokenQuantity )] -> TokenMap Source #
Creates a token map from a flat list.
If a token name appears more than once in the list under the same policy, its associated quantities will be added together in the resultant map.
fromNestedList :: [( TokenPolicyId , NonEmpty ( TokenName , TokenQuantity ))] -> TokenMap Source #
Creates a token map from a nested list.
If a token name appears more than once in the list under the same policy, its associated quantities will be added together in the resultant map.
fromNestedMap :: Map TokenPolicyId ( NonEmptyMap TokenName TokenQuantity ) -> TokenMap Source #
Creates a token map from a nested map.
Deconstruction
toFlatList :: TokenMap -> [( AssetId , TokenQuantity )] Source #
Converts a token map to a flat list.
toNestedList :: TokenMap -> [( TokenPolicyId , NonEmpty ( TokenName , TokenQuantity ))] Source #
Converts a token map to a nested list.
toNestedMap :: TokenMap -> Map TokenPolicyId ( NonEmptyMap TokenName TokenQuantity ) Source #
Converts a token map to a nested map.
Filtering
Arithmetic
difference :: TokenMap -> TokenMap -> TokenMap Source #
Analogous to
Set.difference
, return the difference between two token
maps.
The following property holds:
prop> x
leq
(x
difference
y)
add
y
Note that there's a
leq
rather than equality, which we'd expect if this was
subtraction of integers. I.e.
>>>
(0 - 1) + 1
0
whereas
>>>
let oneToken = singleton aid (TokenQuantity 1)
>>>
(mempty `difference` oneToken) `add` oneToken
oneToken
intersection :: TokenMap -> TokenMap -> TokenMap Source #
Computes the intersection of two token maps.
Analogous to
Set.intersection
.
Example:
>>>
m1 = [("a", 1), ("b", 2), ("c", 3) ]
>>>
m2 = [ ("b", 3), ("c", 2), ("d", 1)]
>>>
intersection m1 m2
[ ("b", 2), ("c", 2) ]
Queries
Tests
isNotEmpty :: TokenMap -> Bool Source #
Returns true if and only if the given map is not empty.
Quantities
getQuantity :: TokenMap -> AssetId -> TokenQuantity Source #
Gets the quantity associated with a given asset.
If the given map does not have an entry for the specified asset, this function returns a value of zero.
setQuantity :: TokenMap -> AssetId -> TokenQuantity -> TokenMap Source #
Updates the quantity associated with a given asset.
If the given quantity is zero, the resultant map will not have an entry for the given asset.
hasQuantity :: TokenMap -> AssetId -> Bool Source #
Returns true if and only if the given map has a non-zero quantity for the given asset.
adjustQuantity :: TokenMap -> AssetId -> ( TokenQuantity -> TokenQuantity ) -> TokenMap Source #
Uses the specified function to adjust the quantity associated with a given asset.
If the result of adjusting the quantity is equal to zero, the resultant map will not have an entry for the given asset.
removeQuantity :: TokenMap -> AssetId -> TokenMap Source #
Removes the quantity associated with the given asset.
This is equivalent to calling
setQuantity
with a value of zero.
maximumQuantity :: TokenMap -> TokenQuantity Source #
Get the largest quantity from this map.
Partitioning
Arguments
:: TokenMap |
The token map to be partitioned. |
-> NonEmpty a |
Represents the number of portions in which to partition the token map. |
-> NonEmpty TokenMap |
The partitioned maps. |
Partitions a token map into
n
smaller maps, where the asset sets of the
resultant maps are disjoint.
In the resultant maps, the smallest asset set size and largest asset set size will differ by no more than 1.
The quantities of each asset are unchanged.
equipartitionQuantities Source #
Arguments
:: TokenMap |
The map to be partitioned. |
-> NonEmpty a |
Represents the number of portions in which to partition the map. |
-> NonEmpty TokenMap |
The partitioned maps. |
Partitions a token map into
n
smaller maps, where the quantity of each
token is equipartitioned across the resultant maps.
In the resultant maps, the smallest quantity and largest quantity of a given token will differ by no more than 1.
The resultant list is sorted into ascending order when maps are compared
with the
leq
function.
equipartitionQuantitiesWithUpperBound Source #
Arguments
:: TokenMap | |
-> TokenQuantity |
Maximum allowable token quantity. |
-> NonEmpty TokenMap |
The partitioned maps. |
Partitions a token map into
n
smaller maps, where the quantity of each
token is equipartitioned across the resultant maps, with the goal that no
token quantity in any of the resultant maps exceeds the given upper bound.
The value
n
is computed automatically, and is the minimum value required
to achieve the goal that no token quantity in any of the resulting maps
exceeds the maximum allowable token quantity.
Ordering
newtype Lexicographic a Source #
Defines a lexicographic ordering.
Constructors
Lexicographic | |
Fields
|
Instances
Serialization
When used with the
Buildable
or
ToJSON
instances, provides a flat
serialization style, where token quantities are paired with their asset
identifiers.
Instances
Eq a => Eq ( Flat a) Source # | |
Ord a => Ord ( Flat a) Source # | |
Defined in Cardano.Wallet.Primitive.Types.TokenMap |
|
Show a => Show ( Flat a) Source # | |
Generic ( Flat a) Source # | |
ToJSON ( Flat TokenMap ) Source # | |
FromJSON ( Flat TokenMap ) Source # | |
Buildable ( Flat TokenMap ) Source # | |
Buildable ( Flat TokenBundle ) Source # | |
Defined in Cardano.Wallet.Primitive.Types.TokenBundle |
|
type Rep ( Flat a) Source # | |
Defined in Cardano.Wallet.Primitive.Types.TokenMap |
When used with the
Buildable
or
ToJSON
instances, provides a nested
serialization style, where token quantities are grouped by policy
identifier.
Instances
Eq a => Eq ( Nested a) Source # | |
Ord a => Ord ( Nested a) Source # | |
Defined in Cardano.Wallet.Primitive.Types.TokenMap |
|
Show a => Show ( Nested a) Source # | |
Generic ( Nested a) Source # | |
ToJSON ( Nested TokenMap ) Source # | |
FromJSON ( Nested TokenMap ) Source # | |
Buildable ( Nested TokenMap ) Source # | |
Buildable ( Nested TokenBundle ) Source # | |
Defined in Cardano.Wallet.Primitive.Types.TokenBundle |
|
type Rep ( Nested a) Source # | |
Defined in Cardano.Wallet.Primitive.Types.TokenMap
type
Rep
(
Nested
a) =
D1
('
MetaData
"Nested" "Cardano.Wallet.Primitive.Types.TokenMap" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" '
True
) (
C1
('
MetaCons
"Nested" '
PrefixI
'
True
) (
S1
('
MetaSel
('
Just
"getNested") '
NoSourceUnpackedness
'
NoSourceStrictness
'
DecidedLazy
) (
Rec0
a)))
|