Money (hutool 5.8.33 API)

java.lang.Object
- cn.hutool.core.math.Money

All Implemented Interfaces:

Serializable, Comparable<Money>
```
public class Money
extends Object
implements Serializable, Comparable<Money>
```
单币种货币类，处理货币算术、币种和取整。
感谢提供此方法的用户：https://github.com/dromara/hutool/issues/605
货币类中封装了货币金额和币种。目前金额在内部是long类型表示，单位是所属币种的最小货币单位（对人民币是分）。
目前，货币实现了以下主要功能：
- 支持货币对象与double(float)/long(int)/String/BigDecimal之间相互转换。
- 货币类在运算中提供与JDK中的BigDecimal类似的运算接口， BigDecimal的运算接口支持任意指定精度的运算功能，能够支持各种可能的财务规则。
- 货币类在运算中也提供一组简单运算接口，使用这组运算接口，则在精度处理上使用缺省的处理规则。
- 推荐使用Money，不建议直接使用BigDecimal的原因之一在于，使用BigDecimal，同样金额和币种的货币使用BigDecimal存在多种可能的表示，例如：new BigDecimal("10.5")与new BigDecimal("10.50") 不相等，因为scale不等。使得Money类，同样金额和币种的货币只有一种表示方式，new Money("10.5")和new Money("10.50")应该是相等的。
- 不推荐直接使用BigDecimal的另一原因在于， BigDecimal是Immutable，一旦创建就不可更改，对BigDecimal进行任意运算都会生成一个新的 BigDecimal对象，因此对于大批量统计的性能不够满意。Money类是 mutable的，对大批量统计提供较好的支持。
- 提供基本的格式化功能。
- Money类中不包含与业务相关的统计功能和格式化功能。业务相关的功能建议使用utility类来实现。
- Money类实现了Serializable接口，支持作为远程调用的参数和返回值。
- Money类实现了equals和hashCode方法。
Since:

5.0.4

Author:

ddatsh

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`DEFAULT_CURRENCY_CODE` 缺省的币种代码，为CNY（人民币）。
`static RoundingMode`	`DEFAULT_ROUNDING_MODE` 缺省的取整模式，为`RoundingMode.HALF_EVEN` （四舍五入，当小数为0.5时，则取最近的偶数）。

Constructor Summary

