Rename equipartitionTokenBundlesWithMaxQuantity.

Rename to `splitBundlesWithExcessiveTokenQuantities`.

lib/core/src/Cardano/Wallet/Primitive/CoinSelection/MA/RoundRobin.hs

@@ -53,8 +53,8 @@ module Cardano.Wallet.Primitive.CoinSelection.MA.RoundRobin
     , makeChangeForNonUserSpecifiedAsset
     , assignCoinsToChangeMaps
 
-    -- * Partitioning
-    , equipartitionTokenBundlesWithMaxQuantity
+    -- * Splitting bundles
+    , splitBundlesWithExcessiveTokenQuantities
 
     -- * Grouping and ungrouping
     , groupByKey
@@ -882,7 +882,7 @@ makeChange minCoinFor requiredCost mExtraCoinSource inputBundles outputBundles
           where
             bundle (m, c) = TokenBundle c m
             unbundle (TokenBundle c m) = (m, c)
-            split = flip equipartitionTokenBundlesWithMaxQuantity
+            split = flip splitBundlesWithExcessiveTokenQuantities
                 maxTxOutTokenQuantity
 
     -- Change for user-specified assets: assets that were present in the
@@ -1170,50 +1170,25 @@ makeChangeForCoin targets excess =
     weights = coinToNatural <$> targets
 
 --------------------------------------------------------------------------------
--- Equipartitioning
+-- Splitting bundles
 --------------------------------------------------------------------------------
 
--- An /equipartition/ of a value 'v' (of some type) is a /partition/ of that
--- value into 'n' smaller values whose /sizes/ differ by no more than 1. The
--- the notion of /size/ is dependent on the type of value 'v'.
---
--- In this section, equipartitions have the following properties:
---
---  1.  The length is observed:
---      >>> length (equipartition v n) == n
---
---  2.  The sum is preserved:
---      >>> sum (equipartition v n) == v
---
---  3.  Each resulting value is less than or equal to the original value:
---      >>> all (`leq` v) (equipartition v n)
---
---  4.  The resultant list is sorted into ascending order when values are
---      compared with the 'leq' function.
---
---------------------------------------------------------------------------------
-
---------------------------------------------------------------------------------
--- Equipartitioning according to a maximum token quantity
---------------------------------------------------------------------------------
-
--- | Applies 'TokenBundle.equipartitionQuantitiesWithUpperBound' to a list of
---   bundles.
+-- | Splits bundles with excessive token quantities into smaller bundles.
 --
 -- Only token bundles containing quantities that exceed the maximum token
--- quantity will be partitioned.
+-- quantity will be split.
 --
 -- If none of the bundles in the given list contain a quantity that exceeds
 -- the maximum token quantity, this function will return the original list.
 --
-equipartitionTokenBundlesWithMaxQuantity
+splitBundlesWithExcessiveTokenQuantities
     :: NonEmpty TokenBundle
     -- ^ Token bundles.
     -> TokenQuantity
     -- ^ Maximum allowable token quantity.
     -> NonEmpty TokenBundle
     -- ^ The partitioned bundles.
-equipartitionTokenBundlesWithMaxQuantity bs maxQuantity =
+splitBundlesWithExcessiveTokenQuantities bs maxQuantity =
     (`TokenBundle.equipartitionQuantitiesWithUpperBound` maxQuantity) =<< bs
 
 --------------------------------------------------------------------------------

lib/core/test/unit/Cardano/Wallet/Primitive/CoinSelection/MA/RoundRobinSpec.hs

@@ -37,7 +37,6 @@ import Cardano.Wallet.Primitive.CoinSelection.MA.RoundRobin
     , assetSelectionLens
     , assignCoinsToChangeMaps
     , coinSelectionLens
-    , equipartitionTokenBundlesWithMaxQuantity
     , fullBalance
     , groupByKey
     , makeChange
