Copyright	© 2018-2021 IOHK
License	Apache-2.0
Safe Haskell	None
Language	Haskell2010

Cardano.Wallet.Primitive.Types.UTxOSelection

Contents

Classes
Types
Construction and deconstruction
Promotion and demotion
Indicator functions
Accessor functions
Modification

Description

Provides the UTxOSelection type, which represents a selection of UTxO entries from a UTxO set.

It consists of a pair of UTxO sets:

the selected set: UTxOs that have already been selected;
the leftover set: UTxOs that have not yet been selected.

To construct a UTxOSelection where none of the UTxOs are selected, use the fromIndex function.

To construct a UTxOSelection where some of the UTxOs are selected, use either the fromIndexFiltered or the fromIndexPair functions.

To select an element (and move it from the leftover set to the selected set), use the select function.

A UTxOSelection can be promoted to a UTxOSelectionNonEmpty , indicating that the selected set contains at least one UTxO. To promote a selection, either use the toNonEmpty function to assert that it is non-empty, or use the select function to select a single entry.

Synopsis

class HasUTxOSelectionState s u => IsUTxOSelection s u
data UTxOSelection u
data UTxOSelectionNonEmpty u
empty :: UTxOSelection u
fromIndex :: UTxOIndex u -> UTxOSelection u
fromIndexFiltered :: Ord u => (u -> Bool ) -> UTxOIndex u -> UTxOSelection u
fromIndexPair :: Ord u => ( UTxOIndex u, UTxOIndex u) -> UTxOSelection u
toIndexPair :: IsUTxOSelection s u => s u -> ( UTxOIndex u, UTxOIndex u)
fromNonEmpty :: UTxOSelectionNonEmpty u -> UTxOSelection u
toNonEmpty :: IsUTxOSelection s u => s u -> Maybe ( UTxOSelectionNonEmpty u)
isEmpty :: IsUTxOSelection s u => s u -> Bool
isNonEmpty :: IsUTxOSelection s u => s u -> Bool
isMember :: IsUTxOSelection s u => Ord u => u -> s u -> Bool
isLeftover :: IsUTxOSelection s u => Ord u => u -> s u -> Bool
isSelected :: IsUTxOSelection s u => Ord u => u -> s u -> Bool
isSubSelectionOf :: IsUTxOSelection s1 u => IsUTxOSelection s2 u => Ord u => s1 u -> s2 u -> Bool
isProperSubSelectionOf :: IsUTxOSelection s1 u => IsUTxOSelection s2 u => Ord u => s1 u -> s2 u -> Bool
availableBalance :: IsUTxOSelection s u => s u -> TokenBundle
availableMap :: IsUTxOSelection s u => Ord u => s u -> Map u TokenBundle
availableSize :: IsUTxOSelection s u => s u -> Int
leftoverBalance :: IsUTxOSelection s u => s u -> TokenBundle
leftoverSize :: IsUTxOSelection s u => s u -> Int
leftoverIndex :: IsUTxOSelection s u => s u -> UTxOIndex u
leftoverList :: IsUTxOSelection s u => s u -> [(u, TokenBundle )]
leftoverMap :: IsUTxOSelection s u => s u -> Map u TokenBundle
selectedBalance :: IsUTxOSelection s u => s u -> TokenBundle
selectedSize :: IsUTxOSelection s u => s u -> Int
selectedIndex :: IsUTxOSelection s u => s u -> UTxOIndex u
selectedList :: IsUTxOSelection s u => s u -> SelectedList s u
selectedMap :: IsUTxOSelection s u => s u -> Map u TokenBundle
select :: IsUTxOSelection s u => Ord u => u -> s u -> Maybe ( UTxOSelectionNonEmpty u)
selectMany :: IsUTxOSelection s u => Ord u => Foldable f => f u -> s u -> s u

Classes

class HasUTxOSelectionState s u => IsUTxOSelection s u Source #

Minimal complete definition

selectedList

Instances

Instances details

IsUTxOSelection UTxOSelectionNonEmpty u Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOSelection Associated Types type SelectedList UTxOSelectionNonEmpty u Methods selectedList :: UTxOSelectionNonEmpty u -> SelectedList UTxOSelectionNonEmpty u Source #
IsUTxOSelection UTxOSelection u Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOSelection Associated Types type SelectedList UTxOSelection u Methods selectedList :: UTxOSelection u -> SelectedList UTxOSelection u Source #

