Adds decimal places method

Author: elliotjreed

src/ElliotJReed/Maths/Exception/InvalidDecimalPlaces.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ElliotJReed\Maths\Exception;
+
+final class InvalidDecimalPlaces extends MathsException
+{
+    protected $message = 'Decimal places must be a whole number greater than or equal to 0.';
+}

src/ElliotJReed/Maths/Number.php

@@ -4,6 +4,7 @@
 
 namespace ElliotJReed\Maths;
 
+use ElliotJReed\Maths\Exception\InvalidDecimalPlaces;
 use ElliotJReed\Maths\Exception\InvalidExponent;
 use ElliotJReed\Maths\Exception\InvalidPowerModulusDivisor;
 
@@ -35,6 +36,17 @@ public function asInteger(int $roundingMode = \PHP_ROUND_HALF_UP): int
         return (int) \round((float) $this->number, mode: $roundingMode);
     }
 
+    public function toDecimalPlaces(int $decimalPlaces, int $roundingMode = \PHP_ROUND_HALF_UP): self
+    {
+        if ($decimalPlaces < 0) {
+            throw new InvalidDecimalPlaces('Decimal places must be a whole number greater than or equal to 0. Invalid decimal places number: ' . $decimalPlaces);
+        }
+
+        $this->number = (string) \round((float) $this->number, $decimalPlaces, mode: $roundingMode);
+
+        return $this;
+    }
+
     public function add(self | int | float | string ...$number): self
     {
         foreach ($number as $numberAsIntegerOrFloatOrString) {

tests/ElliotJReed/Maths/NumberTest.php

@@ -4,6 +4,7 @@
 
 namespace ElliotJReed\Maths;
 
+use ElliotJReed\Maths\Exception\InvalidDecimalPlaces;
 use ElliotJReed\Maths\Exception\InvalidExponent;
 use ElliotJReed\Maths\Exception\InvalidPowerModulusDivisor;
 use PHPUnit\Framework\TestCase;
@@ -926,4 +927,36 @@ public function testItReturnsTrueWhenNumberIsEqualToTheBaseNumberWhenCheckingIfN
 
         $this->assertTrue($number->isGreaterThanOrEqualTo(new Number('1.002')));
     }
+
+    public function testItReturnsNumberSetToDefinedDecimalPlaces(): void
+    {
+        $number = new Number('1.005');
+        $number->toDecimalPlaces(2);
+
+        $this->assertSame('1.01', $number->asString());
+        $this->assertSame(1.01, $number->asFloat());
+        $this->assertSame(1, $number->asInteger());
+        $this->assertSame(1, $number->asInteger(\PHP_ROUND_HALF_DOWN));
+    }
+
+    public function testItReturnsNumberSetToDefinedDecimalPlacesWhenRoundingDown(): void
+    {
+        $number = new Number('1.005');
+        $number->toDecimalPlaces(2, \PHP_ROUND_HALF_DOWN);
+
+        $this->assertSame('1', $number->asString());
+        $this->assertSame(1.0, $number->asFloat());
+        $this->assertSame(1, $number->asInteger());
+        $this->assertSame(1, $number->asInteger(\PHP_ROUND_HALF_DOWN));
+    }
+
+    public function testItThrowsExceptionWhenDecimalPlacesArgumentIsLessThanZero(): void
+    {
+        $number = new Number('1.005');
+
+        $this->expectException(InvalidDecimalPlaces::class);
+        $this->expectExceptionMessage('Decimal places must be a whole number greater than or equal to 0. Invalid decimal places number: -2');
+
+        $number->toDecimalPlaces(-2);
+    }
 }