# bcpow

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

bcpow — Élève un nombre à une puissance donnée

### Description

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

Élève `num` à la puissance `exponent`.

### Liste de paramètres

`num`

  La base, sous la forme d'une chaîne de caractères.

`exponent`

  L'exposant, sous la forme d'une chaîne de caractères. Doit être une valeur sans partie fractionnaire. L'intervale valide de l'exposant dépend de la platforme, mais c'est au minimum de `-2147483648` à `2147483647`.

`scale`
  Ce paramètre est utilisé pour définir le nombre de chiffres après la virgule dans le résultat. Si `null`, il prendra la valeur par défaut de l'échelle définie avec bcscale(), ou utilisera la valeur de la directive INI `bcmath.scale` si disponible.

### Valeurs de retour

Retourne le résultat, sous la forme d'une chaîne de caractères.

### Erreurs / Exceptions

Cette fonction lève une exception de type ValueError dans les cas suivants :

- `num` ou `exponent` n'est pas une chaîne numérique BCMath bien formée
- `exponent` contient une partie fractionnaire
- `exponent` ou `scale` est en dehors de la plage valide

Cette fonction lève une exception de type DivisionByZeroError si `num` est `0` et que `exponent` est une valeur négative.

### Historique

Version | Description
--- | ---
8.4.0 | Les puissances négatives de `0` renvoyaient auparavant `0`, mais lèvent désormais une exception DivisionByZeroError.
8.0.0 | Lorsque `exponent` contient une partie fractionnaire, une exception de type ValueError est désormais levée au lieu d'effectuer une troncature.
7.3.0 | bcpow() retourne désormais les nombres avec la précision demandé. Auparavant, les nombres retournés pouvait omettre les zéros décimaux trainant à la fin.

### Exemples

Exemple #1 Exemple avec bcpow()

`<?php
echo bcpow('4.2', '3', 2); // 74.08
?>`

### Notes

> Note:

> Antérieur à PHP 7.3.0 bcpow() peut retourner un résultat avec moins de chiffres après la virgule que le parmètre `scale` indique. Ceci ne se produit que le résultat ne nécessite pas toute la précision autorisée par `scale`. Par exemple:

> Exemple #2 bcpow() exemple pour scale

> `<?php
> echo bcpow('5', '2', 2); // affiche "25", pas "25.00"
> ?>`

### Voir aussi

- bcpowmod() - Calcule le reste modulo d'un nombre élevé à une puissance
- bcsqrt() - Récupère la racine carrée d'un nombre de grande taille
- BcMath\Number::pow() - Elève un nombre de précision arbitraire