Home/ Manual/ bc / functions/ bcpow

bcpow

PHP function Edit on GitHub ✎

(PHP 4, PHP 5, PHP 7, PHP 8)

Raise an arbitrary precision number to another

Description

bcpow(string $num, string $exponent, int|null $scale = null): string

Raise num to the power exponent.

Parameters

num: The base, as a string.
exponent: 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 -2147483648 to 2147483647.

Return Values

Returns the result as a string.

Errors/Exceptions

This function throws a ValueError in the following cases:

num or exponent is not a well-formed BCMath numeric string
exponent has a fractional part
exponent or scale is outside the valid range

This function throws a DivisionByZeroError exception if num is 0 and exponent is a negative value.

Changelog

Version	Description
8.4.0	Negative powers of `0` previously returned `0`, but now throw a `DivisionByZeroError` exception.
8.0.0	When `exponent` has a fractional part, it now throws a `ValueError` instead of truncating.
7.3.0	`bcpow()` now returns numbers with the requested scale. Formerly, the returned numbers may have omitted trailing decimal zeroes.

Examples

bcpow() example

php

<?php

echo bcpow('4.2', '3', 2); // 74.08

?>

Notes

Note

Before PHP 7.3.0 bcpow() may return a result with fewer digits after the decimal point than the scale parameter would indicate. This only occurs when the result doesn't require all of the precision allowed by the scale. For example:

bcpow() scale example

php

<?php
echo bcpow('5', '2', 2);     // prints "25", not "25.00"
?>