1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.bcpow" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>bcpow</refname>
<refpurpose>Raise an arbitrary precision number to another</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>bcpow</methodname>
<methodparam><type>string</type><parameter>num</parameter></methodparam>
<methodparam><type>string</type><parameter>exponent</parameter></methodparam>
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>scale</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
Raise <parameter>num</parameter> to the power
<parameter>exponent</parameter>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>num</parameter></term>
<listitem>
<para>
The base, as a string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>exponent</parameter></term>
<listitem>
<para>
The exponent, as a string. Must be a value with no fractional part.
The valid range of the exponent is platform specific, but is at least
<literal>-2147483648</literal> to <literal>2147483647</literal>.
</para>
</listitem>
</varlistentry>
&bc.scale.description;
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the result as a string.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
This function throws a <exceptionname>ValueError</exceptionname> in the following cases:
<simplelist>
<member><parameter>num</parameter> or <parameter>exponent</parameter> is not a well-formed BCMath numeric string</member>
<member><parameter>exponent</parameter> has a fractional part</member>
<member><parameter>exponent</parameter> or <parameter>scale</parameter> is outside the valid range</member>
</simplelist>
</para>
<simpara>
This function throws a <exceptionname>DivisionByZeroError</exceptionname> exception if <parameter>num</parameter>
is <literal>0</literal> and <parameter>exponent</parameter> is a negative value.
</simpara>
</refsect1>
<refsect1 role="changelog"><!-- {{{ -->
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.4.0</entry>
<entry>
Negative powers of <literal>0</literal> previously returned 0, but now throw a <exceptionname>DivisionByZeroError</exceptionname>
exception.
</entry>
</row>
<row>
<entry>8.0.0</entry>
<entry>
When <parameter>exponent</parameter> has a fractional part, it now throws a <exceptionname>ValueError</exceptionname>
instead of truncating.
</entry>
</row>
<row>
<entry>7.3.0</entry>
<entry>
<function>bcpow</function> now returns numbers with the requested scale.
Formerly, the returned numbers may have omitted trailing decimal zeroes.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1><!-- }}} -->
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>bcpow</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
echo bcpow('4.2', '3', 2); // 74.08
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<para>
Before PHP 7.3.0 <function>bcpow</function> may return a result with fewer digits after the
decimal point than the <parameter>scale</parameter> parameter would
indicate. This only occurs when the result doesn't require all of the
precision allowed by the <parameter>scale</parameter>. For example:
<example>
<title><function>bcpow</function> scale example</title>
<programlisting role="php">
<![CDATA[
<?php
echo bcpow('5', '2', 2); // prints "25", not "25.00"
?>
]]>
</programlisting>
</example>
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>bcpowmod</function></member>
<member><function>bcsqrt</function></member>
</simplelist>
</para>
</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
-->
|