Constructors
Constructor and Description
`Money()` 缺省构造器。
`Money(BigDecimal amount)` 构造器。
`Money(BigDecimal amount, Currency currency)` 构造器。
`Money(BigDecimal amount, Currency currency, RoundingMode roundingMode)` 构造器。
`Money(BigDecimal amount, RoundingMode roundingMode)` 构造器。
`Money(double amount)` 构造器。
`Money(double amount, Currency currency)` 构造器。
`Money(long yuan, int cent)` 构造器。
`Money(long yuan, int cent, Currency currency)` 构造器。
`Money(String amount)` 构造器。
`Money(String amount, Currency currency)` 构造器。
`Money(String amount, Currency currency, RoundingMode roundingMode)` 构造器。

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Money`	`add(Money other)` 货币加法。
`Money`	`addTo(Money other)` 货币累加。
`Money[]`	`allocate(int targets)` 货币分配。
`Money[]`	`allocate(long[] ratios)` 货币分配。
`protected void`	`assertSameCurrencyAs(Money other)` 断言本货币对象与另一货币对象是否具有相同的币种。
`int`	`compareTo(Money other)` 货币比较。
`Money`	`divide(BigDecimal val)` 货币除法。
`Money`	`divide(BigDecimal val, RoundingMode roundingMode)` 货币除法。
`Money`	`divide(double val)` 货币除法。
`Money`	`divideBy(BigDecimal val)` 货币累除。
`Money`	`divideBy(BigDecimal val, RoundingMode roundingMode)` 货币累除。
`Money`	`divideBy(double val)` 货币累除。
`String`	`dump()` 生成本对象内部变量的字符串表示，用于调试。
`boolean`	`equals(Money other)` 判断本货币对象与另一货币对象是否相等。
`boolean`	`equals(Object other)` 判断本货币对象与另一对象是否相等。
`BigDecimal`	`getAmount()` 获取本货币对象代表的金额数。
`long`	`getCent()` 获取本货币对象代表的金额数。
`int`	`getCentFactor()` 获取本货币币种的元/分换算比率。
`Currency`	`getCurrency()` 获取本货币对象代表的币种。
`boolean`	`greaterThan(Money other)` 货币比较。
`int`	`hashCode()` 计算本货币对象的杂凑值。
`Money`	`multiply(BigDecimal val)` 货币乘法。
`Money`	`multiply(BigDecimal val, RoundingMode roundingMode)` 货币乘法。
`Money`	`multiply(double val)` 货币乘法。
`Money`	`multiply(long val)` 货币乘法。
`Money`	`multiplyBy(BigDecimal val)` 货币累乘。
`Money`	`multiplyBy(BigDecimal val, RoundingMode roundingMode)` 货币累乘。
`Money`	`multiplyBy(double val)` 货币累乘。
`Money`	`multiplyBy(long val)` 货币累乘。
`protected Money`	`newMoneyWithSameCurrency(long cent)` 创建一个币种相同，具有指定金额的货币对象。
`protected long`	`rounding(BigDecimal val, RoundingMode roundingMode)` 对BigDecimal型的值按指定取整方式取整。
`void`	`setAmount(BigDecimal amount)` 设置本货币对象代表的金额数。
`void`	`setCent(long cent)` 设置货币的分值。
`Money`	`subtract(Money other)` 货币减法。
`Money`	`subtractFrom(Money other)` 货币累减。
`String`	`toString()` 生成本对象的缺省字符串表示

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT_CURRENCY_CODE
```
public static final String DEFAULT_CURRENCY_CODE
```
    缺省的币种代码，为CNY（人民币）。
    
    See Also:
    
    Constant Field Values
  - DEFAULT_ROUNDING_MODE
```
public static final RoundingMode DEFAULT_ROUNDING_MODE
```
    缺省的取整模式，为RoundingMode.HALF_EVEN （四舍五入，当小数为0.5时，则取最近的偶数）。
- Constructor Detail
  - Money
```
public Money()
```
    缺省构造器。
    创建一个具有缺省金额（0）和缺省币种的货币对象。
  - Money
```
public Money(long yuan,
             int cent)
```
    构造器。
    创建一个具有金额yuan元cent分和缺省币种的货币对象。
    
    Parameters:
    
    yuan - 金额元数，0的情况下表示元的部分从分中截取
    
    cent - 金额分数。
  - Money
```
public Money(long yuan,
             int cent,
             Currency currency)
```
    构造器。
    创建一个具有金额yuan元cent分和指定币种的货币对象。
    
    Parameters:
    
    yuan - 金额元数，0的情况下表示元的部分从分中截取
    
    cent - 金额分数。
    
    currency - 货币单位
  - Money
```
public Money(String amount)
```
    构造器。
    创建一个具有金额amount元和缺省币种的货币对象。
    
    Parameters:
    
    amount - 金额，以元为单位。
  - Money
```
public Money(String amount,
             Currency currency)
```
    构造器。
    创建一个具有金额amount元和指定币种currency的货币对象。
    
    Parameters:
    
    amount - 金额，以元为单位。
    
    currency - 币种。
  - Money
```
public Money(String amount,
             Currency currency,
             RoundingMode roundingMode)
