diff --git a/appendices/examples.xml b/appendices/examples.xml new file mode 100644 index 000000000..2469053b0 --- /dev/null +++ b/appendices/examples.xml @@ -0,0 +1,32 @@ + + + + + 关于手册示例 + + 需要注意的是，为了清晰简洁，PHP 文档中的许多示例都省略了错误和异常处理。 + + + 这并不意味着生产环境代码可以省略错误处理，因为此举可能会引发 TypeError 错误、强制转换失败值（例如将布尔值 &false; 转为空字符串），或是违背代码预设逻辑，进而产生难以排查的隐蔽漏洞。部分扩展库提供了完整示例，其中均包含错误处理逻辑，用以演示该扩展所提供各类函数与方法的规范用法。 + + + diff --git a/reference/bc/bcmath.number.xml b/reference/bc/bcmath.number.xml new file mode 100644 index 000000000..941cdb482 --- /dev/null +++ b/reference/bc/bcmath.number.xml @@ -0,0 +1,124 @@ + + + + + + BcMath\Number 类 + BcMath\Number + + +
+ &reftitle.intro; + + 用于任意精度数字的类。 + 这些对象支持重载的 + 算术 和 + 比较 运算符。 + + + + + 此类不受 + bcmath.scale + 在 &php.ini; 中设置的 INI 指令影响。 + + + + + + 重载运算符的行为与在相应方法上为 + scale 参数指定 &null; 相同。 + + +
+ +
+ &reftitle.classsynopsis; + + + BcMath + + + + final + readonly + Number + + + + implements + Stringable + + + &Properties; + + public + string + value + + + public + int + scale + + + &Methods; + + + + + + + + +
+ +
+ &reftitle.properties; + + + value + + + 任意精度数字的字符串表示。 + + + + + scale + + + 当前在对象上设置的精度值。 + 对于计算结果的对象，此值会自动计算和设置， + 除非在计算方法中设置了 scale 参数。 + + + + +
+ + + + &reference.bc.bcmath.entities.number; + + + diff --git a/reference/bc/bcmath/number/add.xml b/reference/bc/bcmath/number/add.xml new file mode 100644 index 000000000..b4c1bd1e3 --- /dev/null +++ b/reference/bc/bcmath/number/add.xml @@ -0,0 +1,195 @@ + + + + + + BcMath\Number::add + 加法运算（任意精度数字） + + + + &reftitle.description; + + public BcMath\NumberBcMath\Number::add + BcMath\Numberstringintnum + intnullscale&null; + + + 将 $this 和 num 相加。 + + + + + &reftitle.parameters; + + + num + + + 要相加的值。 + + + + + scale + + + 为计算结果显式指定的 BcMath\Number::scale。 + 如果为 &null;，计算结果的 BcMath\Number::scale 将自动设置。 + + + + + + + + &reftitle.returnvalues; + + 返回加法运算的结果，为新的 BcMath\Number 对象。 + + + 当结果对象的 BcMath\Number::scale 自动设置时， + 将使用加法运算中两个数字的较大 BcMath\Number::scale 值。 + + + 例如，如果两个值的 BcMath\Number::scale 分别为 2 + 和 5，则结果的 BcMath\Number::scale + 将为 5。 + + + + + &reftitle.errors; + + 以下情况会抛出 ValueError 异常： + + num 是 string 类型但不是格式正确的 BCMath 数字字符串 + scale 超出有效范围 + + + + + + &reftitle.examples; + + <methodname>BcMath\Number::add</methodname> 示例：未指定 <parameter>scale</parameter> + +add(new BcMath\Number('2.34567')); +$ret2 = $number->add('-3.456'); +$ret3 = $number->add(7); + +var_dump($number, $ret1, $ret2, $ret3); +?> +]]> + + &example.outputs; + + + string(5) "1.234" + ["scale"]=> + int(3) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(7) "3.57967" + ["scale"]=> + int(5) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(6) "-2.222" + ["scale"]=> + int(3) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(5) "8.234" + ["scale"]=> + int(3) +} +]]> + + + + + <methodname>BcMath\Number::add</methodname> 示例：显式指定 <parameter>scale</parameter> + +add(new BcMath\Number('2.34567'), 1); +$ret2 = $number->add('-3.456', 10); +$ret3 = $number->add(7, 0); + +var_dump($number, $ret1, $ret2, $ret3); +?> +]]> + + &example.outputs; + + + string(5) "1.234" + ["scale"]=> + int(3) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(3) "3.5" + ["scale"]=> + int(1) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(13) "-2.2220000000" + ["scale"]=> + int(10) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(1) "8" + ["scale"]=> + int(0) +} +]]> + + + + + + &reftitle.seealso; + + bcadd + BcMath\Number::sub + + + + + diff --git a/reference/bc/bcmath/number/ceil.xml b/reference/bc/bcmath/number/ceil.xml new file mode 100644 index 000000000..e5976619d --- /dev/null +++ b/reference/bc/bcmath/number/ceil.xml @@ -0,0 +1,104 @@ + + + + + + BcMath\Number::ceil + 向上取整任意精度数字 + + + + &reftitle.description; + + public BcMath\NumberBcMath\Number::ceil + + + + 通过向上取整（必要时）返回不小于 $this 的最小整数。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + 返回结果为新的 BcMath\Number 对象。 + 结果的 BcMath\Number::scale 始终为 0。 + + + + + &reftitle.examples; + + <methodname>BcMath\Number::ceil</methodname> 示例 + +ceil(); +$num2 = new BcMath\Number('9.999')->ceil(); +$num3 = new BcMath\Number('-3.14')->ceil(); + +var_dump($num1, $num2, $num3); +?> +]]> + + &example.outputs; + + + string(1) "5" + ["scale"]=> + int(0) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(2) "10" + ["scale"]=> + int(0) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(2) "-3" + ["scale"]=> + int(0) +} +]]> + + + + + + &reftitle.seealso; + + bcceil + BcMath\Number::floor + BcMath\Number::round + + + + + diff --git a/reference/bc/bcmath/number/compare.xml b/reference/bc/bcmath/number/compare.xml new file mode 100644 index 000000000..88508783f --- /dev/null +++ b/reference/bc/bcmath/number/compare.xml @@ -0,0 +1,142 @@ + + + + + + BcMath\Number::compare + 比较两个任意精度数字 + + + + &reftitle.description; + + public intBcMath\Number::compare + BcMath\Numberstringintnum + intnullscale&null; + + + 比较两个任意精度数字。 + 此方法的行为类似于 太空船运算符。 + + + + + &reftitle.parameters; + + + num + + + 要进行比较的值。 + + + + + scale + + + 指定比较时使用的 scale。 + 如果为 &null;，则比较时使用所有数字。 + + + + + + + + &reftitle.returnvalues; + + 如果两个数字相等则返回 0， + 如果 $this 大于 num 则返回 1， + 否则返回 -1。 + + + + + + + + &reftitle.examples; + + <methodname>BcMath\Number::compare</methodname> 示例：未指定 <parameter>scale</parameter> + +compare(new BcMath\Number('1.234')), + $number->compare('1.23400'), + $number->compare('1.23401'), + $number->compare(1), +); +?> +]]> + + &example.outputs; + + + + + + + <methodname>BcMath\Number::compare</methodname> 示例：显式指定 <parameter>scale</parameter> + +compare(new BcMath\Number('1.299'), 1), + $number->compare('1.24', 2), + $number->compare('1.22', 2), + $number->compare(1, 0), +); +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + bccomp + + + + + diff --git a/reference/bc/bcmath/number/construct.xml b/reference/bc/bcmath/number/construct.xml new file mode 100644 index 000000000..71c59cdb7 --- /dev/null +++ b/reference/bc/bcmath/number/construct.xml @@ -0,0 +1,116 @@ + + + + + + BcMath\Number::__construct + 创建 BcMath\Number 对象 + + + + &reftitle.description; + + public BcMath\Number::__construct + stringintnum + + + 从 int 或 string 值创建 BcMath\Number 对象。 + + + + + &reftitle.parameters; + + + num + + + 一个 int 或 string 值。 + 如果 num 是 int， + 则 BcMath\Number::scale 始终设置为 0。 + 如果 num 是 string，它必须是有效的数字， + 并且 BcMath\Number::scale 通过解析字符串自动设置。 + + + + + + + + &reftitle.errors; + + 如果 num 是 string 且不是格式正确的 BCMath 数字字符串， + 此方法会抛出 ValueError 异常。 + + + + + &reftitle.examples; + + <methodname>BcMath\Number::__construct</methodname> 示例 + + +]]> + + &example.outputs; + + + string(3) "100" + ["scale"]=> + int(0) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(4) "-200" + ["scale"]=> + int(0) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(6) "300.00" + ["scale"]=> + int(2) +} +]]> + + + + + + &reftitle.seealso; + + BcMath\Number::__serialize + BcMath\Number::__unserialize + + + + + diff --git a/reference/bc/bcmath/number/div.xml b/reference/bc/bcmath/number/div.xml new file mode 100644 index 000000000..0d6248e6d --- /dev/null +++ b/reference/bc/bcmath/number/div.xml @@ -0,0 +1,245 @@ + + + + + + BcMath\Number::div + 除法运算（任意精度数字） + + + + &reftitle.description; + + public BcMath\NumberBcMath\Number::div + BcMath\Numberstringintnum + intnullscale&null; + + + 将 $this 除以 num。 + + + + + &reftitle.parameters; + + + num + + + 除数。 + + + + + + + + + &reftitle.returnvalues; + + 返回除法运算的结果，为新的 BcMath\Number 对象。 + + + 当结果对象的 BcMath\Number::scale 自动设置时， + 使用被除数的 BcMath\Number::scale。但在无法整除的情况下， + 结果的 BcMath\Number::scale 会被扩展。 + 扩展仅在需要时进行，最多扩展 +10。 + + + 例如，如果被除数的 BcMath\Number::scale 为 5， + 则结果的 BcMath\Number::scale 将在 5 到 + 15 之间。 + + + 即使在无法整除的计算中，BcMath\Number::scale 也不总是 + +10。 + 结果末尾的 0 被视为不需要扩展，因此 + BcMath\Number::scale 会减少相应的数量。 + BcMath\Number::scale 永远不会小于扩展前的 + BcMath\Number::scale。 + 另请参见 代码示例。 + + + + + &reftitle.errors; + + 以下情况会抛出 ValueError 异常： + + num 是 string 类型但不是格式正确的 BCMath 数字字符串 + scale 超出有效范围 + 结果对象的 BcMath\Number::scale 超出有效范围 + + + + 如果 num 为 0，此方法会抛出 + DivisionByZeroError 异常。 + + + + + &reftitle.examples; + + <methodname>BcMath\Number::div</methodname> 示例：未指定 <parameter>scale</parameter> + +div(new BcMath\Number('2.000')); +$ret2 = $number->div('-3'); +$ret3 = $number->div(32); + +var_dump($number, $ret1, $ret2, $ret3); +?> +]]> + + &example.outputs; + + + string(5) "0.002" + ["scale"]=> + int(3) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(5) "0.001" + ["scale"]=> + int(3) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(16) "-0.0006666666666" + ["scale"]=> + int(13) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(9) "0.0000625" + ["scale"]=> + int(7) +} +]]> + + + + + <methodname>BcMath\Number::div</methodname> 示例：显式指定 <parameter>scale</parameter> + +div(new BcMath\Number('2.000'), 15); +$ret2 = $number->div('-3', 5); +$ret3 = $number->div(32, 2); + +var_dump($number, $ret1, $ret2, $ret3); +?> +]]> + + &example.outputs; + + + string(5) "0.002" + ["scale"]=> + int(3) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(17) "0.001000000000000" + ["scale"]=> + int(15) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(8) "-0.00066" + ["scale"]=> + int(5) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(4) "0.00" + ["scale"]=> + int(2) +} +]]> + + + + + <methodname>BcMath\Number::div</methodname> 示例：结果对象 <property>BcMath\Number::scale</property> 的扩展 + +div('10001'), + new BcMath\Number('0.001')->div('10001', 13), + new BcMath\Number('0.001')->div('100000000000001'), +); +?> +]]> + + &example.outputs; + + + string(13) "0.00000009999" + ["scale"]=> + int(11) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(15) "0.0000000999900" + ["scale"]=> + int(13) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(5) "0.000" + ["scale"]=> + int(3) +} +]]> + + + + + + &reftitle.seealso; + + bcdiv + BcMath\Number::divmod + BcMath\Number::mod + BcMath\Number::sqrt + BcMath\Number::pow + BcMath\Number::mul + + + + + diff --git a/reference/bc/bcmath/number/divmod.xml b/reference/bc/bcmath/number/divmod.xml new file mode 100644 index 000000000..d051e37a5 --- /dev/null +++ b/reference/bc/bcmath/number/divmod.xml @@ -0,0 +1,223 @@ + + + + + + BcMath\Number::divmod + 获取任意精度数字的商和余数 + + + + &reftitle.description; + + public arrayBcMath\Number::divmod + BcMath\Numberstringintnum + intnullscale&null; + + + 获取将 $this 除以 num 的商和余数。 + + + + + + + + &reftitle.returnvalues; + + 返回一个索引 array，其中第一个元素是商（新的 + BcMath\Number 对象），第二个元素是余数（新的 + BcMath\Number 对象）。 + + + 商始终是整数值，因此商的 BcMath\Number::scale 始终为 + 0，无论是否显式指定 scale。 + + + 如果显式指定了 scale，余数的 BcMath\Number::scale + 将为指定的值。 + 当结果余数对象的 BcMath\Number::scale 自动设置时， + 将使用取余运算中两个数字的较大 BcMath\Number::scale 值。 + + + 例如，如果两个值的 BcMath\Number::scale 分别为 2 + 和 5，则余数的 BcMath\Number::scale + 将为 5。 + + + + + &reftitle.errors; + + + + + + + + &reftitle.examples; + + <methodname>BcMath\Number::divmod</methodname> 示例：未指定 <parameter>scale</parameter> + +divmod(new BcMath\Number('2.22')); +var_dump($quot, $rem); + +echo PHP_EOL . '8.3 / 8.3' . PHP_EOL; +[$quot, $rem] = new BcMath\Number('8.3')->divmod('8.3'); +var_dump($quot, $rem); + +echo PHP_EOL . '10 / -3' . PHP_EOL; +[$quot, $rem] = new BcMath\Number('10')->divmod(-3); +var_dump($quot, $rem); +?> +]]> + + &example.outputs; + + + string(1) "3" + ["scale"]=> + int(0) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(4) "1.34" + ["scale"]=> + int(2) +} + +8.3 / 8.3 +object(BcMath\Number)#2 (2) { + ["value"]=> + string(1) "1" + ["scale"]=> + int(0) +} +object(BcMath\Number)#5 (2) { + ["value"]=> + string(3) "0.0" + ["scale"]=> + int(1) +} + +10 / -3 +object(BcMath\Number)#3 (2) { + ["value"]=> + string(2) "-3" + ["scale"]=> + int(0) +} +object(BcMath\Number)#1 (2) { + ["value"]=> + string(1) "1" + ["scale"]=> + int(0) +} +]]> + + + + + <methodname>BcMath\Number::divmod</methodname> 示例：显式指定 <parameter>scale</parameter> + +divmod(new BcMath\Number('2.22'), 1); +var_dump($quot, $rem); + +echo PHP_EOL . '8.3 / 8.3' . PHP_EOL; +[$quot, $rem] = new BcMath\Number('8.3')->divmod('8.3', 4); +var_dump($quot, $rem); + +echo PHP_EOL . '10 / -3' . PHP_EOL; +[$quot, $rem] = new BcMath\Number('10')->divmod(-3, 5); +var_dump($quot, $rem); +?> +]]> + + &example.outputs; + + + string(1) "3" + ["scale"]=> + int(0) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(3) "1.3" + ["scale"]=> + int(1) +} + +8.3 / 8.3 +object(BcMath\Number)#2 (2) { + ["value"]=> + string(1) "1" + ["scale"]=> + int(0) +} +object(BcMath\Number)#5 (2) { + ["value"]=> + string(6) "0.0000" + ["scale"]=> + int(4) +} + +10 / -3 +object(BcMath\Number)#3 (2) { + ["value"]=> + string(2) "-3" + ["scale"]=> + int(0) +} +object(BcMath\Number)#1 (2) { + ["value"]=> + string(7) "1.00000" + ["scale"]=> + int(5) +} +]]> + + + + + + &reftitle.seealso; + + bcdivmod + BcMath\Number::div + BcMath\Number::mod + + + + + diff --git a/reference/bc/bcmath/number/floor.xml b/reference/bc/bcmath/number/floor.xml new file mode 100644 index 000000000..ad5e0300a --- /dev/null +++ b/reference/bc/bcmath/number/floor.xml @@ -0,0 +1,99 @@ + + + + + + BcMath\Number::floor + 向下取整任意精度数字 + + + + &reftitle.description; + + public BcMath\NumberBcMath\Number::floor + + + + 通过向下取整（必要时）返回不大于 $this 的最大整数。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + + + + &reftitle.examples; + + <methodname>BcMath\Number::floor</methodname> 示例 + +floor(); +$num2 = new BcMath\Number('9.999')->floor(); +$num3 = new BcMath\Number('-3.14')->floor(); + +var_dump($num1, $num2, $num3); +?> +]]> + + &example.outputs; + + + string(1) "4" + ["scale"]=> + int(0) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(1) "9" + ["scale"]=> + int(0) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(2) "-4" + ["scale"]=> + int(0) +} +]]> + + + + + + &reftitle.seealso; + + bcfloor + BcMath\Number::ceil + BcMath\Number::round + + + + + diff --git a/reference/bc/bcmath/number/mod.xml b/reference/bc/bcmath/number/mod.xml new file mode 100644 index 000000000..76ceed9c9 --- /dev/null +++ b/reference/bc/bcmath/number/mod.xml @@ -0,0 +1,172 @@ + + + + + + BcMath\Number::mod + 获取任意精度数字的余数 + + + + &reftitle.description; + + public BcMath\NumberBcMath\Number::mod + BcMath\Numberstringintnum + intnullscale&null; + + + 获取将 $this 除以 num 的余数。 + 除非 num 为 0，否则结果与 $this 同符号。 + + + + + + + + &reftitle.returnvalues; + + 返回余数，为新的 BcMath\Number 对象。 + + + 当结果对象的 BcMath\Number::scale 自动设置时， + 将使用取余运算中两个数字的较大 BcMath\Number::scale 值。 + + + + + + + &reftitle.errors; + + + + + + + + &reftitle.examples; + + <methodname>BcMath\Number::mod</methodname> 示例：未指定 <parameter>scale</parameter> + +mod(new BcMath\Number('2.22')); +$ret2 = $number->mod('8.3'); +$ret3 = $number->mod(-5); + +var_dump($number, $ret1, $ret2, $ret3); +?> +]]> + + &example.outputs; + + + string(3) "8.3" + ["scale"]=> + int(1) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(4) "1.64" + ["scale"]=> + int(2) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(3) "0.0" + ["scale"]=> + int(1) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(3) "3.3" + ["scale"]=> + int(1) +} +]]> + + + + + <methodname>BcMath\Number::mod</methodname> 示例：显式指定 <parameter>scale</parameter> + +mod(new BcMath\Number('2.22'), 1); +$ret2 = $number->mod('8.3', 3); +$ret3 = $number->mod(-5, 0); + +var_dump($number, $ret1, $ret2, $ret3); +?> +]]> + + &example.outputs; + + + string(3) "8.3" + ["scale"]=> + int(1) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(3) "1.6" + ["scale"]=> + int(1) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(5) "0.000" + ["scale"]=> + int(3) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(1) "3" + ["scale"]=> + int(0) +} +]]> + + + + + + &reftitle.seealso; + + bcmod + BcMath\Number::div + BcMath\Number::divmod + BcMath\Number::powmod + + + + + diff --git a/reference/bc/bcmath/number/mul.xml b/reference/bc/bcmath/number/mul.xml new file mode 100644 index 000000000..071152baa --- /dev/null +++ b/reference/bc/bcmath/number/mul.xml @@ -0,0 +1,184 @@ + + + + + + BcMath\Number::mul + 乘法运算（任意精度数字） + + + + &reftitle.description; + + public BcMath\NumberBcMath\Number::mul + BcMath\Numberstringintnum + intnullscale&null; + + + 将 $this 乘以 num。 + + + + + &reftitle.parameters; + + + num + + + 乘数。 + + + + + + + + + &reftitle.returnvalues; + + 返回乘法运算的结果，为新的 BcMath\Number 对象。 + + + 当结果对象的 BcMath\Number::scale 自动设置时， + 使用乘法运算中两个值的 BcMath\Number::scale 之和。 + + + 例如，如果两个值的 BcMath\Number::scale 分别为 2 + 和 5，则结果的 BcMath\Number::scale + 将为 7。 + + + + + &reftitle.errors; + + + + + + &reftitle.examples; + + <methodname>BcMath\Number::mul</methodname> 示例：未指定 <parameter>scale</parameter> + +mul(new BcMath\Number('2.3456')); +$ret2 = $number->mul('-3.4'); +$ret3 = $number->mul(7); + +var_dump($number, $ret1, $ret2, $ret3); +?> +]]> + + &example.outputs; + + + string(5) "1.234" + ["scale"]=> + int(3) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(9) "2.8944704" + ["scale"]=> + int(7) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(7) "-4.1956" + ["scale"]=> + int(4) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(5) "8.638" + ["scale"]=> + int(3) +} +]]> + + + + + <methodname>BcMath\Number::mul</methodname> 示例：显式指定 <parameter>scale</parameter> + +mul(new BcMath\Number('2.3456'), 1); +$ret2 = $number->mul('-3.4', 10); +$ret3 = $number->mul(7, 0); + +var_dump($number, $ret1, $ret2, $ret3); +?> +]]> + + &example.outputs; + + + string(5) "1.234" + ["scale"]=> + int(3) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(3) "2.8" + ["scale"]=> + int(1) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(13) "-4.1956000000" + ["scale"]=> + int(10) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(1) "8" + ["scale"]=> + int(0) +} +]]> + + + + + + &reftitle.seealso; + + bcmul + BcMath\Number::div + BcMath\Number::pow + BcMath\Number::powmod + + + + + diff --git a/reference/bc/bcmath/number/pow.xml b/reference/bc/bcmath/number/pow.xml new file mode 100644 index 000000000..6eca4a430 --- /dev/null +++ b/reference/bc/bcmath/number/pow.xml @@ -0,0 +1,225 @@ + + + + + + BcMath\Number::pow + 幂运算（任意精度数字） + + + + &reftitle.description; + + public BcMath\NumberBcMath\Number::pow + BcMath\Numberstringintexponent + intnullscale&null; + + + 计算 $this 的 exponent 次方。 + + + + + &reftitle.parameters; + + + exponent + + + 指数。必须是没有小数部分的值。 + exponent 的有效范围取决于平台， + 但至少为 -2147483648 到 2147483647。 + + + + + + + + + &reftitle.returnvalues; + + 返回幂运算的结果，为新的 BcMath\Number 对象。 + + + 当结果对象的 BcMath\Number::scale 自动设置时， + 根据 exponent 的值，结果的 BcMath\Number::scale + 将如下所示： + + + + + exponent + 结果的 BcMath\Number::scale + + + + + 正数 + （底数的 BcMath\Number::scale） * （exponent 的值） + + + 0 + 0 + + + 负数 + 在（底数的 BcMath\Number::scale）到（底数的 BcMath\Number::scale + + 10）之间 + + + + + + + 如果由于负 exponent 而发生无法整除的除法，结果的 + BcMath\Number::scale 将被扩展。扩展仅在需要时进行，最多扩展 + +10。 + 此行为与 BcMath\Number::div 相同，详情请参见该方法。 + + + + + &reftitle.errors; + + 以下情况会抛出 ValueError 异常： + + exponent 是 string 类型但不是格式正确的 BCMath 数字字符串 + exponent 包含小数部分 + exponent 或 scale 超出有效范围 + 结果对象的 BcMath\Number::scale 超出有效范围 + + + + 如果 $this 的值为 0 且 exponent 为负值， + 此方法会抛出 DivisionByZeroError 异常。 + + + + + &reftitle.examples; + + <methodname>BcMath\Number::pow</methodname> 示例：未指定 <parameter>scale</parameter> + +pow(new BcMath\Number('5')); +$ret2 = $number->pow('-1'); +$ret3 = $number->pow(0); + +var_dump($number, $ret1, $ret2, $ret3); +?> +]]> + + &example.outputs; + + + string(3) "3.0" + ["scale"]=> + int(1) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(9) "243.00000" + ["scale"]=> + int(5) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(13) "0.33333333333" + ["scale"]=> + int(11) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(1) "1" + ["scale"]=> + int(0) +} +]]> + + + + + <methodname>BcMath\Number::pow</methodname> 示例：显式指定 <parameter>scale</parameter> + +pow(new BcMath\Number('5'), 0); +$ret2 = $number->pow('-1', 2); +$ret3 = $number->pow(0, 10); + +var_dump($number, $ret1, $ret2, $ret3); +?> +]]> + + &example.outputs; + + + string(3) "3.0" + ["scale"]=> + int(1) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(3) "243" + ["scale"]=> + int(0) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(4) "0.33" + ["scale"]=> + int(2) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(12) "1.0000000000" + ["scale"]=> + int(10) +} +]]> + + + + + + &reftitle.seealso; + + bcpow + BcMath\Number::powmod + BcMath\Number::mul + BcMath\Number::sqrt + BcMath\Number::div + + + + + diff --git a/reference/bc/bcmath/number/powmod.xml b/reference/bc/bcmath/number/powmod.xml new file mode 100644 index 000000000..b8936bdd1 --- /dev/null +++ b/reference/bc/bcmath/number/powmod.xml @@ -0,0 +1,198 @@ + + + + + + BcMath\Number::powmod + 幂取模运算（任意精度数字） + + + + &reftitle.description; + + public BcMath\NumberBcMath\Number::powmod + BcMath\Numberstringintexponent + BcMath\Numberstringintmodulus + intnullscale&null; + + + 使用快速幂算法计算 $this 的 exponent 次方， + 并对结果取 modulus 模。 + + + + + &reftitle.parameters; + + + exponent + + + 指数，必须是非负整数（即精度必须为零）。 + + + + + modulus + + + 模数，必须是整数（即精度必须为零）。 + + + + + + + + + &reftitle.returnvalues; + + 返回结果，为新的 BcMath\Number 对象。 + + + 当结果对象的 BcMath\Number::scale 自动设置时， + 结果对象的 BcMath\Number::scale 始终为 0。 + + + + + &reftitle.errors; + + 以下情况会抛出 ValueError 异常： + + exponent 或 modulus 是 string 类型但不是 + 格式正确的 BCMath 数字字符串 + $this、exponent 或 modulus 包含小数部分 + exponent 是负值 + scale 超出有效范围 + + + + 如果 modulus 为 0，此方法会抛出 + DivisionByZeroError 异常。 + + + + + &reftitle.examples; + + <methodname>BcMath\Number::powmod</methodname> 示例：未指定 <parameter>scale</parameter> + +powmod(new BcMath\Number('3'), 5), + new BcMath\Number('-8')->powmod(new BcMath\Number('3'), 5), + new BcMath\Number('8')->powmod('2', -3), + new BcMath\Number('-8')->powmod(5, 7), +); +?> +]]> + + &example.outputs; + + + string(1) "2" + ["scale"]=> + int(0) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(2) "-2" + ["scale"]=> + int(0) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(1) "1" + ["scale"]=> + int(0) +} +object(BcMath\Number)#5 (2) { + ["value"]=> + string(2) "-1" + ["scale"]=> + int(0) +} +]]> + + + + + <methodname>BcMath\Number::powmod</methodname> 示例：显式指定 <parameter>scale</parameter> + +powmod(new BcMath\Number('3'), 5, 1), + new BcMath\Number('-8')->powmod(new BcMath\Number('3'), 5, 2), + new BcMath\Number('8')->powmod('2', -3, 3), + new BcMath\Number('-8')->powmod(5, 7, 4), +); +?> +]]> + + &example.outputs; + + + string(3) "2.0" + ["scale"]=> + int(1) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(5) "-2.00" + ["scale"]=> + int(2) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(5) "1.000" + ["scale"]=> + int(3) +} +object(BcMath\Number)#5 (2) { + ["value"]=> + string(7) "-1.0000" + ["scale"]=> + int(4) +} +]]> + + + + + + &reftitle.seealso; + + bcpowmod + BcMath\Number::pow + BcMath\Number::mod + + + + + diff --git a/reference/bc/bcmath/number/round.xml b/reference/bc/bcmath/number/round.xml new file mode 100644 index 000000000..bf2980027 --- /dev/null +++ b/reference/bc/bcmath/number/round.xml @@ -0,0 +1,567 @@ + + + + + + BcMath\Number::round + 四舍五入任意精度数字 + + + + &reftitle.description; + + public BcMath\NumberBcMath\Number::round + intprecision0 + RoundingModemodeRoundingMode::HalfAwayFromZero + + + 返回 $this 四舍五入到指定 precision + （小数点后的位数）的值。 + precision 也可以是负数或零（默认值）。 + + + + + &reftitle.parameters; + + + + + mode + + + 指定四舍五入模式。有关模式的更多信息，请参见 RoundingMode。 + + + + + + + + &reftitle.returnvalues; + + 返回结果，为新的 BcMath\Number 对象。 + + + + + &reftitle.errors; + + 如果指定了无效的 mode，此方法会抛出 ValueError 异常。 + + + + + &reftitle.examples; + + <methodname>BcMath\Number::round</methodname> 示例 + +round(), + new BcMath\Number('3.5')->round(), + new BcMath\Number('3.6')->round(), + new BcMath\Number('3.6')->round(0), + new BcMath\Number('5.045')->round(2), + new BcMath\Number('5.055')->round(2), + new BcMath\Number('345')->round(-2), + new BcMath\Number('345')->round(-3), + new BcMath\Number('678')->round(-2), + new BcMath\Number('678')->round(-3), +); +?> +]]> + + &example.outputs; + + + string(1) "3" + ["scale"]=> + int(0) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(1) "4" + ["scale"]=> + int(0) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(1) "4" + ["scale"]=> + int(0) +} +object(BcMath\Number)#5 (2) { + ["value"]=> + string(1) "4" + ["scale"]=> + int(0) +} +object(BcMath\Number)#6 (2) { + ["value"]=> + string(4) "5.05" + ["scale"]=> + int(2) +} +object(BcMath\Number)#7 (2) { + ["value"]=> + string(4) "5.06" + ["scale"]=> + int(2) +} +object(BcMath\Number)#8 (2) { + ["value"]=> + string(3) "300" + ["scale"]=> + int(0) +} +object(BcMath\Number)#9 (2) { + ["value"]=> + string(1) "0" + ["scale"]=> + int(0) +} +object(BcMath\Number)#10 (2) { + ["value"]=> + string(3) "700" + ["scale"]=> + int(0) +} +object(BcMath\Number)#11 (2) { + ["value"]=> + string(4) "1000" + ["scale"]=> + int(0) +} +]]> + + + + + 使用不同 <parameter>precision</parameter> 值的 <methodname>BcMath\Number::round</methodname> 示例 + + +round(3), + $number->round(2), + $number->round(1), + $number->round(0), + $number->round(-1), + $number->round(-2), + $number->round(-3), +); +?> +]]> + + &example.outputs; + + + string(7) "123.450" + ["scale"]=> + int(3) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(6) "123.45" + ["scale"]=> + int(2) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(5) "123.5" + ["scale"]=> + int(1) +} +object(BcMath\Number)#5 (2) { + ["value"]=> + string(3) "123" + ["scale"]=> + int(0) +} +object(BcMath\Number)#6 (2) { + ["value"]=> + string(3) "120" + ["scale"]=> + int(0) +} +object(BcMath\Number)#7 (2) { + ["value"]=> + string(3) "100" + ["scale"]=> + int(0) +} +object(BcMath\Number)#8 (2) { + ["value"]=> + string(1) "0" + ["scale"]=> + int(0) +} +]]> + + + + + 使用不同 <parameter>mode</parameter> 值的 <methodname>BcMath\Number::round</methodname> 示例 + + +round(0, RoundingMode::HalfAwayFromZero), + $number->round(0, RoundingMode::HalfTowardsZero), + $number->round(0, RoundingMode::HalfEven), + $number->round(0, RoundingMode::HalfOdd), + $number->round(0, RoundingMode::TowardsZero), + $number->round(0, RoundingMode::AwayFromZero), + $number->round(0, RoundingMode::NegativeInfinity), + $number->round(0, RoundingMode::PositiveInfinity), +); + +echo PHP_EOL; +echo 'Rounding modes with 8.5' . PHP_EOL; +$number = new BcMath\Number('8.5'); +var_dump( + $number->round(0, RoundingMode::HalfAwayFromZero), + $number->round(0, RoundingMode::HalfTowardsZero), + $number->round(0, RoundingMode::HalfEven), + $number->round(0, RoundingMode::HalfOdd), + $number->round(0, RoundingMode::TowardsZero), + $number->round(0, RoundingMode::AwayFromZero), + $number->round(0, RoundingMode::NegativeInfinity), + $number->round(0, RoundingMode::PositiveInfinity), +); +?> +]]> + + &example.outputs; + + + string(2) "10" + ["scale"]=> + int(0) +} +object(BcMath\Number)#5 (2) { + ["value"]=> + string(1) "9" + ["scale"]=> + int(0) +} +object(BcMath\Number)#7 (2) { + ["value"]=> + string(2) "10" + ["scale"]=> + int(0) +} +object(BcMath\Number)#9 (2) { + ["value"]=> + string(1) "9" + ["scale"]=> + int(0) +} +object(BcMath\Number)#11 (2) { + ["value"]=> + string(1) "9" + ["scale"]=> + int(0) +} +object(BcMath\Number)#13 (2) { + ["value"]=> + string(2) "10" + ["scale"]=> + int(0) +} +object(BcMath\Number)#15 (2) { + ["value"]=> + string(1) "9" + ["scale"]=> + int(0) +} +object(BcMath\Number)#17 (2) { + ["value"]=> + string(2) "10" + ["scale"]=> + int(0) +} + +Rounding modes with 8.5 +object(BcMath\Number)#1 (2) { + ["value"]=> + string(1) "9" + ["scale"]=> + int(0) +} +object(BcMath\Number)#15 (2) { + ["value"]=> + string(1) "8" + ["scale"]=> + int(0) +} +object(BcMath\Number)#13 (2) { + ["value"]=> + string(1) "8" + ["scale"]=> + int(0) +} +object(BcMath\Number)#11 (2) { + ["value"]=> + string(1) "9" + ["scale"]=> + int(0) +} +object(BcMath\Number)#9 (2) { + ["value"]=> + string(1) "8" + ["scale"]=> + int(0) +} +object(BcMath\Number)#7 (2) { + ["value"]=> + string(1) "9" + ["scale"]=> + int(0) +} +object(BcMath\Number)#5 (2) { + ["value"]=> + string(1) "8" + ["scale"]=> + int(0) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(1) "9" + ["scale"]=> + int(0) +} +]]> + + + + + 指定 <parameter>precision</parameter> 时使用不同 <parameter>mode</parameter> 值的 <methodname>BcMath\Number::round</methodname> 示例 + + +round(1, RoundingMode::HalfAwayFromZero), + $negative->round(1, RoundingMode::HalfAwayFromZero), +); + +echo PHP_EOL; +echo 'Using RoundingMode::HalfTowardsZero with 1 decimal digit precision' . PHP_EOL; +var_dump( + $positive->round(1, RoundingMode::HalfTowardsZero), + $negative->round(1, RoundingMode::HalfTowardsZero), +); + +echo PHP_EOL; +echo 'Using RoundingMode::HalfEven with 1 decimal digit precision' . PHP_EOL; +var_dump( + $positive->round(1, RoundingMode::HalfEven), + $negative->round(1, RoundingMode::HalfEven), +); + +echo PHP_EOL; +echo 'Using RoundingMode::HalfOdd with 1 decimal digit precision' . PHP_EOL; +var_dump( + $positive->round(1, RoundingMode::HalfOdd), + $negative->round(1, RoundingMode::HalfOdd), +); + +echo PHP_EOL; +echo 'Using RoundingMode::TowardsZero with 1 decimal digit precision' . PHP_EOL; +var_dump( + $positive->round(1, RoundingMode::TowardsZero), + $negative->round(1, RoundingMode::TowardsZero), +); + +echo PHP_EOL; +echo 'Using RoundingMode::AwayFromZero with 1 decimal digit precision' . PHP_EOL; +var_dump( + $positive->round(1, RoundingMode::AwayFromZero), + $negative->round(1, RoundingMode::AwayFromZero), +); + +echo PHP_EOL; +echo 'Using RoundingMode::NegativeInfinity with 1 decimal digit precision' . PHP_EOL; +var_dump( + $positive->round(1, RoundingMode::NegativeInfinity), + $negative->round(1, RoundingMode::NegativeInfinity), +); + +echo PHP_EOL; +echo 'Using RoundingMode::PositiveInfinity with 1 decimal digit precision' . PHP_EOL; +var_dump( + $positive->round(1, RoundingMode::PositiveInfinity), + $negative->round(1, RoundingMode::PositiveInfinity), +); +?> +]]> + + &example.outputs; + + + string(3) "1.6" + ["scale"]=> + int(1) +} +object(BcMath\Number)#5 (2) { + ["value"]=> + string(4) "-1.6" + ["scale"]=> + int(1) +} + +Using RoundingMode::HalfTowardsZero with 1 decimal digit precision +object(BcMath\Number)#4 (2) { + ["value"]=> + string(3) "1.5" + ["scale"]=> + int(1) +} +object(BcMath\Number)#6 (2) { + ["value"]=> + string(4) "-1.5" + ["scale"]=> + int(1) +} + +Using RoundingMode::HalfEven with 1 decimal digit precision +object(BcMath\Number)#4 (2) { + ["value"]=> + string(3) "1.6" + ["scale"]=> + int(1) +} +object(BcMath\Number)#7 (2) { + ["value"]=> + string(4) "-1.6" + ["scale"]=> + int(1) +} + +Using RoundingMode::HalfOdd with 1 decimal digit precision +object(BcMath\Number)#4 (2) { + ["value"]=> + string(3) "1.5" + ["scale"]=> + int(1) +} +object(BcMath\Number)#8 (2) { + ["value"]=> + string(4) "-1.5" + ["scale"]=> + int(1) +} + +Using RoundingMode::TowardsZero with 1 decimal digit precision +object(BcMath\Number)#4 (2) { + ["value"]=> + string(3) "1.5" + ["scale"]=> + int(1) +} +object(BcMath\Number)#9 (2) { + ["value"]=> + string(4) "-1.5" + ["scale"]=> + int(1) +} + +Using RoundingMode::AwayFromZero with 1 decimal digit precision +object(BcMath\Number)#4 (2) { + ["value"]=> + string(3) "1.6" + ["scale"]=> + int(1) +} +object(BcMath\Number)#10 (2) { + ["value"]=> + string(4) "-1.6" + ["scale"]=> + int(1) +} + +Using RoundingMode::NegativeInfinity with 1 decimal digit precision +object(BcMath\Number)#4 (2) { + ["value"]=> + string(3) "1.5" + ["scale"]=> + int(1) +} +object(BcMath\Number)#11 (2) { + ["value"]=> + string(4) "-1.6" + ["scale"]=> + int(1) +} + +Using RoundingMode::PositiveInfinity with 1 decimal digit precision +object(BcMath\Number)#4 (2) { + ["value"]=> + string(3) "1.6" + ["scale"]=> + int(1) +} +object(BcMath\Number)#12 (2) { + ["value"]=> + string(4) "-1.5" + ["scale"]=> + int(1) +} +]]> + + + + + + &reftitle.seealso; + + bcround + BcMath\Number::ceil + BcMath\Number::floor + + + + + diff --git a/reference/bc/bcmath/number/serialize.xml b/reference/bc/bcmath/number/serialize.xml new file mode 100644 index 000000000..a0043b606 --- /dev/null +++ b/reference/bc/bcmath/number/serialize.xml @@ -0,0 +1,54 @@ + + + + + + BcMath\Number::__serialize + 序列化 BcMath\Number 对象 + + + + &reftitle.description; + + public arrayBcMath\Number::__serialize + + + + 序列化 $this。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.seealso; + + BcMath\Number::__construct + BcMath\Number::__unserialize + + + + + diff --git a/reference/bc/bcmath/number/sqrt.xml b/reference/bc/bcmath/number/sqrt.xml new file mode 100644 index 000000000..b1022556f --- /dev/null +++ b/reference/bc/bcmath/number/sqrt.xml @@ -0,0 +1,135 @@ + + + + + + BcMath\Number::sqrt + 获取任意精度数字的平方根 + + + + &reftitle.description; + + public BcMath\NumberBcMath\Number::sqrt + intnullscale&null; + + + 返回 $this 的平方根。 + + + + + &reftitle.parameters; + + + + + + + &reftitle.returnvalues; + + 返回平方根，为新的 BcMath\Number 对象。 + + + 当结果对象的 BcMath\Number::scale 被自动设置时， + 会使用 $this 的 BcMath\Number::scale。但是，在不可整除的除法等情况下， + 结果的 BcMath\Number::scale 会被扩展。 + 扩展仅在需要时进行，最大扩展到 +10。 + 此行为与 BcMath\Number::div 相同，因此请参阅该方法了解详细信息。 + + + 也就是说，如果 $this 的 BcMath\Number::scale 为 5， + 则结果的 BcMath\Number::scale 在 5 到 15 之间。 + + + + + &reftitle.errors; + + 此方法在以下情况下会抛出 ValueError 异常： + + $this 是负值 + scale 超出有效范围 + 结果对象的 BcMath\Number::scale 超出有效范围 + + + + + + &reftitle.examples; + + <methodname>BcMath\Number::sqrt</methodname> 示例 + +sqrt(), + new BcMath\Number('2')->sqrt(3), + new BcMath\Number('4')->sqrt(), + new BcMath\Number('4')->sqrt(3), +); +?> +]]> + + &example.outputs; + + + string(12) "1.4142135623" + ["scale"]=> + int(10) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(5) "1.414" + ["scale"]=> + int(3) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(1) "2" + ["scale"]=> + int(0) +} +object(BcMath\Number)#5 (2) { + ["value"]=> + string(5) "2.000" + ["scale"]=> + int(3) +} +]]> + + + + + + &reftitle.seealso; + + bcsqrt + BcMath\Number::div + BcMath\Number::pow + + + + + diff --git a/reference/bc/bcmath/number/sub.xml b/reference/bc/bcmath/number/sub.xml new file mode 100644 index 000000000..bd50333f2 --- /dev/null +++ b/reference/bc/bcmath/number/sub.xml @@ -0,0 +1,176 @@ + + + + + + BcMath\Number::sub + 减去任意精度数字 + + + + &reftitle.description; + + public BcMath\NumberBcMath\Number::sub + BcMath\Numberstringintnum + intnullscale&null; + + + 从 $this 中减去 num。 + + + + + &reftitle.parameters; + + + num + + + 要减去的值。 + + + + + + + + + &reftitle.returnvalues; + + 返回减法结果，为新的 BcMath\Number 对象。 + + + 当结果对象的 BcMath\Number::scale 被自动设置时， + 使用减法运算中两个数字的较大 BcMath\Number::scale。 + + + + + + + + + + &reftitle.examples; + + 未指定 <parameter>scale</parameter> 时的 <methodname>BcMath\Number::sub</methodname> 示例 + +sub(new BcMath\Number('2.34567')); +$ret2 = $number->sub('-3.456'); +$ret3 = $number->sub(7); + +var_dump($number, $ret1, $ret2, $ret3); +?> +]]> + + &example.outputs; + + + string(5) "1.234" + ["scale"]=> + int(3) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(8) "-1.11167" + ["scale"]=> + int(5) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(5) "4.690" + ["scale"]=> + int(3) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(6) "-5.766" + ["scale"]=> + int(3) +} +]]> + + + + + 显式指定 <parameter>scale</parameter> 的 <methodname>BcMath\Number::sub</methodname> 示例 + +sub(new BcMath\Number('2.34567'), 1); +$ret2 = $number->sub('-3.456', 10); +$ret3 = $number->sub(7, 0); + +var_dump($number, $ret1, $ret2, $ret3); +?> +]]> + + &example.outputs; + + + string(5) "1.234" + ["scale"]=> + int(3) +} +object(BcMath\Number)#3 (2) { + ["value"]=> + string(4) "-1.1" + ["scale"]=> + int(1) +} +object(BcMath\Number)#2 (2) { + ["value"]=> + string(12) "4.6900000000" + ["scale"]=> + int(10) +} +object(BcMath\Number)#4 (2) { + ["value"]=> + string(2) "-5" + ["scale"]=> + int(0) +} +]]> + + + + + + &reftitle.seealso; + + bcsub + BcMath\Number::add + + + + + diff --git a/reference/bc/bcmath/number/tostring.xml b/reference/bc/bcmath/number/tostring.xml new file mode 100644 index 000000000..55ed9ba26 --- /dev/null +++ b/reference/bc/bcmath/number/tostring.xml @@ -0,0 +1,52 @@ + + + + + + BcMath\Number::__toString + 将 BcMath\Number 转换为字符串 + + + + &reftitle.description; + + public stringBcMath\Number::__toString + + + + 将 BcMath\Number 转换为 string。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + 返回 BcMath\Number::value 作为 string。 + + + + diff --git a/reference/bc/bcmath/number/unserialize.xml b/reference/bc/bcmath/number/unserialize.xml new file mode 100644 index 000000000..f9eaacd84 --- /dev/null +++ b/reference/bc/bcmath/number/unserialize.xml @@ -0,0 +1,70 @@ + + + + + + BcMath\Number::__unserialize + 将数据参数反序列化为 BcMath\Number 对象 + + + + &reftitle.description; + + public voidBcMath\Number::__unserialize + arraydata + + + 将数据参数反序列化为 BcMath\Number 对象。 + + + + + &reftitle.parameters; + + + data + + + 作为关联 array 的序列化数据参数 + + + + + + + + &reftitle.errors; + + 如果传入无效的序列化数据，此方法会抛出 ValueError 异常。 + + + + + &reftitle.seealso; + + BcMath\Number::__construct + BcMath\Number::serialize + + + + + diff --git a/reference/bc/functions/bcceil.xml b/reference/bc/functions/bcceil.xml new file mode 100644 index 000000000..c573acbc5 --- /dev/null +++ b/reference/bc/functions/bcceil.xml @@ -0,0 +1,101 @@ + + + + + + bcceil + 向上舍入任意精度数字 + + + + &reftitle.description; + + stringbcceil + stringnum + + + 通过向上舍入返回下一个最高整数值（如有必要）。 + + + + + &reftitle.parameters; + + + num + + + 要舍入的值。 + + + + + + + + &reftitle.returnvalues; + + 返回一个数值字符串，表示 num 向上舍入到最接近的整数。 + + + + + &reftitle.errors; + + 如果 num 不是格式良好的 BCMath 数值字符串，此函数会抛出 ValueError 异常。 + + + + + &reftitle.examples; + + <function>bcceil</function> 示例 + + +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + bcfloor + bcround + BcMath\Number::ceil + + + + diff --git a/reference/bc/functions/bcdivmod.xml b/reference/bc/functions/bcdivmod.xml new file mode 100644 index 000000000..e099a69dc --- /dev/null +++ b/reference/bc/functions/bcdivmod.xml @@ -0,0 +1,107 @@ + + + + + + bcdivmod + 获取任意精度数字的商和模数 + + + + &reftitle.description; + + arraybcdivmod + stringnum1 + stringnum2 + intnullscale&null; + + + 获取 num1 除以 num2 的商和余数。 + + + + + + + + + &reftitle.returnvalues; + + 返回一个索引 array，其中第一个元素是作为 string 的商， + 第二个元素是作为 string 的余数。 + + + + + + + &reftitle.examples; + + <function>bcdivmod</function> 示例 + + +]]> + + + + <function>bcdivmod</function> 处理小数 + + +]]> + + + + + + &reftitle.seealso; + + bcdiv + bcmod + BcMath\Number::divmod + + + + diff --git a/reference/bc/functions/bcfloor.xml b/reference/bc/functions/bcfloor.xml new file mode 100644 index 000000000..ed3818318 --- /dev/null +++ b/reference/bc/functions/bcfloor.xml @@ -0,0 +1,86 @@ + + + + + + bcfloor + 向下舍入任意精度数字 + + + + &reftitle.description; + + stringbcfloor + stringnum + + + 通过向下舍入返回下一个最低整数值（如有必要）。 + + + + + + + + + &reftitle.returnvalues; + + 返回一个数值字符串，表示 num 向下舍入到最接近的整数。 + + + + + + + &reftitle.examples; + + <function>bcfloor</function> 示例 + + +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + bcceil + bcround + BcMath\Number::floor + + + + diff --git a/reference/bc/functions/bcpowmod.xml b/reference/bc/functions/bcpowmod.xml new file mode 100644 index 000000000..bbf683f26 --- /dev/null +++ b/reference/bc/functions/bcpowmod.xml @@ -0,0 +1,176 @@ + + + + + + bcpowmod + 将任意精度数字提升到另一个数的幂，并对指定模数取余 + + + + &reftitle.description; + + stringbcpowmod + stringnum + stringexponent + stringmodulus + intnullscale&null; + + + 使用快速幂算法将 num 提升到 exponent 次幂， + 并对模数 modulus 取余。 + + + + + &reftitle.parameters; + + + + num + + + 底数，作为整数字符串（即小数位数必须为零）。 + + + + + exponent + + + 指数，作为非负整数字符串（即小数位数必须为零）。 + + + + + modulus + + + 模数，作为整数字符串（即小数位数必须为零）。 + + + + + + + + + + &reftitle.returnvalues; + + 以字符串形式返回结果。 + + + + + &reftitle.errors; + + 此函数在以下情况下会抛出 ValueError 异常： + + num、exponent 或 modulus 不是格式良好的 BCMath 数值字符串 + num、exponent 或 modulus 有小数部分 + exponent 是负值 + scale 超出有效范围 + + + + 如果 modulus 为 0，此函数会抛出 DivisionByZeroError 异常。 + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.0.0 + + scale 现在可以为 null。 + + + + 8.0.0 + + 现在如果 exponent 是负值，会抛出 ValueError 异常，而不是返回 &false;。 + + + + 8.0.0 + + 除以 0 现在会抛出 DivisionByZeroError 异常，而不是返回 &false;。 + + + + + + + + + &reftitle.examples; + + 以下两个语句在功能上是相同的。但是，bcpowmod 版本执行时间更短， + 并且可以接受更大的参数。 + + + +]]> + + + + + + + &reftitle.notes; + + + 由于此方法使用取模运算，非正整数可能会产生意外结果。 + + + + + + &reftitle.seealso; + + + bcpow + bcmod + BcMath\Number::powmod + + + + + diff --git a/reference/bc/functions/bcround.xml b/reference/bc/functions/bcround.xml new file mode 100644 index 000000000..83e80bf3c --- /dev/null +++ b/reference/bc/functions/bcround.xml @@ -0,0 +1,290 @@ + + + + + + bcround + 四舍五入任意精度数字 + + + + &reftitle.description; + + stringbcround + stringnum + intprecision0 + RoundingModemodeRoundingMode::HalfAwayFromZero + + + 返回 num 四舍五入到指定 precision + （小数点后的位数）的值。 + precision 也可以是负数或零（默认值）。 + + + + + &reftitle.parameters; + + + + + + + + + &reftitle.returnvalues; + + 返回一个数值字符串，表示 num 四舍五入到指定精度的结果。 + + + + + &reftitle.errors; + + 此函数在以下情况下会抛出 ValueError 异常： + + num 不是格式良好的 BCMath 数值字符串。 + 指定了无效的 mode。 + + + + + + &reftitle.examples; + + <function>bcround</function> 示例 + + +]]> + + &example.outputs; + + + + + + + 使用不同 <parameter>precision</parameter> 值的 <function>bcround</function> 示例 + + + +]]> + + &example.outputs; + + + + + + + 使用不同 <parameter>mode</parameter> 值的 <function>bcround</function> 示例 + + + +]]> + + &example.outputs; + + + + + + + 指定 <parameter>precision</parameter> 时使用不同 <parameter>mode</parameter> 值的 <function>bcround</function> 示例 + + + +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + bcceil + bcfloor + BcMath\Number::round + + + +