Types

data UTxOSelection u Source #

A selection for which isNonEmpty may be False .

Instances

Instances details

IsUTxOSelection UTxOSelection u Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOSelection Associated Types type SelectedList UTxOSelection u Methods selectedList :: UTxOSelection u -> SelectedList UTxOSelection u Source #
Eq u => Eq ( UTxOSelection u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOSelection Methods (==) :: UTxOSelection u -> UTxOSelection u -> Bool Source # (/=) :: UTxOSelection u -> UTxOSelection u -> Bool Source #
Show u => Show ( UTxOSelection u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOSelection Methods showsPrec :: Int -> UTxOSelection u -> ShowS Source # show :: UTxOSelection u -> String Source # showList :: [ UTxOSelection u] -> ShowS Source #
Generic ( UTxOSelection u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOSelection Associated Types type Rep ( UTxOSelection u) :: Type -> Type Source # Methods from :: UTxOSelection u -> Rep ( UTxOSelection u) x Source # to :: Rep ( UTxOSelection u) x -> UTxOSelection u Source #
type Rep ( UTxOSelection u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOSelection type Rep ( UTxOSelection u)

data UTxOSelectionNonEmpty u Source #

A selection for which isNonEmpty must be True .

Instances

Instances details

IsUTxOSelection UTxOSelectionNonEmpty u Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOSelection Associated Types type SelectedList UTxOSelectionNonEmpty u Methods selectedList :: UTxOSelectionNonEmpty u -> SelectedList UTxOSelectionNonEmpty u Source #
Eq u => Eq ( UTxOSelectionNonEmpty u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOSelection Methods (==) :: UTxOSelectionNonEmpty u -> UTxOSelectionNonEmpty u -> Bool Source # (/=) :: UTxOSelectionNonEmpty u -> UTxOSelectionNonEmpty u -> Bool Source #
Show u => Show ( UTxOSelectionNonEmpty u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOSelection Methods showsPrec :: Int -> UTxOSelectionNonEmpty u -> ShowS Source # show :: UTxOSelectionNonEmpty u -> String Source # showList :: [ UTxOSelectionNonEmpty u] -> ShowS Source #
Generic ( UTxOSelectionNonEmpty u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOSelection Associated Types type Rep ( UTxOSelectionNonEmpty u) :: Type -> Type Source # Methods from :: UTxOSelectionNonEmpty u -> Rep ( UTxOSelectionNonEmpty u) x Source # to :: Rep ( UTxOSelectionNonEmpty u) x -> UTxOSelectionNonEmpty u Source #
type Rep ( UTxOSelectionNonEmpty u) Source #
Instance details Defined in Cardano.Wallet.Primitive.Types.UTxOSelection type Rep ( UTxOSelectionNonEmpty u)

Construction and deconstruction

empty :: UTxOSelection u Source #

A completely empty selection with no selected or leftover UTxOs.

fromIndex :: UTxOIndex u -> UTxOSelection u Source #

Creates a selection where none of the UTxOs are selected.

All UTxOs in the index will be added to the leftover set.

fromIndexFiltered :: Ord u => (u -> Bool ) -> UTxOIndex u -> UTxOSelection u Source #

Creates a selection from an index and a filter.

All UTxOs that match the given filter will be added to the selected set, whereas all UTxOs that do not match will be added to the leftover set.

fromIndexPair :: Ord u => ( UTxOIndex u, UTxOIndex u) -> UTxOSelection u Source #

Creates a selection from a pair of indices.

The 1st index in the pair represents the leftover set. The 2nd index in the pair represents the selected set.

Any items that are in both sets are removed from the leftover set.

toIndexPair :: IsUTxOSelection s u => s u -> ( UTxOIndex u, UTxOIndex u) Source #

Converts a selection to a pair of indices.

The 1st index in the pair represents the leftover set. The 2nd index in the pair represents the selected set.

Promotion and demotion

fromNonEmpty :: UTxOSelectionNonEmpty u -> UTxOSelection u Source #

Demotes a non-empty selection to an ordinary selection.

toNonEmpty :: IsUTxOSelection s u => s u -> Maybe ( UTxOSelectionNonEmpty u) Source #

Promotes an ordinary selection to a non-empty selection.

Returns Nothing if the the selected set is empty.

Indicator functions

isEmpty :: IsUTxOSelection s u => s u -> Bool Source #

Returns True if and only if the selected set is empty.

isNonEmpty :: IsUTxOSelection s u => s u -> Bool Source #

Returns True if and only if the selected set is non-empty.

isMember :: IsUTxOSelection s u => Ord u => u -> s u -> Bool Source #

Returns True if the given InputId is a member of either set.

Otherwise, returns False .

isLeftover :: IsUTxOSelection s u => Ord u => u -> s u -> Bool Source #

Returns True iff. the given InputId is a member of the leftover set.

isSelected :: IsUTxOSelection s u => Ord u => u -> s u -> Bool Source #

Returns True iff. the given InputId is a member of the selected set.

isSubSelectionOf :: IsUTxOSelection s1 u => IsUTxOSelection s2 u => Ord u => s1 u -> s2 u -> Bool Source #

Returns True iff. the first selection is a sub-selection of the second.

A selection s1 is a sub-selection of selection s2 if (and only if) it is possible to transform s1 into s2 through zero or more applications of the select function.

isProperSubSelectionOf :: IsUTxOSelection s1 u => IsUTxOSelection s2 u => Ord u => s1 u -> s2 u -> Bool Source #

Returns True iff. the first selection is a proper sub-selection of the second.

A selection s1 is a proper sub-selection of selection s2 if (and only if) it is possible to transform s1 into s2 through one or more applications of the select function.

Accessor functions

availableBalance :: IsUTxOSelection s u => s u -> TokenBundle Source #

Computes the available balance.

The available balance is the sum of the selected and the leftover balances.

It predicts what selectedBalance would be if every single UTxO were selected.

This result of this function remains constant over applications of select and selectMany :

>>> availableBalance s == availableBalance (selectMany is s)

availableMap :: IsUTxOSelection s u => Ord u => s u -> Map u TokenBundle Source #

Computes the complete map of all available UTxOs.

The available UTxO set is the union of the selected and leftover UTxO sets.

It predicts what selectedMap would be if every single UTxO were selected.

This result of this function remains constant over applications of select and selectMany :

>>> availableMap s == availableMap (selectMany is s)

availableSize :: IsUTxOSelection s u => s u -> Int Source #

Computes the size of the available UTxO set.

leftoverBalance :: IsUTxOSelection s u => s u -> TokenBundle Source #

Retrieves the balance of leftover UTxOs.

leftoverSize :: IsUTxOSelection s u => s u -> Int Source #

Retrieves the size of the leftover UTxO set.

leftoverIndex :: IsUTxOSelection s u => s u -> UTxOIndex u Source #

Retrieves an index of the leftover UTxOs.

leftoverList :: IsUTxOSelection s u => s u -> [(u, TokenBundle )] Source #

Retrieves a list of the leftover UTxOs.

leftoverMap :: IsUTxOSelection s u => s u -> Map u TokenBundle Source #

Retrieves a map of the leftover UTxOs.

selectedBalance :: IsUTxOSelection s u => s u -> TokenBundle Source #

Retrieves the balance of selected UTxOs.

selectedSize :: IsUTxOSelection s u => s u -> Int Source #

Retrieves the size of the selected UTxO set.

selectedIndex :: IsUTxOSelection s u => s u -> UTxOIndex u Source #

Retrieves an index of the selected UTxOs.

selectedList :: IsUTxOSelection s u => s u -> SelectedList s u Source #

Retrieves a list of the selected UTxOs.

selectedMap :: IsUTxOSelection s u => s u -> Map u TokenBundle Source #

Retrieves a map of the selected UTxOs.

Modification

select :: IsUTxOSelection s u => Ord u => u -> s u -> Maybe ( UTxOSelectionNonEmpty u) Source #

Moves a single entry from the leftover set to the selected set.

Returns Nothing if the given entry is not a member of the leftover set.

selectMany :: IsUTxOSelection s u => Ord u => Foldable f => f u -> s u -> s u Source #

Moves multiple entries from the leftover set to the selected set.