```
    构造器。
    创建一个具有金额amount元和指定币种currency的货币对象。如果金额不能转换为整数分，则使用指定的取整模式roundingMode取整。
    
    Parameters:
    
    amount - 金额，以元为单位。
    
    currency - 币种。
    
    roundingMode - 取整模式。
  - Money
```
public Money(double amount)
```
    构造器。
    创建一个具有参数amount指定金额和缺省币种的货币对象。如果金额不能转换为整数分，则使用四舍五入方式取整。
    注意：由于double类型运算中存在误差，使用四舍五入方式取整的结果并不确定，因此，应尽量避免使用double类型创建货币类型。例： assertEquals(999, Math.round(9.995 * 100)); assertEquals(1000, Math.round(999.5)); money = new Money((9.995)); assertEquals(999, money.getCent()); money = new Money(10.005); assertEquals(1001, money.getCent());
    
    Parameters:
    
    amount - 金额，以元为单位。
  - Money
```
public Money(double amount,
             Currency currency)
```
    构造器。
    创建一个具有金额amount和指定币种的货币对象。如果金额不能转换为整数分，则使用四舍五入方式取整。
    注意：由于double类型运算中存在误差，使用四舍五入方式取整的结果并不确定，因此，应尽量避免使用double类型创建货币类型。例： assertEquals(999, Math.round(9.995 * 100)); assertEquals(1000, Math.round(999.5)); money = new Money((9.995)); assertEquals(999, money.getCent()); money = new Money(10.005); assertEquals(1001, money.getCent());
    
    Parameters:
    
    amount - 金额，以元为单位。
    
    currency - 币种。
  - Money
```
public Money(BigDecimal amount)
```
    构造器。
    创建一个具有金额amount和缺省币种的货币对象。如果金额不能转换为整数分，则使用缺省取整模式DEFAULT_ROUNDING_MODE取整。
    
    Parameters:
    
    amount - 金额，以元为单位。
  - Money
```
public Money(BigDecimal amount,
             RoundingMode roundingMode)
```
    构造器。
    创建一个具有参数amount指定金额和缺省币种的货币对象。如果金额不能转换为整数分，则使用指定的取整模式roundingMode取整。
    
    Parameters:
    
    amount - 金额，以元为单位。
    
    roundingMode - 取整模式
  - Money
```
public Money(BigDecimal amount,
             Currency currency)
```
    构造器。
    创建一个具有金额amount和指定币种的货币对象。如果金额不能转换为整数分，则使用缺省的取整模式DEFAULT_ROUNDING_MODE进行取整。
    
    Parameters:
    
    amount - 金额，以元为单位。
    
    currency - 币种
  - Money
```
public Money(BigDecimal amount,
             Currency currency,
             RoundingMode roundingMode)
