safe-currency API

# 初始化 
自定义配置，默认以人民币为准，也可以根据设置覆盖。

```javascript
import currency from 'safe-currency'
new currency(value, opts)=> currencyObj
type valueType = {number|string|JSBD|BigInt}
defaultOpts=
{
symbol: '¥',
separator: ',',
decimal: '.',
precision: 2,
pattern: '!#',
format:null,
strict: false,
showTail0:false,
fromCents: false
}
```

### symbol  默认: "￥"

货币符号

```javascript
new currency(1.23).format(); // => "￥ 1.23"
```

### separator  默认: ","

千分位分隔符

```javascript
new currency(1234.56, { separator: "," }).format(); // => "￥ 1,234.56"
new currency(1234.56, { separator: " " }).format(); // => "￥ 1 234.56"
```

### decimal  默认: "."

小数点符号

```javascript
new currency(1.23, { decimal: "." }).format(); // => "￥ 1.23"
new currency(1.23, { decimal: "," }).format(); // => "￥ 1,23"
```

### precision  默认: 2

精度

```javascript
new currency(1.234, { precision: 2 }); // => "1.23"
new currency(1.234, { precision: 3 }); // => "1.234"
```

### pattern  默认: !#

!指代金额，#指代符号

```javascript
new currency(1.23, {
  pattern: `# !`,
}).format(); // => "1.23 $"
```

### format  默认: null

自定义 format 函数

```javascript
function format(currency, options) {
  return `${currency.yuan()}.${currency.cents()}`;
}
new currency(1234.56, { format: format }).format(); // => "1234.56"
```

### strict  默认: false

错误输入是否报错

```javascript
new currency("12 哈哈.2"); // 12.2
new currency(undefined); // 0
new currency("12 哈哈.2", { errorOnInvalid: true }); // throws an error
new currency(undefined, { errorOnInvalid: true }); // throws an error
```

### showTail0  默认: true

是否显示小数点后末尾零

```javascript
new currency("123.00").format(); // =>'￥ 123.00'
new currency("123.00", { showTail0: false }).format(); // =>'￥ 123'
```

### fromCents  默认: false

以分为单位创建 currency（运算后不继承）

```javascript
new currency("123").format(); // =>'￥ 123.00'
new currency("123", { fromCents: true }).format(); // =>'￥ 1.23'
```

# 属性

### JSBDVal

currency.JSBDVal
返回原始的 JSBD 类型

```javascript
new currency(123.45).JSBDVal; // => JSBD 对象
```

### value

currency.value
返回字符串表示

```javascript
new currency(123.45).value; // => '123.45'
```

# 方法

### add

```javascript
currency.add(value);
```

支持输入 string、number、currency、JSBD、BigInt，支持链式调用，运算结果继承配置

```javascript
new currency(123.45).add(0.01).toString(); // => "123.46"
```

### subtract

```javascript
currency.subtract(value);
```

支持输入 string、number、currency、JSBD、BigInt，支持链式调用，运算结果继承配置

```javascript
new currency(123.45).subtract(0.01).toString(); // => "123.44"
```

### multiply

```javascript
currency.multiply(number);
```

支持输入 string、number、currency、JSBD、BigInt，支持链式调用，运算结果继承配置

```javascript
new currency(123.45).multiply(2).toString(); // => "246.90"
```

### divide

```javascript
currency.divide(number);
```

支持输入 string、number、currency、JSBD、BigInt，支持链式调用，运算结果继承配置

```javascript
new currency(123.45).divide(2).toString(); // => "61.73"
```

### distribute

```javascript
currency.distribute(string | number | JSBD | BigInt);
```

不可被整除的场景，支持输入 string、number、JSBD、BigInt。（仅整数）

```javascript
new currency(1).distribute(3); // => [0.34, 0.33, 0.33]
new currency(12.35).distribute(3); // => [4.12, 4.12, 4.11]
new currency(12.0).distribute(3); // => [4.00, 4.00, 4.00]
```

### compareTo

```javascript
currency.compareTo(number);
```

比较大小，支持输入 string、number、currency、JSBD、BigInt，返回-1,0,1（可用于排序）

```javascript
new currency(1).compareTo(currency(2)); // =>-1
```

### chineseNumber

```javascript
currency.chineseNumber();
```

转中文数字

```javascript
new currency(12345.67).chineseNumber(); // =>"壹万贰仟叁佰肆拾伍元陆角柒分"
```

### format

```javascript
currency.format(options);
```

格式化，支持自定义配置，支持自动推断

```javascript
new currency(1000.0).format(); // => "￥ 1,000.00"
new currency(1000.0, { symbol: "￥", precision: 3 }).format(); // => "￥ 1,000.000"
new currency(1000.0).format({ symbol: "￥", precision: 3 }); // => "￥ 1,000.000"
new currency(1000.0).format({ formatter: () => "烫烫" }); // => "烫烫"
new currency("£1234.500").format(); // =>'£1,234.500' (自动推断货币为 £, 精度 3 位)
```

### toString

```javascript
currency.toString();
```

返回以元为单位的表示( 同 yuan() )

```javascript
new currency(123.45).toString(); // => 123.45
new currency("0.99").toString(); // => 0.99
new currency("1").toString(); // => 1
```

### yuan

currency.yuan()
返回以元为单位的表示，超出 2 位精度四舍五入

```javascript
new currency("0.99").yuan(); // => 0.99
new currency("1").yuan(); // => 1
new currency(123.45).yuan(); // => 123.45
new currency(123.459).yuan(); // => 123.46
```

### cents

currency.cents()
返回以分为单位的表示，超出 0 位精度四舍五入

```javascript
new currency("0.99").cents(); // => 99
new currency("1").cents(); // => 100
new currency(123.45).cents(); // => 12345
new currency(123.459).cents(); // => 12346
```