Adds formatting string to defined decimal places

Author: elliotjreed

src/ElliotJReed/Maths/Number.php

@@ -17,8 +17,16 @@ public function __construct(self | int | float | string $number = 0, private rea
         $this->number = $this->castNumberToString($number);
     }
 
-    public function asString(): string
+    public function asString(?int $decimalPlaces = null): string
     {
+        if (null !== $decimalPlaces) {
+            if ($decimalPlaces < 0) {
+                throw new InvalidDecimalPlaces('Decimal places must be a whole number greater than or equal to 0. Invalid decimal places number: ' . $decimalPlaces);
+            }
+
+            return \number_format((float) $this->number, $decimalPlaces, '.', '');
+        }
+
         if (\str_contains($this->number, '.')) {
             $this->number = \rtrim($this->number, '0');
         }
@@ -36,7 +44,7 @@ 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
+    public function roundToDecimalPlaces(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);

tests/ElliotJReed/Maths/NumberTest.php

@@ -11,6 +11,34 @@
 
 final class NumberTest extends TestCase
 {
+    public function testItReturnsNumberAsStringToDefinedDecimalPlaces(): void
+    {
+        $number = new Number(0.29533);
+
+        $this->assertSame('0.30', $number->asString(2));
+        $this->assertSame('0.29533', $number->asString());
+        $this->assertSame(0.29533, $number->asFloat());
+    }
+
+    public function testItReturnsNumberAsWholeNumberStringToZeroDefinedDecimalPlaces(): void
+    {
+        $number = new Number(1.29533);
+
+        $this->assertSame('1', $number->asString(0));
+        $this->assertSame('1.29533', $number->asString());
+        $this->assertSame(1.29533, $number->asFloat());
+    }
+
+    public function testItThrowsExceptionWhenDecimalPlacesArgumentIsLessThanZeroWhenReturningNumberAsAString(): 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->asString(-2);
+    }
+
     public function testItMultipliesFloatingPointNumberAsFloat(): void
     {
         $number = new Number(0.295);
@@ -928,10 +956,10 @@ public function testItReturnsTrueWhenNumberIsEqualToTheBaseNumberWhenCheckingIfN
         $this->assertTrue($number->isGreaterThanOrEqualTo(new Number('1.002')));
     }
 
-    public function testItReturnsNumberSetToDefinedDecimalPlaces(): void
+    public function testItReturnsNumberSetToDefinedDecimalPlacesWhenRoundingUpByDefault(): void
     {
         $number = new Number('1.005');
-        $number->toDecimalPlaces(2);
+        $number->roundToDecimalPlaces(2);
 
         $this->assertSame('1.01', $number->asString());
         $this->assertSame(1.01, $number->asFloat());
@@ -942,21 +970,21 @@ public function testItReturnsNumberSetToDefinedDecimalPlaces(): void
     public function testItReturnsNumberSetToDefinedDecimalPlacesWhenRoundingDown(): void
     {
         $number = new Number('1.005');
-        $number->toDecimalPlaces(2, \PHP_ROUND_HALF_DOWN);
+        $number->roundToDecimalPlaces(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
+    public function testItThrowsExceptionWhenDecimalPlacesArgumentIsLessThanZeroWhenRoundingNumber(): 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);
+        $number->roundToDecimalPlaces(-2);
     }
 }