reference/bc/functions/bcpow.xml
c9490d424ec11a4fe92f07f08cff95c85c7d22df
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xml:id="function.bcpow" xmlns="http://docbook.org/ns/docbook">
3
+
<refentry xml:id="function.bcpow" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
4
4
<refnamediv>
5
5
<refname>bcpow</refname>
6
6
<refpurpose>Raise an arbitrary precision number to another</refpurpose>
...
...
@@ -10,13 +10,13 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>string</type><methodname>bcpow</methodname>
13
-
<methodparam><type>string</type><parameter>left_operand</parameter></methodparam>
14
-
<methodparam><type>string</type><parameter>right_operand</parameter></methodparam>
15
-
<methodparam choice="opt"><type>int</type><parameter>scale</parameter><initializer>0</initializer></methodparam>
13
+
<methodparam><type>string</type><parameter>num</parameter></methodparam>
14
+
<methodparam><type>string</type><parameter>exponent</parameter></methodparam>
15
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>scale</parameter><initializer>&null;</initializer></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
-
Raise <parameter>left_operand</parameter> to the power
19
-
<parameter>right_operand</parameter>.
18
+
Raise <parameter>num</parameter> to the power
19
+
<parameter>exponent</parameter>.
20
20
</para>
21
21
</refsect1>
22
22

...
...
@@ -25,22 +25,24 @@
25
25
<para>
26
26
<variablelist>
27
27
<varlistentry>
28
-
<term><parameter>left_operand</parameter></term>
28
+
<term><parameter>num</parameter></term>
29
29
<listitem>
30
30
<para>
31
-
The left operand, as a string.
31
+
The base, as a string.
32
32
</para>
33
33
</listitem>
34
34
</varlistentry>
35
35
<varlistentry>
36
-
<term><parameter>right_operand</parameter></term>
36
+
<term><parameter>exponent</parameter></term>
37
37
<listitem>
38
38
<para>
39
-
The right operand, as a string.
39
+
The exponent, as a string. Must be a value with no fractional part.
40
+
The valid range of the exponent is platform specific, but is at least
41
+
<literal>-2147483648</literal> to <literal>2147483647</literal>.
40
42
</para>
41
43
</listitem>
42
44
</varlistentry>
43
-
&bc.scale.description;
45
+
<xi:include xpointer="function.bcadd..parameters.scale" />
44
46
</variablelist>
45
47
</para>
46
48
</refsect1>
...
...
@@ -52,6 +54,59 @@
52
54
</para>
53
55
</refsect1>
54
56

57
+
<refsect1 role="errors">
58
+
&reftitle.errors;
59
+
<para>
60
+
This function throws a <exceptionname>ValueError</exceptionname> in the following cases:
61
+
<simplelist>
62
+
<member><parameter>num</parameter> or <parameter>exponent</parameter> is not a well-formed BCMath numeric string</member>
63
+
<member><parameter>exponent</parameter> has a fractional part</member>
64
+
<member><parameter>exponent</parameter> or <parameter>scale</parameter> is outside the valid range</member>
65
+
</simplelist>
66
+
</para>
67
+
<simpara>
68
+
This function throws a <exceptionname>DivisionByZeroError</exceptionname> exception if <parameter>num</parameter>
69
+
is <literal>0</literal> and <parameter>exponent</parameter> is a negative value.
70
+
</simpara>
71
+
</refsect1>
72
+

73
+
<refsect1 role="changelog"><!-- {{{ -->
74
+
&reftitle.changelog;
75
+
<informaltable>
76
+
<tgroup cols="2">
77
+
<thead>
78
+
<row>
79
+
<entry>&Version;</entry>
80
+
<entry>&Description;</entry>
81
+
</row>
82
+
</thead>
83
+
<tbody>
84
+
<row>
85
+
<entry>8.4.0</entry>
86
+
<entry>
87
+
Negative powers of <literal>0</literal> previously returned <literal>0</literal>, but now throw a <exceptionname>DivisionByZeroError</exceptionname>
88
+
exception.
89
+
</entry>
90
+
</row>
91
+
<row>
92
+
<entry>8.0.0</entry>
93
+
<entry>
94
+
When <parameter>exponent</parameter> has a fractional part, it now throws a <exceptionname>ValueError</exceptionname>
95
+
instead of truncating.
96
+
</entry>
97
+
</row>
98
+
<row>
99
+
<entry>7.3.0</entry>
100
+
<entry>
101
+
<function>bcpow</function> now returns numbers with the requested scale.
102
+
Formerly, the returned numbers may have omitted trailing decimal zeroes.
103
+
</entry>
104
+
</row>
105
+
</tbody>
106
+
</tgroup>
107
+
</informaltable>
108
+
</refsect1><!-- }}} -->
109
+

55
110
<refsect1 role="examples">
56
111
&reftitle.examples;
57
112
<example>
...
...
@@ -72,7 +127,7 @@ echo bcpow('4.2', '3', 2); // 74.08
72
127
&reftitle.notes;
73
128
<note>
74
129
<para>
75
-
<function>bcpow</function> may return a result with fewer digits after the
130
+
Before PHP 7.3.0 <function>bcpow</function> may return a result with fewer digits after the
76
131
decimal point than the <parameter>scale</parameter> parameter would
77
132
indicate. This only occurs when the result doesn't require all of the
78
133
precision allowed by the <parameter>scale</parameter>. For example:
...
...
@@ -96,11 +151,11 @@ echo bcpow('5', '2', 2); // prints "25", not "25.00"
96
151
<simplelist>
97
152
<member><function>bcpowmod</function></member>
98
153
<member><function>bcsqrt</function></member>
154
+
<member><methodname>BcMath\Number::pow</methodname></member>
99
155
</simplelist>
100
156
</para>
101
157
</refsect1>
102
158
</refentry>
103
-

104
159
<!-- Keep this comment at the end of the file
105
160
Local variables:
106
161
mode: sgml
107
162



Translation status