Method AllocateToCash
AllocateToCash(int)
Allocates this value into the specified number of equal parts that are valid cash amounts under the currency's CashRoundingPolicy, distributing any remainder so that the parts always sum to this value rounded to the policy.
Declaration
public ImmutableArray<MonetaryValue> AllocateToCash(int count)Parameters
| Type | Name | Description |
|---|---|---|
| int | count | The number of parts to allocate the value into. |
Returns
| Type | Description |
|---|---|
| ImmutableArray<MonetaryValue> |
Remarks
The value is first rounded to the policy using ToEven rounding, and the parts always sum exactly to that rounded
value. The remainder that results from rounding the individual parts down to the policy's smallest unit is distributed one unit at a time to the
parts that lost the largest fraction (the "largest remainder" method), with ties resolved in favor of earlier parts. For equal allocations this
means earlier parts receive the extra units, i.e. USD 100.00 allocated into 3 parts yields 34.34, 33.33 and
33.33.
Negative values are allocated the same way as their absolute value with the parts negated. Parts with a zero ratio are always zero. A default value is allocated into default values.
Exceptions
| Type | Condition |
|---|---|
| ArgumentOutOfRangeException |
|
| NotSupportedException | Cash rounding rules are not available for the currency. See CashRoundingPolicy for more information. |
AllocateToCash(params ReadOnlySpan<decimal>)
Allocates this value into parts proportional to the specified ratios that are valid cash amounts under the currency's CashRoundingPolicy, distributing any remainder so that the parts always sum to this value rounded to the policy.
Declaration
public ImmutableArray<MonetaryValue> AllocateToCash(params ReadOnlySpan<decimal> ratios)Parameters
| Type | Name | Description |
|---|---|---|
| ReadOnlySpan<decimal> | ratios | The relative weights of each part. Weights can be any non-negative values and do not need to sum to |
Returns
| Type | Description |
|---|---|
| ImmutableArray<MonetaryValue> |
Remarks
The value is first rounded to the policy using ToEven rounding, and the parts always sum exactly to that rounded
value. The remainder that results from rounding the individual parts down to the policy's smallest unit is distributed one unit at a time to the
parts that lost the largest fraction (the "largest remainder" method), with ties resolved in favor of earlier parts. For equal allocations this
means earlier parts receive the extra units, i.e. USD 100.00 allocated into 3 parts yields 34.34, 33.33 and
33.33.
Negative values are allocated the same way as their absolute value with the parts negated. Parts with a zero ratio are always zero. A default value is allocated into default values.
Exceptions
| Type | Condition |
|---|---|
| ArgumentException |
|
| NotSupportedException | Cash rounding rules are not available for the currency. See CashRoundingPolicy for more information. |