```
    构造器。
    创建一个具有金额amount和指定币种的货币对象。如果金额不能转换为整数分，则使用指定的取整模式roundingMode取整。
    
    Parameters:
    
    amount - 金额，以元为单位。
    
    currency - 币种。
    
    roundingMode - 取整模式。
- Method Detail
  - getAmount
```
public BigDecimal getAmount()
```
    获取本货币对象代表的金额数。
    
    Returns:
    
    金额数，以元为单位。
  - setAmount
```
public void setAmount(BigDecimal amount)
```
    设置本货币对象代表的金额数。
    
    Parameters:
    
    amount - 金额数，以元为单位。
  - getCent
```
public long getCent()
```
    获取本货币对象代表的金额数。
    
    Returns:
    
    金额数，以分为单位。
  - getCurrency
```
public Currency getCurrency()
```
    获取本货币对象代表的币种。
    
    Returns:
    
    本货币对象所代表的币种。
  - getCentFactor
```
public int getCentFactor()
```
    获取本货币币种的元/分换算比率。
    
    Returns:
    
    本货币币种的元/分换算比率。
  - equals
```
public boolean equals(Object other)
```
    判断本货币对象与另一对象是否相等。
    货币对象与另一对象相等的充分必要条件是：
    - 另一对象也属货币对象类。
    - 金额相同。
    - 币种相同。
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    other - 待比较的另一对象。
    
    Returns:
    
    true表示相等，false表示不相等。
  - equals
```
public boolean equals(Money other)
```
    判断本货币对象与另一货币对象是否相等。
    货币对象与另一货币对象相等的充分必要条件是：
    - 金额相同。
    - 币种相同。
    Parameters:
    
    other - 待比较的另一货币对象。
    
    Returns:
    
    true表示相等，false表示不相等。
  - hashCode
```
public int hashCode()
```
    计算本货币对象的杂凑值。
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    本货币对象的杂凑值。
  - compareTo
```
public int compareTo(Money other)
```
    货币比较。
    比较本货币对象与另一货币对象的大小。如果待比较的两个货币对象的币种不同，则抛出java.lang.IllegalArgumentException。如果本货币对象的金额少于待比较货币对象，则返回-1。如果本货币对象的金额等于待比较货币对象，则返回0。如果本货币对象的金额大于待比较货币对象，则返回1。
    
    Specified by:
    
    compareTo in interface Comparable<Money>
    
    Parameters:
    
    other - 另一对象。
    
    Returns:
    
    -1表示小于，0表示等于，1表示大于。
    
    Throws:
    
    IllegalArgumentException - 待比较货币对象与本货币对象的币种不同。
  - greaterThan
```
public boolean greaterThan(Money other)
```
    货币比较。
    判断本货币对象是否大于另一货币对象。如果待比较的两个货币对象的币种不同，则抛出java.lang.IllegalArgumentException。如果本货币对象的金额大于待比较货币对象，则返回true，否则返回false。
    
    Parameters:
    
    other - 另一对象。
    
    Returns:
    
    true表示大于，false表示不大于（小于等于）。
    
    Throws:
    
    IllegalArgumentException - 待比较货币对象与本货币对象的币种不同。
  - add
```
public Money add(Money other)
```
    货币加法。
    如果两货币币种相同，则返回一个新的相同币种的货币对象，其金额为两货币对象金额之和，本货币对象的值不变。如果两货币对象币种不同，抛出java.lang.IllegalArgumentException。
    
    Parameters:
    
    other - 作为加数的货币对象。
    
    Returns:
    
    相加后的结果。
    
    Throws:
    
    IllegalArgumentException - 如果本货币对象与另一货币对象币种不同。
  - addTo
```
public Money addTo(Money other)
```
    货币累加。
    如果两货币币种相同，则本货币对象的金额等于两货币对象金额之和，并返回本货币对象的引用。如果两货币对象币种不同，抛出java.lang.IllegalArgumentException。
    
    Parameters:
    
    other - 作为加数的货币对象。
    
    Returns:
    
    累加后的本货币对象。
    
    Throws:
    
    IllegalArgumentException - 如果本货币对象与另一货币对象币种不同。
  - subtract
```
public Money subtract(Money other)
```
    货币减法。
    如果两货币币种相同，则返回一个新的相同币种的货币对象，其金额为本货币对象的金额减去参数货币对象的金额。本货币对象的值不变。如果两货币币种不同，抛出java.lang.IllegalArgumentException。
    
    Parameters:
    
    other - 作为减数的货币对象。
    
    Returns:
    
    相减后的结果。
    
    Throws:
    
    IllegalArgumentException - 如果本货币对象与另一货币对象币种不同。
  - subtractFrom
```
public Money subtractFrom(Money other)
```
    货币累减。
    如果两货币币种相同，则本货币对象的金额等于两货币对象金额之差，并返回本货币对象的引用。如果两货币币种不同，抛出java.lang.IllegalArgumentException。
    
    Parameters:
    
    other - 作为减数的货币对象。
    
    Returns:
    
    累减后的本货币对象。
    
    Throws:
    
    IllegalArgumentException - 如果本货币对象与另一货币对象币种不同。
  - multiply
```
public Money multiply(long val)
```
    货币乘法。
    返回一个新的货币对象，币种与本货币对象相同，金额为本货币对象的金额乘以乘数。本货币对象的值不变。
    
    Parameters:
    
    val - 乘数
    
    Returns:
    
    乘法后的结果。
  - multiplyBy
```
public Money multiplyBy(long val)
```
    货币累乘。
    本货币对象金额乘以乘数，并返回本货币对象。
    
    Parameters:
    
    val - 乘数
    
    Returns:
    
    累乘后的本货币对象。
  - multiply
```
public Money multiply(double val)
```
    货币乘法。
    返回一个新的货币对象，币种与本货币对象相同，金额为本货币对象的金额乘以乘数。本货币对象的值不变。如果相乘后的金额不能转换为整数分，则四舍五入。
    
    Parameters:
    
    val - 乘数
    
    Returns:
    
    相乘后的结果。
  - multiplyBy
```
public Money multiplyBy(double val)
```
    货币累乘。
    本货币对象金额乘以乘数，并返回本货币对象。如果相乘后的金额不能转换为整数分，则使用四舍五入。
    
    Parameters:
    
    val - 乘数
    
    Returns:
    
    累乘后的本货币对象。
  - multiply
```
public Money multiply(BigDecimal val)
```
    货币乘法。
    返回一个新的货币对象，币种与本货币对象相同，金额为本货币对象的金额乘以乘数。本货币对象的值不变。如果相乘后的金额不能转换为整数分，使用缺省的取整模式 DEFUALT_ROUNDING_MODE进行取整。
    
    Parameters:
    
    val - 乘数
    
    Returns:
    
    相乘后的结果。
  - multiplyBy
```
public Money multiplyBy(BigDecimal val)
```
    货币累乘。
    本货币对象金额乘以乘数，并返回本货币对象。如果相乘后的金额不能转换为整数分，使用缺省的取整方式 DEFUALT_ROUNDING_MODE进行取整。
    
    Parameters:
    
    val - 乘数
    
    Returns:
    
    累乘后的结果。
  - multiply
```
public Money multiply(BigDecimal val,
                      RoundingMode roundingMode)
