Skip to content

翻译 reference/bc #1041

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
singi2016cn wants to merge 3 commits into
base: master
Choose a base branch
from
Open

翻译 reference/bc #1041

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cd66fc9
feat: 翻译 appendices\examples.xml
Apr 30, 2026
fbe012a
Merge branch 'php:master' into master
singi2016cn Apr 30, 2026
996c382
feat: 翻译 reference/bc
Apr 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions appendices/examples.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: Singi Status: ready -->
<appendix xml:id="examples" xmlns="http://docbook.org/ns/docbook">
<title>关于手册示例</title>
<simpara>
需要注意的是，为了清晰简洁，PHP 文档中的许多示例都省略了错误和异常处理。
</simpara>
<simpara>
这并不意味着生产环境代码可以省略错误处理，因为此举可能会引发 <exceptionname>TypeError</exceptionname> 错误、强制转换失败值（例如将布尔值 &false; 转为空字符串），或是违背代码预设逻辑，进而产生难以排查的隐蔽漏洞。部分扩展库提供了完整示例，其中均包含错误处理逻辑，用以演示该扩展所提供各类函数与方法的规范用法。
</simpara>
</appendix>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
124 changes: 124 additions & 0 deletions reference/bc/bcmath.number.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: Singi Status: ready -->
<reference xml:id="class.bcmath-number" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">

<title>BcMath\Number 类</title>
<titleabbrev>BcMath\Number</titleabbrev>

<partintro>
<section xml:id="bcmath-number.intro">
&reftitle.intro;
<simpara>
用于任意精度数字的类。
这些对象支持重载的
<link linkend="language.operators.arithmetic">算术</link> 和
<link linkend="language.operators.comparison">比较</link> 运算符。
</simpara>

<note>
<simpara>
此类不受
<link linkend="ini.bcmath.scale">bcmath.scale</link>
在 &php.ini; 中设置的 INI 指令影响。
</simpara>
</note>

<note>
<simpara>
重载运算符的行为与在相应方法上为
<parameter>scale</parameter> 参数指定 &null; 相同。
</simpara>
</note>
</section>

<section xml:id="bcmath-number.synopsis">
&reftitle.classsynopsis;

<packagesynopsis>
<package>BcMath</package>

<classsynopsis class="class">
<ooclass>
<modifier>final</modifier>
<modifier>readonly</modifier>
<classname>Number</classname>
</ooclass>

<oointerface>
<modifier>implements</modifier>
<interfacename>Stringable</interfacename>
</oointerface>

<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
<fieldsynopsis>
<modifier>public</modifier>
<type>string</type>
<varname linkend="bcmath-number.props.value">value</varname>
</fieldsynopsis>
<fieldsynopsis>
<modifier>public</modifier>
<type>int</type>
<varname linkend="bcmath-number.props.scale">scale</varname>
</fieldsynopsis>

<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.bcmath-number')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='BcMath\\Number'])">
<xi:fallback/>
</xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.bcmath-number')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='BcMath\\Number'])">
<xi:fallback/>
</xi:include>
</classsynopsis>
</packagesynopsis>
</section>

<section xml:id="bcmath-number.props">
&reftitle.properties;
<variablelist>
<varlistentry xml:id="bcmath-number.props.value">
<term><varname>value</varname></term>
<listitem>
<simpara>
任意精度数字的字符串表示。
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="bcmath-number.props.scale">
<term><varname>scale</varname></term>
<listitem>
<simpara>
当前在对象上设置的精度值。
对于计算结果的对象，此值会自动计算和设置，
除非在计算方法中设置了 <parameter>scale</parameter> 参数。
</simpara>
</listitem>
</varlistentry>
</variablelist>
</section>

</partintro>

&reference.bc.bcmath.entities.number;

</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=
-->
195 changes: 195 additions & 0 deletions reference/bc/bcmath/number/add.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,195 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 9f4cb232d01a06077a2324e38f767d63f87f2e5f Maintainer: Singi Status: ready -->
<refentry xml:id="bcmath-number.add" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>BcMath\Number::add</refname>
<refpurpose>加法运算（任意精度数字）</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis role="BcMath\\Number">
<modifier>public</modifier> <type>BcMath\Number</type><methodname>BcMath\Number::add</methodname>
<methodparam><type class="union"><type>BcMath\Number</type><type>string</type><type>int</type></type><parameter>num</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>scale</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<simpara>
将 <varname>$this</varname> 和 <parameter>num</parameter> 相加。
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>num</parameter></term>
<listitem>
<simpara>
要相加的值。
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>scale</parameter></term>
<listitem>
<simpara>
为计算结果显式指定的 <property>BcMath\Number::scale</property>。
如果为 &null;，计算结果的 <property>BcMath\Number::scale</property> 将自动设置。
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
返回加法运算的结果，为新的 <classname>BcMath\Number</classname> 对象。
</simpara>
<simpara>
当结果对象的 <property>BcMath\Number::scale</property> 自动设置时，
将使用加法运算中两个数字的较大 <property>BcMath\Number::scale</property> 值。
</simpara>
<simpara>
例如，如果两个值的 <property>BcMath\Number::scale</property> 分别为 <literal>2</literal>
和 <literal>5</literal>，则结果的 <property>BcMath\Number::scale</property>
将为 <literal>5</literal>。
</simpara>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<para>
以下情况会抛出 <exceptionname>ValueError</exceptionname> 异常：
<simplelist>
<member><parameter>num</parameter> 是 <type>string</type> 类型但不是格式正确的 BCMath 数字字符串</member>
<member><parameter>scale</parameter> 超出有效范围</member>
</simplelist>
</para>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>BcMath\Number::add</methodname> 示例：未指定 <parameter>scale</parameter></title>
<programlisting role="php">
<![CDATA[
<?php
$number = new BcMath\Number('1.234');

$ret1 = $number->add(new BcMath\Number('2.34567'));
$ret2 = $number->add('-3.456');
$ret3 = $number->add(7);

var_dump($number, $ret1, $ret2, $ret3);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
object(BcMath\Number)#1 (2) {
["value"]=>
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)
}
]]>
</screen>
</example>

<example>
<title><methodname>BcMath\Number::add</methodname> 示例：显式指定 <parameter>scale</parameter></title>
<programlisting role="php">
<![CDATA[
<?php
$number = new BcMath\Number('1.234');

$ret1 = $number->add(new BcMath\Number('2.34567'), 1);
$ret2 = $number->add('-3.456', 10);
$ret3 = $number->add(7, 0);

var_dump($number, $ret1, $ret2, $ret3);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
object(BcMath\Number)#1 (2) {
["value"]=>
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)
}
]]>
</screen>
</example>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>bcadd</function></member>
<member><methodname>BcMath\Number::sub</methodname></member>
</simplelist>
</refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=
-->
Loading