Skip to content

Commit 4fbed5c

Browse files
SakiTakamachiSakiTakamachi
committed
Created pow()
1 parent 5d9e5f4 commit 4fbed5c

File tree

2 files changed

+349
-0
lines changed

2 files changed

+349
-0
lines changed

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

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

‎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)