Skip to content

Commit c7e83fb

Browse files
SakiTakamachiGirgias
SakiTakamachi
and
Girgias
authored
ext/bcmath: Document BcMath\Number class (#4187)
Co-authored-by: Gina Peter Banyard <[email protected]>
1 parent 30c0106 commit c7e83fb

34 files changed

+3082
-0
lines changed

‎reference/bc/bcmath.number.xml

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
<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">
4+
5+
<title>The BcMath\Number class</title>
6+
<titleabbrev>BcMath\Number</titleabbrev>
7+
8+
<partintro>
9+
<section xml:id="bcmath-number.intro">
10+
&reftitle.intro;
11+
<simpara>
12+
A class for an arbitrary precision number.
13+
These objects support overloaded
14+
<link linkend="language.operators.arithmetic">arithmetic</link> and
15+
<link linkend="language.operators.comparison">comparison</link> operators.
16+
</simpara>
17+
18+
<note>
19+
<simpara>
20+
This class is not affected by the
21+
<link linkend="ini.bcmath.scale">bcmath.scale</link>
22+
INI directive set in &php.ini;.
23+
</simpara>
24+
</note>
25+
26+
<note>
27+
<simpara>
28+
The behavior of an overloaded operator is the same as specifying &null; for the
29+
<parameter>scale</parameter> parameter on the corresponding method.
30+
</simpara>
31+
</note>
32+
</section>
33+
34+
<section xml:id="bcmath-number.synopsis">
35+
&reftitle.classsynopsis;
36+
37+
<classsynopsis class="class">
38+
<ooclass>
39+
<modifier>final</modifier>
40+
<modifier>readonly</modifier>
41+
<classname>BcMath\Number</classname>
42+
</ooclass>
43+
44+
<oointerface>
45+
<modifier>implements</modifier>
46+
<interfacename>Stringable</interfacename>
47+
</oointerface>
48+
49+
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
50+
<fieldsynopsis>
51+
<modifier>public</modifier>
52+
<type>string</type>
53+
<varname linkend="bcmath-number.props.value">value</varname>
54+
</fieldsynopsis>
55+
<fieldsynopsis>
56+
<modifier>public</modifier>
57+
<type>int</type>
58+
<varname linkend="bcmath-number.props.scale">scale</varname>
59+
</fieldsynopsis>
60+
61+
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
62+
<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'])">
63+
<xi:fallback/>
64+
</xi:include>
65+
<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'])">
66+
<xi:fallback/>
67+
</xi:include>
68+
</classsynopsis>
69+
</section>
70+
71+
<section xml:id="bcmath-number.props">
72+
&reftitle.properties;
73+
<variablelist>
74+
<varlistentry xml:id="bcmath-number.props.value">
75+
<term><varname>value</varname></term>
76+
<listitem>
77+
<simpara>
78+
A string representation of an arbitrary precision number.
79+
</simpara>
80+
</listitem>
81+
</varlistentry>
82+
<varlistentry xml:id="bcmath-number.props.scale">
83+
<term><varname>scale</varname></term>
84+
<listitem>
85+
<simpara>
86+
The scale value currently set on the object.
87+
For objects resulting from calculations, this value is automatically computed and set,
88+
unless the <parameter>scale</parameter> parameter was set in the calculation method.
89+
</simpara>
90+
</listitem>
91+
</varlistentry>
92+
</variablelist>
93+
</section>
94+
95+
</partintro>
96+
97+
&reference.bc.bcmath.entities.number;
98+
99+
</reference>
100+
<!-- Keep this comment at the end of the file
101+
Local variables:
102+
mode: sgml
103+
sgml-omittag:t
104+
sgml-shorttag:t
105+
sgml-minimize-attributes:nil
106+
sgml-always-quote-attributes:t
107+
sgml-indent-step:1
108+
sgml-indent-data:t
109+
indent-tabs-mode:nil
110+
sgml-parent-document:nil
111+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
112+
sgml-exposed-tags:nil
113+
sgml-local-catalogs:nil
114+
sgml-local-ecat-files:nil
115+
End:
116+
vim600: syn=xml fen fdm=syntax fdl=2 si
117+
vim: et tw=78 syn=sgml
118+
vi: ts=1 sw=1
119+
-->

‎reference/bc/bcmath/number/add.xml

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<refentry xml:id="bcmath-number.add" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
3+
<refnamediv>
4+
<refname>BcMath\Number::add</refname>
5+
<refpurpose>Adds an arbitrary precision number</refpurpose>
6+
</refnamediv>
7+
8+
<refsect1 role="description">
9+
&reftitle.description;
10+
<methodsynopsis role="BcMath\\Number">
11+
<modifier>public</modifier> <type>BcMath\Number</type><methodname>BcMath\Number::add</methodname>
12+
<methodparam><type class="union"><type>BcMath\Number</type><type>string</type><type>int</type></type><parameter>num</parameter></methodparam>
13+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>scale</parameter><initializer>&null;</initializer></methodparam>
14+
</methodsynopsis>
15+
<simpara>
16+
Adds <varname>$this</varname> and <parameter>num</parameter>.
17+
</simpara>
18+
</refsect1>
19+
20+
<refsect1 role="parameters">
21+
&reftitle.parameters;
22+
<variablelist>
23+
<varlistentry>
24+
<term><parameter>num</parameter></term>
25+
<listitem>
26+
<simpara>
27+
The value to add.
28+
</simpara>
29+
</listitem>
30+
</varlistentry>
31+
<varlistentry>
32+
<term><parameter>scale</parameter></term>
33+
<listitem>
34+
<simpara>
35+
<parameter>scale</parameter> explicitly specified for calculation results.
36+
If &null;, the <parameter>scale</parameter> of the calculation result will be set automatically.
37+
</simpara>
38+
</listitem>
39+
</varlistentry>
40+
</variablelist>
41+
</refsect1>
42+
43+
<refsect1 role="returnvalues">
44+
&reftitle.returnvalues;
45+
<simpara>
46+
Returns the result of addition as a new <classname>BcMath\Number</classname> object.
47+
</simpara>
48+
<simpara>
49+
When the <property>BcMath\Number::scale</property> of the result object is automatically set,
50+
the greater <property>BcMath\Number::scale</property> of the two numbers used for addition is used.
51+
</simpara>
52+
<simpara>
53+
That is, if the <property>BcMath\Number::scale</property>s of two values are <literal>2</literal>
54+
and <literal>5</literal> respectively, the <property>BcMath\Number::scale</property> of the result
55+
will be <literal>5</literal>.
56+
</simpara>
57+
</refsect1>
58+
59+
<refsect1 role="errors">
60+
&reftitle.errors;
61+
<para>
62+
This method throws a <exceptionname>ValueError</exceptionname> in the following cases:
63+
<simplelist>
64+
<member><parameter>num</parameter> is <type>string</type> and not a well-formed BCMath numeric string</member>
65+
<member><parameter>scale</parameter> is outside the valid range</member>
66+
</simplelist>
67+
</para>
68+
</refsect1>
69+
70+
<refsect1 role="examples">
71+
&reftitle.examples;
72+
<example>
73+
<title><methodname>BcMath\Number::add</methodname> example when <parameter>scale</parameter> is not specified</title>
74+
<programlisting role="php">
75+
<![CDATA[
76+
<?php
77+
$number = new BcMath\Number('1.234');
78+
79+
$ret1 = $number->add(new BcMath\Number('2.34567'));
80+
$ret2 = $number->add('-3.456');
81+
$ret3 = $number->add(7);
82+
83+
var_dump($number, $ret1, $ret2, $ret3);
84+
?>
85+
]]>
86+
</programlisting>
87+
&example.outputs;
88+
<screen>
89+
<![CDATA[
90+
object(BcMath\Number)#1 (2) {
91+
["value"]=>
92+
string(5) "1.234"
93+
["scale"]=>
94+
int(3)
95+
}
96+
object(BcMath\Number)#3 (2) {
97+
["value"]=>
98+
string(7) "3.57967"
99+
["scale"]=>
100+
int(5)
101+
}
102+
object(BcMath\Number)#2 (2) {
103+
["value"]=>
104+
string(6) "-2.222"
105+
["scale"]=>
106+
int(3)
107+
}
108+
object(BcMath\Number)#4 (2) {
109+
["value"]=>
110+
string(5) "8.234"
111+
["scale"]=>
112+
int(3)
113+
}
114+
]]>
115+
</screen>
116+
</example>
117+
118+
<example>
119+
<title><methodname>BcMath\Number::add</methodname> example of explicitly specifying <parameter>scale</parameter></title>
120+
<programlisting role="php">
121+
<![CDATA[
122+
<?php
123+
$number = new BcMath\Number('1.234');
124+
125+
$ret1 = $number->add(new BcMath\Number('2.34567'), 1);
126+
$ret2 = $number->add('-3.456', 10);
127+
$ret3 = $number->add(7, 0);
128+
129+
var_dump($number, $ret1, $ret2, $ret3);
130+
?>
131+
]]>
132+
</programlisting>
133+
&example.outputs;
134+
<screen>
135+
<![CDATA[
136+
object(BcMath\Number)#1 (2) {
137+
["value"]=>
138+
string(5) "1.234"
139+
["scale"]=>
140+
int(3)
141+
}
142+
object(BcMath\Number)#3 (2) {
143+
["value"]=>
144+
string(3) "3.5"
145+
["scale"]=>
146+
int(1)
147+
}
148+
object(BcMath\Number)#2 (2) {
149+
["value"]=>
150+
string(13) "-2.2220000000"
151+
["scale"]=>
152+
int(10)
153+
}
154+
object(BcMath\Number)#4 (2) {
155+
["value"]=>
156+
string(1) "8"
157+
["scale"]=>
158+
int(0)
159+
}
160+
]]>
161+
</screen>
162+
</example>
163+
</refsect1>
164+
165+
<refsect1 role="seealso">
166+
&reftitle.seealso;
167+
<simplelist>
168+
<member><function>bcadd</function></member>
169+
<member><methodname>BcMath\Number::sub</methodname></member>
170+
</simplelist>
171+
</refsect1>
172+
173+
</refentry>
174+
<!-- Keep this comment at the end of the file
175+
Local variables:
176+
mode: sgml
177+
sgml-omittag:t
178+
sgml-shorttag:t
179+
sgml-minimize-attributes:nil
180+
sgml-always-quote-attributes:t
181+
sgml-indent-step:1
182+
sgml-indent-data:t
183+
indent-tabs-mode:nil
184+
sgml-parent-document:nil
185+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
186+
sgml-exposed-tags:nil
187+
sgml-local-catalogs:nil
188+
sgml-local-ecat-files:nil
189+
End:
190+
vim600: syn=xml fen fdm=syntax fdl=2 si
191+
vim: et tw=78 syn=sgml
192+
vi: ts=1 sw=1
193+
-->

0 commit comments

Comments
 (0)