Skip to content

Commit 95ef75d

Browse files
SakiTakamachiSakiTakamachi
committed
Created pow()
1 parent 5d9e5f4 commit 95ef75d

File tree

2 files changed

+348
-0
lines changed

2 files changed

+348
-0
lines changed

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

Lines changed: 347 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,347 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<refentry xml:id="bcmath-number.pow" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
3+
<refnamediv>
4+
<refname>BcMath\Number::pow</refname>
5+
<refpurpose>Raises 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::pow</methodname>
12+
<methodparam><type class="union"><type>BcMath\Number</type><type>string</type><type>int</type></type><parameter>exponent</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+
Raises this object to the <parameter>exponent</parameter> power.
17+
</simpara>
18+
</refsect1>
19+
20+
<refsect1 role="parameters">
21+
&reftitle.parameters;
22+
<variablelist>
23+
<varlistentry>
24+
<term><parameter>exponent</parameter></term>
25+
<listitem>
26+
<simpara>
27+
The exponent. Must be a value with no fractional part.
28+
The valid range of the exponent is platform specific, but is at least
29+
<literal>-2147483648</literal> to <literal>2147483647</literal>.
30+
</simpara>
31+
</listitem>
32+
</varlistentry>
33+
&bc.number.scale.description;
34+
</variablelist>
35+
</refsect1>
36+
37+
<refsect1 role="returnvalues">
38+
&reftitle.returnvalues;
39+
<simpara>
40+
Returns the result of power as a new <classname>BcMath\Number</classname> object.
41+
</simpara>
42+
<!-- About the operator return value -->
43+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('bcmath-number.add')/db:refsect1[@role='returnvalues']/db:simpara[2])" />
44+
</refsect1>
45+
46+
<refsect1 role="errors">
47+
&reftitle.errors;
48+
<para>
49+
This method throws a <exceptionname>ValueError</exceptionname> in the following cases:
50+
<simplelist>
51+
<member><parameter>exponent</parameter> is <type>string</type> and not a well-formed BCMath numeric string</member>
52+
<member><parameter>exponent</parameter> has a fractional part</member>
53+
<member><parameter>scale</parameter> is outside the valid range</member>
54+
<member><property>BcMath\Number::scale</property> of the result object is outside the valid range</member>
55+
</simplelist>
56+
</para>
57+
<simpara>
58+
This method throws a <exceptionname>DivisionByZeroError</exceptionname> exception if this object's value
59+
is <literal>0</literal> and <parameter>exponent</parameter> is a negative value.
60+
</simpara>
61+
<para>
62+
When using the operator, throws a <exceptionname>ValueError</exceptionname> in the following cases:
63+
<simplelist>
64+
<member><parameter>exponent</parameter> is <type>string</type> and not a well-formed BCMath numeric string</member>
65+
<member><parameter>exponent</parameter> has a fractional part</member>
66+
<member><property>BcMath\Number::scale</property> of the result object is outside the valid range</member>
67+
</simplelist>
68+
</para>
69+
<simpara>
70+
When using the operator, throw a <exceptionname>DivisionByZeroError</exceptionname> exception If the left
71+
operand is <literal>0</literal> and the right operand is a negative value.
72+
</simpara>
73+
</refsect1>
74+
75+
<refsect1 role="bc.autoscale">
76+
<!-- auto scale title -->
77+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('bcmath-number.add')/db:refsect1[@role='bc.autoscale']/db:title)" />
78+
<para>
79+
When the <property>BcMath\Number::scale</property> of the result object is automatically set,
80+
depending on the value of <parameter>exponent</parameter>, the <property>BcMath\Number::scale
81+
</property> of result will be as follows:
82+
<informaltable>
83+
<tgroup cols="2">
84+
<thead>
85+
<row>
86+
<entry><parameter>exponent</parameter></entry>
87+
<entry><property>BcMath\Number::scale</property> of result</entry>
88+
</row>
89+
</thead>
90+
<tbody>
91+
<row>
92+
<entry>positive</entry>
93+
<entry>(<property>BcMath\Number::scale</property> of power base) * (<parameter>exponent</parameter>'s value)</entry>
94+
</row>
95+
<row>
96+
<entry><literal>0</literal></entry>
97+
<entry><literal>0</literal></entry>
98+
</row>
99+
<row>
100+
<entry>negative</entry>
101+
<entry>Between (<property>BcMath\Number::scale</property> of power base) and (<property>BcMath\Number::scale
102+
</property> of power base + <literal>10</literal>)</entry>
103+
</row>
104+
</tbody>
105+
</tgroup>
106+
</informaltable>
107+
</para>
108+
<simpara>
109+
If an indivisible division occurs due to a negative <parameter>exponent</parameter>, the <property>
110+
BcMath\Number::scale</property> of the result is expanded. Expansion is done only as needed, up to
111+
a maximum of +<literal>10</literal>.
112+
This behavior is the same as <methodname>BcMath\Number::div</methodname>, so please see that for details.
113+
</simpara>
114+
<!-- Regarding the handling of scale when calculating with string value -->
115+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('bcmath-number.add')/db:refsect1[@role='bc.autoscale']/db:simpara[3])" />
116+
</refsect1>
117+
118+
<refsect1 role="examples">
119+
&reftitle.examples;
120+
<example>
121+
<title><methodname>BcMath\Number::pow</methodname> example when <parameter>scale</parameter> is not specified</title>
122+
<programlisting role="php">
123+
<![CDATA[
124+
<?php
125+
$number = new BcMath\Number('3.0');
126+
127+
$ret1 = $number->pow(new BcMath\Number('5'));
128+
$ret2 = $number->pow('-1');
129+
$ret3 = $number->pow(0);
130+
131+
var_dump($number, $ret1, $ret2, $ret3);
132+
?>
133+
]]>
134+
</programlisting>
135+
&example.outputs;
136+
<screen>
137+
<![CDATA[
138+
object(BcMath\Number)#1 (2) {
139+
["value"]=>
140+
string(3) "3.0"
141+
["scale"]=>
142+
int(1)
143+
}
144+
object(BcMath\Number)#3 (2) {
145+
["value"]=>
146+
string(9) "243.00000"
147+
["scale"]=>
148+
int(5)
149+
}
150+
object(BcMath\Number)#2 (2) {
151+
["value"]=>
152+
string(13) "0.33333333333"
153+
["scale"]=>
154+
int(11)
155+
}
156+
object(BcMath\Number)#4 (2) {
157+
["value"]=>
158+
string(1) "1"
159+
["scale"]=>
160+
int(0)
161+
}
162+
]]>
163+
</screen>
164+
</example>
165+
166+
<example>
167+
<title><methodname>BcMath\Number::pow</methodname> example of explicitly specifying <parameter>scale</parameter></title>
168+
<programlisting role="php">
169+
<![CDATA[
170+
<?php
171+
$number = new BcMath\Number('3.0');
172+
173+
$ret1 = $number->pow(new BcMath\Number('5'), 0);
174+
$ret2 = $number->pow('-1', 2);
175+
$ret3 = $number->pow(0, 10);
176+
177+
var_dump($number, $ret1, $ret2, $ret3);
178+
?>
179+
]]>
180+
</programlisting>
181+
&example.outputs;
182+
<screen>
183+
<![CDATA[
184+
object(BcMath\Number)#1 (2) {
185+
["value"]=>
186+
string(3) "3.0"
187+
["scale"]=>
188+
int(1)
189+
}
190+
object(BcMath\Number)#3 (2) {
191+
["value"]=>
192+
string(3) "243"
193+
["scale"]=>
194+
int(0)
195+
}
196+
object(BcMath\Number)#2 (2) {
197+
["value"]=>
198+
string(4) "0.33"
199+
["scale"]=>
200+
int(2)
201+
}
202+
object(BcMath\Number)#4 (2) {
203+
["value"]=>
204+
string(12) "1.0000000000"
205+
["scale"]=>
206+
int(10)
207+
}
208+
]]>
209+
</screen>
210+
</example>
211+
</refsect1>
212+
213+
<refsect1 role="bc.operatoroverload">
214+
<!-- operator overload title -->
215+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('bcmath-number.add')/db:refsect1[@role='bc.operatoroverload']/db:title)" />
216+
<simpara>
217+
<classname>BcMath\Number</classname> can perform power using operators. The calculation with
218+
the operator behaves the same as when the method argument <parameter>scale</parameter> is &null;.
219+
</simpara>
220+
<example>
221+
<title>Example of power using operators</title>
222+
<programlisting role="php">
223+
<![CDATA[
224+
<?php
225+
$number = new BcMath\Number('3.0');
226+
227+
$ret1 = $number ** new BcMath\Number('5');
228+
$ret2 = $number ** '-1';
229+
$ret3 = $number ** 0;
230+
231+
var_dump($number, $ret1, $ret2, $ret3);
232+
?>
233+
]]>
234+
</programlisting>
235+
&example.outputs;
236+
<screen>
237+
<![CDATA[
238+
object(BcMath\Number)#1 (2) {
239+
["value"]=>
240+
string(3) "3.0"
241+
["scale"]=>
242+
int(1)
243+
}
244+
object(BcMath\Number)#3 (2) {
245+
["value"]=>
246+
string(9) "243.00000"
247+
["scale"]=>
248+
int(5)
249+
}
250+
object(BcMath\Number)#2 (2) {
251+
["value"]=>
252+
string(13) "0.33333333333"
253+
["scale"]=>
254+
int(11)
255+
}
256+
object(BcMath\Number)#4 (2) {
257+
["value"]=>
258+
string(1) "1"
259+
["scale"]=>
260+
int(0)
261+
}
262+
]]>
263+
</screen>
264+
</example>
265+
266+
<example>
267+
<title>Examples of shorthand power using operators</title>
268+
<programlisting role="php">
269+
<![CDATA[
270+
<?php
271+
$number = new BcMath\Number('1.2');
272+
$num1 = $number;
273+
$num2 = $number;
274+
$num3 = $number;
275+
276+
$num1 **= new BcMath\Number('2');
277+
$num2 **= '-1';
278+
$num3 **= 0;
279+
280+
var_dump($number, $num1, $num2, $num3);
281+
?>
282+
]]>
283+
</programlisting>
284+
&example.outputs;
285+
<screen>
286+
<![CDATA[
287+
object(BcMath\Number)#1 (2) {
288+
["value"]=>
289+
string(3) "1.2"
290+
["scale"]=>
291+
int(1)
292+
}
293+
object(BcMath\Number)#3 (2) {
294+
["value"]=>
295+
string(4) "1.44"
296+
["scale"]=>
297+
int(2)
298+
}
299+
object(BcMath\Number)#2 (2) {
300+
["value"]=>
301+
string(13) "0.83333333333"
302+
["scale"]=>
303+
int(11)
304+
}
305+
object(BcMath\Number)#4 (2) {
306+
["value"]=>
307+
string(1) "1"
308+
["scale"]=>
309+
int(0)
310+
}
311+
]]>
312+
</screen>
313+
</example>
314+
</refsect1>
315+
316+
<refsect1 role="seealso">
317+
&reftitle.seealso;
318+
<simplelist>
319+
<member><function>bcpow</function></member>
320+
<member><methodname>BcMath\Number::powmod</methodname></member>
321+
<member><methodname>BcMath\Number::mul</methodname></member>
322+
<member><methodname>BcMath\Number::sqrt</methodname></member>
323+
<member><methodname>BcMath\Number::div</methodname></member>
324+
</simplelist>
325+
</refsect1>
326+
327+
</refentry>
328+
<!-- Keep this comment at the end of the file
329+
Local variables:
330+
mode: sgml
331+
sgml-omittag:t
332+
sgml-shorttag:t
333+
sgml-minimize-attributes:nil
334+
sgml-always-quote-attributes:t
335+
sgml-indent-step:1
336+
sgml-indent-data:t
337+
indent-tabs-mode:nil
338+
sgml-parent-document:nil
339+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
340+
sgml-exposed-tags:nil
341+
sgml-local-catalogs:nil
342+
sgml-local-ecat-files:nil
343+
End:
344+
vim600: syn=xml fen fdm=syntax fdl=2 si
345+
vim: et tw=78 syn=sgml
346+
vi: ts=1 sw=1
347+
-->

‎reference/bc/functions/bcpow.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,7 @@ echo bcpow('5', '2', 2); // prints "25", not "25.00"
151151
<simplelist>
152152
<member><function>bcpowmod</function></member>
153153
<member><function>bcsqrt</function></member>
154+
<member><methodname>BcMath\Number::pow</methodname></member>
154155
</simplelist>
155156
</para>
156157
</refsect1>

0 commit comments

Comments
 (0)