safe-currency API

初始化

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

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 默认: "￥"

货币符号

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

separator 默认: ","

千分位分隔符

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

decimal 默认: "."

小数点符号

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

precision 默认: 2

精度

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

pattern 默认: !#

!指代金额，#指代符号

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

format 默认: null

自定义 format 函数

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

strict 默认: false

错误输入是否报错

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

是否显示小数点后末尾零

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

fromCents 默认: false

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

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

属性

JSBDVal

currency.JSBDVal 返回原始的 JSBD 类型

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

value

currency.value 返回字符串表示

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

方法

add

currency.add(value);

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

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

subtract

currency.subtract(value);

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

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

multiply

currency.multiply(number);

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

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

divide

currency.divide(number);

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

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

distribute

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

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

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

currency.compareTo(number);

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

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

chineseNumber

currency.chineseNumber();

转中文数字

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

format

currency.format(options);

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

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

currency.toString();

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

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

yuan

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

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 位精度四舍五入

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