[doc-en] master: gmp: document the ValueErrors for negative and out of range arguments (#6006)

Author: qodelicious (qodelicious) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-10-24T08:33:55+02:00 Commit: https://github.com/php/doc-en/commit/f2d5808339e7bf94474f0fe0330c3bd9419d4bfe Raw diff: https://github.com/php/doc-en/commit/f2d5808339e7bf94474f0fe0330c3bd9419d4bfe.diff gmp: document the ValueErrors for negative and out of range arguments (#6006) * gmp: document the ValueErrors for negative and out of range arguments * Say the too large case is new in PHP 8.5.0 * Apply suggestion from @lacatoire * gmp_powm(): use simpara and fix the description sentence --------- Co-authored-by: Louis-Arnaud <la.catoire@gmail.com> Changed paths: M reference/gmp/functions/gmp-clrbit.xml M reference/gmp/functions/gmp-fact.xml M reference/gmp/functions/gmp-pow.xml M reference/gmp/functions/gmp-powm.xml M reference/gmp/functions/gmp-root.xml M reference/gmp/functions/gmp-rootrem.xml M reference/gmp/functions/gmp-scan0.xml M reference/gmp/functions/gmp-scan1.xml M reference/gmp/functions/gmp-setbit.xml M reference/gmp/functions/gmp-sqrt.xml M reference/gmp/functions/gmp-sqrtrem.xml M reference/gmp/functions/gmp-strval.xml M reference/gmp/functions/gmp-testbit.xml Diff: diff --git a/reference/gmp/functions/gmp-clrbit.xml b/reference/gmp/functions/gmp-clrbit.xml index fd6f56899b9c..7bf5a41af6ac 100644 --- a/reference/gmp/functions/gmp-clrbit.xml +++ b/reference/gmp/functions/gmp-clrbit.xml @@ -50,6 +50,16 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>index</parameter> is negative or, as of PHP 8.5.0, too large. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised instead. + </simpara> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <example> diff --git a/reference/gmp/functions/gmp-fact.xml b/reference/gmp/functions/gmp-fact.xml index dc58908b1dcb..178f86ba306b 100644 --- a/reference/gmp/functions/gmp-fact.xml +++ b/reference/gmp/functions/gmp-fact.xml @@ -41,6 +41,16 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>num</parameter> is negative. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised instead. + </simpara> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> diff --git a/reference/gmp/functions/gmp-pow.xml b/reference/gmp/functions/gmp-pow.xml index 51e7796afa5a..28981a3c19f5 100644 --- a/reference/gmp/functions/gmp-pow.xml +++ b/reference/gmp/functions/gmp-pow.xml @@ -51,6 +51,16 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>exponent</parameter> is negative. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised instead. + </simpara> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> @@ -63,8 +73,6 @@ $pow1 = gmp_pow("2", 31); echo gmp_strval($pow1) . "\n"; $pow2 = gmp_pow("0", 0); echo gmp_strval($pow2) . "\n"; -$pow3 = gmp_pow("2", -1); // Negative exp, generates warning -echo gmp_strval($pow3) . "\n"; ?> ]]> </programlisting> diff --git a/reference/gmp/functions/gmp-powm.xml b/reference/gmp/functions/gmp-powm.xml index bb5dffa1cb5d..caa9f1825115 100644 --- a/reference/gmp/functions/gmp-powm.xml +++ b/reference/gmp/functions/gmp-powm.xml @@ -14,11 +14,10 @@ <methodparam><type class="union"><type>GMP</type><type>int</type><type>string</type></type><parameter>exponent</parameter></methodparam> <methodparam><type class="union"><type>GMP</type><type>int</type><type>string</type></type><parameter>modulus</parameter></methodparam> </methodsynopsis> - <para> + <simpara> Calculate (<parameter>num</parameter> raised into power - <parameter>exponent</parameter>) modulo <parameter>modulus</parameter>. If - <parameter>exponent</parameter> is negative, result is undefined. - </para> + <parameter>exponent</parameter>) modulo <parameter>modulus</parameter>. + </simpara> </refsect1> @@ -64,6 +63,20 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>exponent</parameter> is negative. + </simpara> + <simpara> + Throws a <exceptionname>DivisionByZeroError</exceptionname> if <parameter>modulus</parameter> + is <literal>0</literal>. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised instead. + </simpara> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> diff --git a/reference/gmp/functions/gmp-root.xml b/reference/gmp/functions/gmp-root.xml index 74b014cee2a7..6b7b50ba14b0 100644 --- a/reference/gmp/functions/gmp-root.xml +++ b/reference/gmp/functions/gmp-root.xml @@ -47,6 +47,17 @@ The integer component of the resultant root, as a GMP number. </para> </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>nth</parameter> is less than <literal>1</literal>, + or if <parameter>nth</parameter> is even and <parameter>num</parameter> is negative. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised instead. + </simpara> + </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: diff --git a/reference/gmp/functions/gmp-rootrem.xml b/reference/gmp/functions/gmp-rootrem.xml index 7300130f298a..aae4ee1be0ee 100644 --- a/reference/gmp/functions/gmp-rootrem.xml +++ b/reference/gmp/functions/gmp-rootrem.xml @@ -49,6 +49,17 @@ numbers. </para> </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>nth</parameter> is less than <literal>1</literal>, + or if <parameter>nth</parameter> is even and <parameter>num</parameter> is negative. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised instead. + </simpara> + </refsect1> </refentry> <!-- Keep this comment at the end of the file Local variables: diff --git a/reference/gmp/functions/gmp-scan0.xml b/reference/gmp/functions/gmp-scan0.xml index 5de0ead1c420..38153f390b8c 100644 --- a/reference/gmp/functions/gmp-scan0.xml +++ b/reference/gmp/functions/gmp-scan0.xml @@ -53,6 +53,16 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>start</parameter> is negative or, as of PHP 8.5.0, too large. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised instead. + </simpara> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> diff --git a/reference/gmp/functions/gmp-scan1.xml b/reference/gmp/functions/gmp-scan1.xml index aeff7425e924..130dd88e1bae 100644 --- a/reference/gmp/functions/gmp-scan1.xml +++ b/reference/gmp/functions/gmp-scan1.xml @@ -53,6 +53,16 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>start</parameter> is negative or, as of PHP 8.5.0, too large. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised instead. + </simpara> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> diff --git a/reference/gmp/functions/gmp-setbit.xml b/reference/gmp/functions/gmp-setbit.xml index 7b5454714687..dd0c37b90623 100644 --- a/reference/gmp/functions/gmp-setbit.xml +++ b/reference/gmp/functions/gmp-setbit.xml @@ -58,6 +58,16 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>index</parameter> is negative or too large. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised instead. + </simpara> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> diff --git a/reference/gmp/functions/gmp-sqrt.xml b/reference/gmp/functions/gmp-sqrt.xml index 31bf4f87875e..a4baff954e70 100644 --- a/reference/gmp/functions/gmp-sqrt.xml +++ b/reference/gmp/functions/gmp-sqrt.xml @@ -38,6 +38,16 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>num</parameter> is negative. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised instead. + </simpara> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> diff --git a/reference/gmp/functions/gmp-sqrtrem.xml b/reference/gmp/functions/gmp-sqrtrem.xml index 781c0af02893..5665941006c7 100644 --- a/reference/gmp/functions/gmp-sqrtrem.xml +++ b/reference/gmp/functions/gmp-sqrtrem.xml @@ -44,6 +44,16 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>num</parameter> is negative. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised instead. + </simpara> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> diff --git a/reference/gmp/functions/gmp-strval.xml b/reference/gmp/functions/gmp-strval.xml index c6ca69e455ea..aa28b9708151 100644 --- a/reference/gmp/functions/gmp-strval.xml +++ b/reference/gmp/functions/gmp-strval.xml @@ -52,6 +52,17 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>base</parameter> is not between + <literal>2</literal> and <literal>62</literal>, or <literal>-2</literal> and <literal>-36</literal>. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised instead. + </simpara> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> diff --git a/reference/gmp/functions/gmp-testbit.xml b/reference/gmp/functions/gmp-testbit.xml index ef0f8ec47334..5cf0713cd814 100644 --- a/reference/gmp/functions/gmp-testbit.xml +++ b/reference/gmp/functions/gmp-testbit.xml @@ -50,11 +50,12 @@ <refsect1 role="errors"> &reftitle.errors; - <para> - An <constant>E_WARNING</constant> level error is issued when - <parameter>index</parameter> is less than zero, and &false; - is returned. - </para> + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if <parameter>index</parameter> is negative or, as of PHP 8.5.0, too large. + </simpara> + <simpara> + Prior to PHP 8.0.0, an <constant>E_WARNING</constant> was raised and &false; was returned instead. + </simpara> </refsect1> <refsect1 role="examples">