@@ -51,6 +50,7 @@ import Cardano.Wallet.Primitive.CoinSelection.MA.RoundRobin
     , runRoundRobin
     , runSelection
     , runSelectionStep
+    , splitBundlesWithExcessiveTokenQuantities
     , ungroupByKey
     )
 import Cardano.Wallet.Primitive.Types.Address
@@ -111,8 +111,6 @@ import Data.Map.Strict
     ( Map )
 import Data.Maybe
     ( isJust )
-import Data.Ratio
-    ( (%) )
 import Data.Set
     ( Set )
 import Data.Tuple
@@ -317,14 +315,12 @@ spec = describe "Cardano.Wallet.Primitive.CoinSelection.MA.RoundRobinSpec" $
         unitTests "makeChangeForUserSpecifiedAsset"
             unit_makeChangeForUserSpecifiedAsset
 
-    parallel $ describe "Equipartitioning token bundles by max quantity" $ do
+    parallel $ describe "Splitting bundles with excessive token quantities" $ do
 
-        describe "Lists of token bundles" $ do
-
-            it "prop_equipartitionTokenBundlesWithMaxQuantity_length" $
-                property prop_equipartitionTokenBundlesWithMaxQuantity_length
-            it "prop_equipartitionTokenBundlesWithMaxQuantity_sum" $
-                property prop_equipartitionTokenBundlesWithMaxQuantity_sum
+        it "prop_splitBundlesWithExcessiveTokenQuantities_length" $
+            property prop_splitBundlesWithExcessiveTokenQuantities_length
+        it "prop_splitBundlesWithExcessiveTokenQuantities_sum" $
+            property prop_splitBundlesWithExcessiveTokenQuantities_sum
 
     parallel $ describe "Grouping and ungrouping" $ do
 
@@ -1802,12 +1798,12 @@ unit_makeChangeForUserSpecifiedAsset =
     assetC = AssetId (UnsafeTokenPolicyId $ Hash "A") (UnsafeTokenName "2")
 
 --------------------------------------------------------------------------------
--- Equipartitioning lists of token bundles according to a maximum quantity
+-- Splitting bundles with excessive token quantities
 --------------------------------------------------------------------------------
 
-prop_equipartitionTokenBundlesWithMaxQuantity_length
+prop_splitBundlesWithExcessiveTokenQuantities_length
     :: NonEmpty TokenBundle -> TokenQuantity -> Property
-prop_equipartitionTokenBundlesWithMaxQuantity_length input maxQuantityAllowed =
+prop_splitBundlesWithExcessiveTokenQuantities_length input maxQuantityAllowed =
     maxQuantityAllowed > TokenQuantity.zero ==> checkCoverage $ property $
         cover 5 (lengthOutput > lengthInput)
             "length has increased" $
@@ -1832,13 +1828,13 @@ prop_equipartitionTokenBundlesWithMaxQuantity_length input maxQuantityAllowed =
     maxQuantityOutput =
         F.maximum (TokenMap.maximumQuantity . view #tokens <$> output)
     output =
-        equipartitionTokenBundlesWithMaxQuantity input maxQuantityAllowed
+        splitBundlesWithExcessiveTokenQuantities input maxQuantityAllowed
 
-prop_equipartitionTokenBundlesWithMaxQuantity_sum
+prop_splitBundlesWithExcessiveTokenQuantities_sum
     :: NonEmpty TokenBundle -> TokenQuantity -> Property
-prop_equipartitionTokenBundlesWithMaxQuantity_sum ms maxQuantity =
+prop_splitBundlesWithExcessiveTokenQuantities_sum ms maxQuantity =
     maxQuantity > TokenQuantity.zero ==>
-        F.fold (equipartitionTokenBundlesWithMaxQuantity ms maxQuantity)
+        F.fold (splitBundlesWithExcessiveTokenQuantities ms maxQuantity)
             === F.fold ms
 
 --------------------------------------------------------------------------------