reference/bc/functions/bcpowmod.xml
3295741565f760edd22e305bd10e37f243e9e194
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xml:id="function.bcpowmod" xmlns="http://docbook.org/ns/docbook">
3
+
<refentry xml:id="function.bcpowmod" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
4
4
<refnamediv>
5
5
<refname>bcpowmod</refname>
6
6
<refpurpose>Raise an arbitrary precision number to another, reduced by a specified modulus</refpurpose>
...
...
@@ -10,15 +10,15 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>string</type><methodname>bcpowmod</methodname>
13
-
<methodparam><type>string</type><parameter>left_operand</parameter></methodparam>
14
-
<methodparam><type>string</type><parameter>right_operand</parameter></methodparam>
13
+
<methodparam><type>string</type><parameter>num</parameter></methodparam>
14
+
<methodparam><type>string</type><parameter>exponent</parameter></methodparam>
15
15
<methodparam><type>string</type><parameter>modulus</parameter></methodparam>
16
-
<methodparam choice="opt"><type>int</type><parameter>scale</parameter><initializer>0</initializer></methodparam>
16
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>scale</parameter><initializer>&null;</initializer></methodparam>
17
17
</methodsynopsis>
18
18
<para>
19
19
Use the fast-exponentiation method to raise
20
-
<parameter>left_operand</parameter> to the power
21
-
<parameter>right_operand</parameter> with respect to the modulus
20
+
<parameter>num</parameter> to the power
21
+
<parameter>exponent</parameter> with respect to the modulus
22
22
<parameter>modulus</parameter>.
23
23
</para>
24
24
</refsect1>
...
...
@@ -28,18 +28,18 @@
28
28
<para>
29
29
<variablelist>
30
30
<varlistentry>
31
-
<term><parameter>left_operand</parameter></term>
31
+
<term><parameter>num</parameter></term>
32
32
<listitem>
33
33
<para>
34
-
The left operand, as a string.
34
+
The base, as an integral string (i.e. the scale has to be zero).
35
35
</para>
36
36
</listitem>
37
37
</varlistentry>
38
38
<varlistentry>
39
-
<term><parameter>right_operand</parameter></term>
39
+
<term><parameter>exponent</parameter></term>
40
40
<listitem>
41
41
<para>
42
-
The right operand, as a string.
42
+
The exponent, as an non-negative, integral string (i.e. the scale has to be zero).
43
43
</para>
44
44
</listitem>
45
45
</varlistentry>
...
...
@@ -47,11 +47,11 @@
47
47
<term><parameter>modulus</parameter></term>
48
48
<listitem>
49
49
<para>
50
-
The modulus, as a string.
50
+
The modulus, as an integral string (i.e. the scale has to be zero).
51
51
</para>
52
52
</listitem>
53
53
</varlistentry>
54
-
&bc.scale.description;
54
+
<xi:include xpointer="function.bcadd..parameters.scale" />
55
55
</variablelist>
56
56
</para>
57
57
</refsect1>
...
...
@@ -59,19 +59,59 @@
59
59
<refsect1 role="returnvalues">
60
60
&reftitle.returnvalues;
61
61
<para>
62
-
Returns the result as a string, or &null; if <parameter>modulus</parameter>
63
-
is 0.
62
+
Returns the result as a string.
64
63
</para>
65
64
</refsect1>
66
65

67
-
<refsect1 role="notes">
68
-
&reftitle.notes;
69
-
<note>
70
-
<para>
71
-
Because this method uses the modulus operation, numbers which are not
72
-
positive integers may give unexpected results.
73
-
</para>
74
-
</note>
66
+
<refsect1 role="errors">
67
+
&reftitle.errors;
68
+
<para>
69
+
This function throws a <exceptionname>ValueError</exceptionname> in the following cases:
70
+
<simplelist>
71
+
<member><parameter>num</parameter>, <parameter>exponent</parameter> or <parameter>modulus</parameter> is not a well-formed BCMath numeric string</member>
72
+
<member><parameter>num</parameter>, <parameter>exponent</parameter> or <parameter>modulus</parameter> has a fractional part</member>
73
+
<member><parameter>exponent</parameter> is a negative value</member>
74
+
<member><parameter>scale</parameter> is outside the valid range</member>
75
+
</simplelist>
76
+
</para>
77
+
<simpara>
78
+
This function throws a <exceptionname>DivisionByZeroError</exceptionname> exception if <parameter>modulus</parameter>
79
+
is <literal>0</literal>.
80
+
</simpara>
81
+
</refsect1>
82
+

83
+
<refsect1 role="changelog">
84
+
&reftitle.changelog;
85
+
<informaltable>
86
+
<tgroup cols="2">
87
+
<thead>
88
+
<row>
89
+
<entry>&Version;</entry>
90
+
<entry>&Description;</entry>
91
+
</row>
92
+
</thead>
93
+
<tbody>
94
+
<row>
95
+
<entry>8.0.0</entry>
96
+
<entry>
97
+
<parameter>scale</parameter> is now nullable.
98
+
</entry>
99
+
</row>
100
+
<row>
101
+
<entry>8.0.0</entry>
102
+
<entry>
103
+
Now throws a <exceptionname>ValueError</exceptionname> instead of returning &false; if <parameter>exponent</parameter> is a negative value.
104
+
</entry>
105
+
</row>
106
+
<row>
107
+
<entry>8.0.0</entry>
108
+
<entry>
109
+
Dividing by <literal>0</literal> now throws a <exceptionname>DivisionByZeroError</exceptionname> exception instead of returning &false;.
110
+
</entry>
111
+
</row>
112
+
</tbody>
113
+
</tgroup>
114
+
</informaltable>
75
115
</refsect1>
76
116

77
117
<refsect1 role="examples">
...
...
@@ -97,17 +137,27 @@ $b = bcmod(bcpow($x, $y), $mod);
97
137
</para>
98
138
</refsect1>
99
139

140
+
<refsect1 role="notes">
141
+
&reftitle.notes;
142
+
<note>
143
+
<para>
144
+
Because this method uses the modulus operation, numbers which are not
145
+
positive integers may give unexpected results.
146
+
</para>
147
+
</note>
148
+
</refsect1>
149
+

100
150
<refsect1 role="seealso">
101
151
&reftitle.seealso;
102
152
<para>
103
153
<simplelist>
104
154
<member><function>bcpow</function></member>
105
155
<member><function>bcmod</function></member>
156
+
<member><methodname>BcMath\Number::powmod</methodname></member>
106
157
</simplelist>
107
158
</para>
108
159
</refsect1>
109
160
</refentry>
110
-

111
161
<!-- Keep this comment at the end of the file
112
162
Local variables:
113
163
mode: sgml
114
164



Translation status