# 数字辅助函数

数字辅助辅助函数文件包含了一些函数，用于根据区域设置来处理数值数据。

## 加载此辅助函数

使用以下代码加载此辅助函数：

    <?php

    helper('number');

## 出现错误时

如果在指定的区域设置和选项下，PHP 的国际化与本地化逻辑无法处理传入的值，则会抛出 `BadFunctionCallException()` 异常。

## 可用函数

提供以下函数：

number_to_size($num[, $precision = 1[, $locale = null]])
  参数:

    - $num (`mixed`) -- 字节数

    - $precision (`int`) -- 浮点精度

  返回:

    格式化后的数据大小字符串，如果提供的值不是数字则返回 false

  返回类型:

    `string`

  根据大小将数字格式化为字节，并添加适当的后缀。示例：

      <?php

      echo number_to_size(456); // Returns 456 Bytes
      echo number_to_size(4567); // Returns 4.5 KB
      echo number_to_size(45678); // Returns 44.6 KB
      echo number_to_size(456789); // Returns 447.8 KB
      echo number_to_size(3456789); // Returns 3.3 MB
      echo number_to_size(12345678912345); // Returns 1.8 GB
      echo number_to_size(123456789123456789); // Returns 11,228.3 TB

  可选的第二个参数允许你设置结果的精度：

      <?php

      echo number_to_size(45678, 2); // Returns 44.61 KB

  可选的第三个参数允许你指定生成数字时应使用的区域设置，这可能影响格式化。如果未指定区域设置，将分析请求并从头部获取适当的区域设置，或使用应用程序默认值：

      <?php

      // Generates 11.2 TB
      echo number_to_size(12345678912345, 1, 'en_US');
      // Generates 11,2 TB
      echo number_to_size(12345678912345, 1, 'fr_FR');

  备注

  此函数生成的文本可在以下语言文件中找到：language/<your_lang>/Number.php

number_to_amount($num[, $precision = 1[, $locale = null])
  参数:

    - $num (`mixed`) -- 要格式化的数字

    - $precision (`int`) -- 浮点精度

    - $locale (`string`) -- 用于格式化的区域设置

  返回:

    人类可读的字符串版本，如果提供的值不是数字则返回 false

  返回类型:

    `string`

  将数字转换为人类可读的版本，如对于高达千万亿级的数字显示为 123.4 万亿 （最大支持千万亿级数字）。示例：

      <?php

      echo number_to_amount(123456); // Returns 123 thousand
      echo number_to_amount(123456789); // Returns 123 million
      echo number_to_amount(1234567890123, 2); // Returns 1.23 trillion
      echo number_to_amount('123,456,789,012', 2); // Returns 123.46 billion

  可选的第二个参数允许你设置结果的精度：

      <?php

      echo number_to_amount(45678, 2); // Returns 45.68 thousand

  可选的第三个参数允许指定区域设置：

      <?php

      echo number_to_amount('123,456,789,012', 2, 'de_DE'); // Returns 123,46 billion

number_to_currency($num, $currency[, $locale = null[, $fraction = 0]])
  参数:

    - $num (`float`) -- 要格式化的数字

    - $currency (`string`) -- 货币类型，如 USD、EUR 等

    - $locale (`string|null`) -- 用于格式化的区域设置

    - $fraction (`integer`) -- 小数点后的分数位数

  返回:

    适合该区域设置的货币格式的数字

  返回类型:

    `string`

  将数字转换为通用货币格式，如 USD、EUR、GBP 等：

      <?php

      echo number_to_currency(1234.56, 'USD', 'en_US', 2);  // Returns $1,234.56
      echo number_to_currency(1234.56, 'EUR', 'de_DE', 2);  // Returns 1.234,56 €
      echo number_to_currency(1234.56, 'GBP', 'en_GB', 2);  // Returns £1,234.56
      echo number_to_currency(1234.56, 'YEN', 'ja_JP', 2);  // Returns YEN 1,234.56

  如果不指定区域设置，将使用请求的区域设置。

number_to_roman($num)
  参数:

    - $num (`int|string`) -- 要转换的数字

  返回:

    从给定参数转换的罗马数字

  返回类型:

    `string|null`

  将数字转换为罗马数字：

      <?php

      echo number_to_roman(23);    // Returns XXIII
      echo number_to_roman(324);   // Returns CCCXXIV
      echo number_to_roman(2534);  // Returns MMDXXXIV

  此函数仅处理 1 到 3999 范围内的数字。 对于超出该范围的任何值，它将返回 `null`。