```
    货币乘法。
    返回一个新的货币对象，币种与本货币对象相同，金额为本货币对象的金额乘以乘数。本货币对象的值不变。如果相乘后的金额不能转换为整数分，使用指定的取整方式 roundingMode进行取整。
    
    Parameters:
    
    val - 乘数
    
    roundingMode - 取整方式
    
    Returns:
    
    相乘后的结果。
  - multiplyBy
```
public Money multiplyBy(BigDecimal val,
                        RoundingMode roundingMode)
```
    货币累乘。
    本货币对象金额乘以乘数，并返回本货币对象。如果相乘后的金额不能转换为整数分，使用指定的取整方式 roundingMode进行取整。
    
    Parameters:
    
    val - 乘数
    
    roundingMode - 取整方式
    
    Returns:
    
    累乘后的结果。
  - divide
```
public Money divide(double val)
```
    货币除法。
    返回一个新的货币对象，币种与本货币对象相同，金额为本货币对象的金额除以除数。本货币对象的值不变。如果相除后的金额不能转换为整数分，使用四舍五入方式取整。
    
    Parameters:
    
    val - 除数
    
    Returns:
    
    相除后的结果。
  - divideBy
```
public Money divideBy(double val)
```
    货币累除。
    本货币对象金额除以除数，并返回本货币对象。如果相除后的金额不能转换为整数分，使用四舍五入方式取整。
    
    Parameters:
    
    val - 除数
    
    Returns:
    
    累除后的结果。
  - divide
```
public Money divide(BigDecimal val)
```
    货币除法。
    返回一个新的货币对象，币种与本货币对象相同，金额为本货币对象的金额除以除数。本货币对象的值不变。如果相除后的金额不能转换为整数分，使用缺省的取整模式 DEFAULT_ROUNDING_MODE进行取整。
    
    Parameters:
    
    val - 除数
    
    Returns:
    
    相除后的结果。
  - divide
```
public Money divide(BigDecimal val,
                    RoundingMode roundingMode)
