W3cubDocs

/PHP

BcMath\Number::pow

(PHP 8 >= 8.4.0)

BcMath\Number::pow — Raises an arbitrary precision number

Description

public BcMath\Number::pow(BcMath\Number|string|int $exponent, ?int $scale = null): BcMath\Number

Raises $this to the exponent power.

Parameters

exponent: The exponent. Must be a value with no fractional part. The valid range of the exponent is platform specific, but it is at least -2147483648 to 2147483647.
scale: BcMath\Number::scale explicitly specified for calculation results. If null, the BcMath\Number::scale of the calculation result will be set automatically.

Return Values

Returns the result of power as a new BcMath\Number object.

When the BcMath\Number::scale of the result object is automatically set, depending on the value of exponent, the BcMath\Number::scale of result will be as follows:

`exponent`	BcMath\Number::scale of result
positive	(BcMath\Number::scale of power base) * (`exponent`'s value)
`0`	`0`
negative	Between (BcMath\Number::scale of power base) and (BcMath\Number::scale of power base + `10`)

If an indivisible division occurs due to a negative exponent, the BcMath\Number::scale of the result is expanded. Expansion is done only as needed, up to a maximum of +10. This behavior is the same as BcMath\Number::div(), so please see that for details.

Errors/Exceptions

This method throws a ValueError in the following cases:

exponent is string and not a well-formed BCMath numeric string
exponent has a fractional part
exponent or scale is outside the valid range
BcMath\Number::scale of the result object is outside the valid range

This method throws a DivisionByZeroError exception if $this's value is 0 and exponent is a negative value.

Examples

Example #1 BcMath\Number::pow() example when scale is not specified

<?php
$number = new BcMath\Number('3.0');

$ret1 = $number->pow(new BcMath\Number('5'));
$ret2 = $number->pow('-1');
$ret3 = $number->pow(0);

var_dump($number, $ret1, $ret2, $ret3);
?>

The above example will output:

object(BcMath\Number)#1 (2) {
  ["value"]=>
  string(3) "3.0"
  ["scale"]=>
  int(1)
}
object(BcMath\Number)#3 (2) {
  ["value"]=>
  string(9) "243.00000"
  ["scale"]=>
  int(5)
}
object(BcMath\Number)#2 (2) {
  ["value"]=>
  string(13) "0.33333333333"
  ["scale"]=>
  int(11)
}
object(BcMath\Number)#4 (2) {
  ["value"]=>
  string(1) "1"
  ["scale"]=>
  int(0)
}

Example #2 BcMath\Number::pow() example of explicitly specifying scale

<?php
$number = new BcMath\Number('3.0');

$ret1 = $number->pow(new BcMath\Number('5'), 0);
$ret2 = $number->pow('-1', 2);
$ret3 = $number->pow(0, 10);

var_dump($number, $ret1, $ret2, $ret3);
?>