Adds raising by power, and raising by power and reducing by modulus methods

Author: elliotjreed

src/ElliotJReed/Maths/Exception/InvalidExponent.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ElliotJReed\Maths\Exception;
+
+final class InvalidExponent extends MathsException
+{
+    protected $message = 'Exponent must be a whole number.';
+}

src/ElliotJReed/Maths/Exception/InvalidPowerModulusDivisor.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ElliotJReed\Maths\Exception;
+
+final class InvalidPowerModulusDivisor extends MathsException
+{
+    protected $message = 'Divisor must be a whole number.';
+}

src/ElliotJReed/Maths/Exception/MathsException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ElliotJReed\Maths\Exception;
+
+use Exception;
+
+abstract class MathsException extends Exception
+{
+}

src/ElliotJReed/Maths/Number.php

@@ -4,6 +4,9 @@
 
 namespace ElliotJReed\Maths;
 
+use ElliotJReed\Maths\Exception\InvalidExponent;
+use ElliotJReed\Maths\Exception\InvalidPowerModulusDivisor;
+
 final class Number
 {
     private string $number;
@@ -90,6 +93,34 @@ public function modulus(int | float | string $divisorNumber): self
         return $this;
     }
 
+    public function raiseToPower(int | float | string $exponentNumber): self
+    {
+        if (\floor((float) $exponentNumber) !== (float) $exponentNumber) {
+            throw new InvalidExponent('Exponent must be a whole number. Invalid exponent: ' . $exponentNumber);
+        }
+
+        $this->number = \bcpow($this->number, (string) $exponentNumber, $this->precision);
+
+        return $this;
+    }
+
+    public function raiseToPowerReduceByModulus(
+        int | float | string $exponentNumber,
+        int | float | string $divisorNumber
+    ): self {
+        if (\floor((float) $exponentNumber) !== (float) $exponentNumber) {
+            throw new InvalidExponent('Exponent must be a whole number. Invalid exponent: ' . $exponentNumber);
+        }
+
+        if (\floor((float) $divisorNumber) !== (float) $divisorNumber) {
+            throw new InvalidPowerModulusDivisor('Divisor must be a whole number. Invalid divisor: ' . $divisorNumber);
+        }
+
+        $this->number = \bcpowmod($this->number, (string) $exponentNumber, (string) $divisorNumber, $this->precision);
+
+        return $this;
+    }
+
     public function isLessThan(int | float | string $number): bool
     {
         $result = \bccomp($this->number, (string) $number, $this->precision);

tests/ElliotJReed/Maths/NumberTest.php

@@ -4,6 +4,8 @@
 
 namespace ElliotJReed\Maths;
 
+use ElliotJReed\Maths\Exception\InvalidExponent;
+use ElliotJReed\Maths\Exception\InvalidPowerModulusDivisor;
 use PHPUnit\Framework\TestCase;
 
 final class NumberTest extends TestCase
@@ -558,6 +560,80 @@ public function testItReturnsModulusWhenBaseNumberIsAString(): void
         $this->assertSame(0, $number->asInteger(\PHP_ROUND_HALF_DOWN));
     }
 
+    public function testItReturnsNumberRaisedToPowerExponentWhenBaseNumberIsAnInteger(): void
+    {
+        $number = new Number(5);
+        $number->raiseToPower(3);
+
+        $this->assertSame('125', $number->asString());
+        $this->assertSame(125.0, $number->asFloat());
+        $this->assertSame(125, $number->asInteger());
+        $this->assertSame(125, $number->asInteger(\PHP_ROUND_HALF_DOWN));
+    }
+
+    public function testItReturnsNumberRaisedToPowerExponentWhenBaseNumberIsAFloat(): void
+    {
+        $number = new Number(2.75);
+        $number->raiseToPower(2);
+
+        $this->assertSame('7.5625', $number->asString());
+        $this->assertSame(7.5625, $number->asFloat());
+        $this->assertSame(8, $number->asInteger());
+        $this->assertSame(8, $number->asInteger(\PHP_ROUND_HALF_DOWN)); // TODO: use a rounded number
+    }
+
+    public function testItThrowsExceptionWhenExponentIsNotAWholeNumberWhenRaisingToPower(): void
+    {
+        $number = new Number(25);
+
+        $this->expectException(InvalidExponent::class);
+        $this->expectExceptionMessage('Exponent must be a whole number. Invalid exponent: 1.5');
+
+        $number->raiseToPower(1.5);
+    }
+
+    public function testItReturnsNumberRaisedToPowerExponentAndReducedByModulusWhenBaseNumberIsAnInteger(): void
+    {
+        $number = new Number(5371);
+        $number->raiseToPowerReduceByModulus(2, 7);
+
+        $this->assertSame('4', $number->asString());
+        $this->assertSame(4.0, $number->asFloat());
+        $this->assertSame(4, $number->asInteger());
+        $this->assertSame(4, $number->asInteger(\PHP_ROUND_HALF_DOWN));
+    }
+
+    public function testItReturnsNumberRaisedToPowerExponentAndReducedByModulusWhenBaseNumberIsAString(): void
+    {
+        $number = new Number('5371');
+        $number->raiseToPowerReduceByModulus(2, 7);
+
+        $this->assertSame('4', $number->asString());
+        $this->assertSame(4.0, $number->asFloat());
+        $this->assertSame(4, $number->asInteger());
+        $this->assertSame(4, $number->asInteger(\PHP_ROUND_HALF_DOWN));
+    }
+
+    public function testItThrowsExceptionWhenExponentIsNotAWholeNumberWhenRaisingToPowerAndReducingByModulus(): void
+    {
+        $number = new Number('5371');
+
+        $this->expectException(InvalidExponent::class);
+        $this->expectExceptionMessage('Exponent must be a whole number. Invalid exponent: 2.2');
+
+        $number->raiseToPowerReduceByModulus(2.2, 7);
+    }
+
+    public function testItThrowsExceptionWhenDivisorIsNotAWholeNumberWhenRaisingToPowerAndReducingByModulus(): void
+    {
+        $number = new Number('5371');
+
+        $this->expectException(InvalidPowerModulusDivisor::class);
+        $this->expectExceptionMessage('Divisor must be a whole number. Invalid divisor: 7.5');
+
+        $number->raiseToPowerReduceByModulus(2, 7.5);
+    }
+
     public function testItReturnsTrueWhenNumberIsLessThanTheBaseNumberWhenCheckingIfNumberIsLessThanBaseNumber(): void
     {
         $number = new Number('100.01');