```
    货币除法。
    返回一个新的货币对象，币种与本货币对象相同，金额为本货币对象的金额除以除数。本货币对象的值不变。如果相除后的金额不能转换为整数分，使用指定的取整模式 roundingMode进行取整。
    
    Parameters:
    
    val - 除数
    
    roundingMode - 取整
    
    Returns:
    
    相除后的结果。
  - divideBy
```
public Money divideBy(BigDecimal val)
```
    货币累除。
    本货币对象金额除以除数，并返回本货币对象。如果相除后的金额不能转换为整数分，使用缺省的取整模式 DEFAULT_ROUNDING_MODE进行取整。
    
    Parameters:
    
    val - 除数
    
    Returns:
    
    累除后的结果。
  - divideBy
```
public Money divideBy(BigDecimal val,
                      RoundingMode roundingMode)
```
    货币累除。
    本货币对象金额除以除数，并返回本货币对象。如果相除后的金额不能转换为整数分，使用指定的取整模式 roundingMode进行取整。
    
    Parameters:
    
    val - 除数
    
    roundingMode - 保留小数方式
    
    Returns:
    
    累除后的结果。
  - allocate
```
public Money[] allocate(int targets)
```
    货币分配。
    将本货币对象尽可能平均分配成targets份。如果不能平均分配尽，则将零头放到开始的若干份中。分配运算能够确保不会丢失金额零头。
    
    Parameters:
    
    targets - 待分配的份数
    
    Returns:
    
    货币对象数组，数组的长度与分配份数相同，数组元素从大到小排列，所有货币对象的金额最多只相差1分。
  - allocate
```
public Money[] allocate(long[] ratios)
```
    货币分配。
    将本货币对象按照规定的比例分配成若干份。分配所剩的零头从第一份开始顺序分配。分配运算确保不会丢失金额零头。
    
    Parameters:
    
    ratios - 分配比例数组，每一个比例是一个长整型，代表相对于总数的相对数。
    
    Returns:
    
    货币对象数组，数组的长度与分配比例数组的长度相同。
  - toString
```
public String toString()
```
    生成本对象的缺省字符串表示
    
    Overrides:
    
    toString in class Object
  - assertSameCurrencyAs
```
protected void assertSameCurrencyAs(Money other)
```
    断言本货币对象与另一货币对象是否具有相同的币种。
    如果本货币对象与另一货币对象具有相同的币种，则方法返回。否则抛出运行时异常java.lang.IllegalArgumentException。
    
    Parameters:
    
    other - 另一货币对象
    
    Throws:
    
    IllegalArgumentException - 如果本货币对象与另一货币对象币种不同。
  - rounding
```
protected long rounding(BigDecimal val,
                        RoundingMode roundingMode)
```
    对BigDecimal型的值按指定取整方式取整。
    
    Parameters:
    
    val - 待取整的BigDecimal值
    
    roundingMode - 取整方式
    
    Returns:
    
    取整后的long型值
  - newMoneyWithSameCurrency
```
protected Money newMoneyWithSameCurrency(long cent)
```
    创建一个币种相同，具有指定金额的货币对象。
    
    Parameters:
    
    cent - 金额，以分为单位
    
    Returns:
    
    一个新建的币种相同，具有指定金额的货币对象
  - dump
```
public String dump()
```
    生成本对象内部变量的字符串表示，用于调试。
    
    Returns:
    
    本对象内部变量的字符串表示。
  - setCent
```
public void setCent(long cent)
```
    设置货币的分值。
    
    Parameters:
    
    cent - 分值

Class Money

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_CURRENCY_CODE

DEFAULT_ROUNDING_MODE

Constructor Detail

Money

Money

Money

Money

Money

Money

Money

Money

Money

Money

Money

Money

Method Detail

getAmount

setAmount

getCent

getCurrency

getCentFactor

equals

equals

hashCode

compareTo

greaterThan

add

addTo

subtract

subtractFrom

multiply

multiplyBy

multiply

multiplyBy

multiply

multiplyBy

multiply

multiplyBy

divide

divideBy

divide

divide

divideBy

divideBy

allocate

allocate

toString

assertSameCurrencyAs

rounding

newMoneyWithSameCurrency

dump

setCent