Skip to content

Commit

Permalink
ext/bcmath: Document BcMath\Number class (#4187)
Browse files Browse the repository at this point in the history 
Co-authored-by: Gina Peter Banyard <[email protected]>
  • Loading branch information
@SakiTakamachi @Girgias
SakiTakamachi and Girgias authored Jan 14, 2025
1 parent 30c0106 commit c7e83fb
Show file tree
Hide file tree
Showing 34 changed files with 3,082 additions and 0 deletions.
119 changes: 119 additions & 0 deletions reference/bc/bcmath.number.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<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>The BcMath\Number class</title>
<titleabbrev>BcMath\Number</titleabbrev>

<partintro>
<section xml:id="bcmath-number.intro">
&reftitle.intro;
<simpara>
A class for an arbitrary precision number.
These objects support overloaded
<link linkend="language.operators.arithmetic">arithmetic</link> and
<link linkend="language.operators.comparison">comparison</link> operators.
</simpara>

<note>
<simpara>
This class is not affected by the
<link linkend="ini.bcmath.scale">bcmath.scale</link>
INI directive set in &php.ini;.
</simpara>
</note>

<note>
<simpara>
The behavior of an overloaded operator is the same as specifying &null; for the
<parameter>scale</parameter> parameter on the corresponding method.
</simpara>
</note>
</section>

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

<classsynopsis class="class">
<ooclass>
<modifier>final</modifier>
<modifier>readonly</modifier>
<classname>BcMath\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>
</section>

<section xml:id="bcmath-number.props">
&reftitle.properties;
<variablelist>
<varlistentry xml:id="bcmath-number.props.value">
<term><varname>value</varname></term>
<listitem>
<simpara>
A string representation of an arbitrary precision number.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="bcmath-number.props.scale">
<term><varname>scale</varname></term>
<listitem>
<simpara>
The scale value currently set on the object.
For objects resulting from calculations, this value is automatically computed and set,
unless the <parameter>scale</parameter> parameter was set in the calculation method.
</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=1
-->
193 changes: 193 additions & 0 deletions reference/bc/bcmath/number/add.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,193 @@
<?xml version="1.0" encoding="utf-8"?>
<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>Adds an arbitrary precision number</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>
Adds <varname>$this</varname> and <parameter>num</parameter>.
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>num</parameter></term>
<listitem>
<simpara>
The value to add.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>scale</parameter></term>
<listitem>
<simpara>
<parameter>scale</parameter> explicitly specified for calculation results.
If &null;, the <parameter>scale</parameter> of the calculation result will be set automatically.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
Returns the result of addition as a new <classname>BcMath\Number</classname> object.
</simpara>
<simpara>
When the <property>BcMath\Number::scale</property> of the result object is automatically set,
the greater <property>BcMath\Number::scale</property> of the two numbers used for addition is used.
</simpara>
<simpara>
That is, if the <property>BcMath\Number::scale</property>s of two values are <literal>2</literal>
and <literal>5</literal> respectively, the <property>BcMath\Number::scale</property> of the result
will be <literal>5</literal>.
</simpara>
</refsect1>

<refsect1 role="errors">
&reftitle.errors;
<para>
This method throws a <exceptionname>ValueError</exceptionname> in the following cases:
<simplelist>
<member><parameter>num</parameter> is <type>string</type> and not a well-formed BCMath numeric string</member>
<member><parameter>scale</parameter> is outside the valid range</member>
</simplelist>
</para>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>BcMath\Number::add</methodname> example when <parameter>scale</parameter> is not specified</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> example of explicitly specifying <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=1
-->
Loading

0 comments on commit c7e83fb

Please sign in to comment.