Release/3.1.0 (#19)

src/BigNumber.php

@@ -6,6 +6,10 @@
 
 use TinyBlocks\Math\Internal\Exceptions\DivisionByZero;
 
+/**
+ * The BigNumber interface represents arbitrary-precision arithmetic, allowing
+ * precise mathematical operations on large or small numbers.
+ */
 interface BigNumber
 {
     public const AUTOMATIC_SCALE = null;
@@ -18,22 +22,6 @@ interface BigNumber
      */
     public function add(BigNumber $addend): BigNumber;
 
-    /**
-     * Subtracts another BigNumber (subtrahend) from the current BigNumber (minuend).
-     *
-     * @param BigNumber $subtrahend The BigNumber to be subtracted from the current BigNumber.
-     * @return BigNumber A new BigNumber representing the difference between the two numbers.
-     */
-    public function subtract(BigNumber $subtrahend): BigNumber;
-
-    /**
-     * Multiplies the current BigNumber (multiplicand) with another BigNumber (multiplier).
-     *
-     * @param BigNumber $multiplier The BigNumber to multiply the current BigNumber by.
-     * @return BigNumber A new BigNumber representing the product of the two numbers.
-     */
-    public function multiply(BigNumber $multiplier): BigNumber;
-
     /**
      * Divides the current BigNumber (dividend) by another BigNumber (divisor).
      *
@@ -44,62 +32,64 @@ public function multiply(BigNumber $multiplier): BigNumber;
     public function divide(BigNumber $divisor): BigNumber;
 
     /**
-     * Returns a new BigNumber after applying the specified rounding mode.
+     * Retrieves the scale of the current BigNumber.
      *
-     * @param RoundingMode $mode The rounding mode to apply.
-     * @return BigNumber A new BigNumber rounded according to the specified mode.
+     * @return int|null The scale of the current BigNumber, or null if no scale is applied.
      */
-    public function withRounding(RoundingMode $mode): BigNumber;
+    public function getScale(): ?int;
 
     /**
-     * Returns a new BigNumber with the specified scale.
+     * Compares the current BigNumber with another BigNumber to determine if it is greater.
      *
-     * @param int $scale The scale to apply to the BigNumber.
-     * @return BigNumber A new BigNumber with the specified scale.
+     * @param BigNumber $other The BigNumber to compare with.
+     * @return bool True if the current BigNumber is greater than the other BigNumber, otherwise false.
      */
-    public function withScale(int $scale): BigNumber;
+    public function isGreaterThan(BigNumber $other): bool;
 
     /**
-     * Returns a new BigNumber with the negated value of the current BigNumber.
+     * Compares the current BigNumber with another BigNumber to determine if it is greater than or equal.
      *
-     * @return BigNumber A new BigNumber representing the negated value of the current number.
+     * @param BigNumber $other The BigNumber to compare with.
+     * @return bool True if the current BigNumber is greater than or equal to the other BigNumber, otherwise false.
      */
-    public function negate(): BigNumber;
+    public function isGreaterThanOrEqual(BigNumber $other): bool;
 
     /**
-     * Retrieves the scale of the current BigNumber.
+     * Determines if the current BigNumber is negative.
      *
-     * @return int|null The scale of the current BigNumber, or null if no scale is applied.
+     * @return bool True if the BigNumber is negative, otherwise false.
      */
-    public function getScale(): ?int;
+    public function isNegative(): bool;
 
     /**
-     * Determines if the current BigNumber is equal to zero.
+     * Determines if the current BigNumber is either negative or zero.
      *
-     * @return bool True if the BigNumber is zero, otherwise false.
+     * @return bool True if the BigNumber is negative or zero, otherwise false.
      */
-    public function isZero(): bool;
+    public function isNegativeOrZero(): bool;
 
     /**
-     * Determines if the current BigNumber is negative.
+     * Compares the current BigNumber with another BigNumber to determine if it is less.
      *
-     * @return bool True if the BigNumber is negative, otherwise false.
+     * @param BigNumber $other The BigNumber to compare with.
+     * @return bool True if the current BigNumber is less than the other BigNumber, otherwise false.
      */
-    public function isNegative(): bool;
+    public function isLessThan(BigNumber $other): bool;
 
     /**
-     * Determines if the current BigNumber is positive.
+     * Compares the current BigNumber with another BigNumber to determine if it is less than or equal.
      *
-     * @return bool True if the BigNumber is positive, otherwise false.
+     * @param BigNumber $other The BigNumber to compare with.
+     * @return bool True if the current BigNumber is less than or equal to the other BigNumber, otherwise false.
      */
-    public function isPositive(): bool;
+    public function isLessThanOrEqual(BigNumber $other): bool;
 
     /**
-     * Determines if the current BigNumber is either negative or zero.
+     * Determines if the current BigNumber is positive.
      *
-     * @return bool True if the BigNumber is negative or zero, otherwise false.
+     * @return bool True if the BigNumber is positive, otherwise false.
      */
-    public function isNegativeOrZero(): bool;
+    public function isPositive(): bool;
 
     /**
      * Determines if the current BigNumber is either positive or zero.
@@ -109,36 +99,34 @@ public function isNegativeOrZero(): bool;
     public function isPositiveOrZero(): bool;
 
     /**
-     * Compares the current BigNumber with another BigNumber to determine if it is less.
+     * Determines if the current BigNumber is equal to zero.
      *
-     * @param BigNumber $other The BigNumber to compare with.
-     * @return bool True if the current BigNumber is less than the other BigNumber, otherwise false.
+     * @return bool True if the BigNumber is zero, otherwise false.
      */
-    public function isLessThan(BigNumber $other): bool;
+    public function isZero(): bool;
 
     /**
-     * Compares the current BigNumber with another BigNumber to determine if it is greater.
+     * Multiplies the current BigNumber (multiplicand) with another BigNumber (multiplier).
      *
-     * @param BigNumber $other The BigNumber to compare with.
-     * @return bool True if the current BigNumber is greater than the other BigNumber, otherwise false.
+     * @param BigNumber $multiplier The BigNumber to multiply the current BigNumber by.
+     * @return BigNumber A new BigNumber representing the product of the two numbers.
      */
-    public function isGreaterThan(BigNumber $other): bool;
+    public function multiply(BigNumber $multiplier): BigNumber;
 
     /**
-     * Compares the current BigNumber with another BigNumber to determine if it is less than or equal.
+     * Returns a new BigNumber with the negated value of the current BigNumber.
      *
-     * @param BigNumber $other The BigNumber to compare with.
-     * @return bool True if the current BigNumber is less than or equal to the other BigNumber, otherwise false.
+     * @return BigNumber A new BigNumber representing the negated value of the current number.
      */
-    public function isLessThanOrEqual(BigNumber $other): bool;
+    public function negate(): BigNumber;
 
     /**
-     * Compares the current BigNumber with another BigNumber to determine if it is greater than or equal.
+     * Subtracts another BigNumber (subtrahend) from the current BigNumber (minuend).
      *
-     * @param BigNumber $other The BigNumber to compare with.
-     * @return bool True if the current BigNumber is greater than or equal to the other BigNumber, otherwise false.
+     * @param BigNumber $subtrahend The BigNumber to be subtracted from the current BigNumber.
+     * @return BigNumber A new BigNumber representing the difference between the two numbers.
      */
-    public function isGreaterThanOrEqual(BigNumber $other): bool;
+    public function subtract(BigNumber $subtrahend): BigNumber;
 
     /**
      * Converts the current BigNumber to a floating-point number.
@@ -154,4 +142,20 @@ public function toFloat(): float;
      * @return string The string representation of the BigNumber.
      */
     public function toString(): string;
+
+    /**
+     * Returns a new BigNumber after applying the specified rounding mode.
+     *
+     * @param RoundingMode $mode The rounding mode to apply.
+     * @return BigNumber A new BigNumber rounded according to the specified mode.
+     */
+    public function withRounding(RoundingMode $mode): BigNumber;
+
+    /**
+     * Returns a new BigNumber with the specified scale.
+     *
+     * @param int $scale The scale to apply to the BigNumber.
+     * @return BigNumber A new BigNumber with the specified scale.
+     */
+    public function withScale(int $scale): BigNumber;
 }

src/Internal/Exceptions/InvalidNumber.php

@@ -8,7 +8,7 @@
 
 final class InvalidNumber extends RuntimeException
 {
-    public function __construct(mixed $value)
+    public function __construct(string $value)
     {
         $template = 'The value <%s> is not a valid number.';
         parent::__construct(message: sprintf($template, $value));

src/Internal/Exceptions/NonPositiveValue.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\Math\Internal\Exceptions;
+
+use RuntimeException;
+use TinyBlocks\Math\Internal\Number;
+
+final class NonPositiveValue extends RuntimeException
+{
+    public function __construct(Number $number)
+    {
+        $template = 'Value <%s> is not valid. Must be a positive number greater than zero.';
+        parent::__construct(message: sprintf($template, $number->value));
+    }
+}

src/Internal/Number.php

@@ -6,7 +6,7 @@
 
 use TinyBlocks\Math\Internal\Exceptions\InvalidNumber;
 
-class Number
+final class Number
 {
     private const ZERO = 0.0;
     private const SIGN = '?<sign>[\-\+]';

src/PositiveBigDecimal.php

@@ -5,7 +5,7 @@
 namespace TinyBlocks\Math;
 
 use TinyBlocks\Math\Internal\BigNumberBehavior;
-use TinyBlocks\Math\Internal\Exceptions\NonPositiveNumber;
+use TinyBlocks\Math\Internal\Exceptions\NonPositiveValue;
 use TinyBlocks\Math\Internal\Number;
 use TinyBlocks\Math\Internal\Scale;
 
@@ -17,7 +17,7 @@ protected function __construct(string|float $value, ?int $scale = null)
         $number = Number::from(value: $value);
 
         if ($number->isNegativeOrZero()) {
-            throw new NonPositiveNumber(number: $number);
+            throw new NonPositiveValue(number: $number);
         }
 
         parent::__construct(number: $number, scale: $scale);

tests/Models/CustomPositiveBigDecimal.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\Math\Models;
+
+use TinyBlocks\Math\PositiveBigDecimal;
+
+final class CustomPositiveBigDecimal extends PositiveBigDecimal
+{
+}

tests/PositiveBigDecimalTest.php

@@ -6,7 +6,8 @@
 
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
-use TinyBlocks\Math\Internal\Exceptions\NonPositiveNumber;
+use TinyBlocks\Math\Internal\Exceptions\NonPositiveValue;
+use TinyBlocks\Math\Models\CustomPositiveBigDecimal;
 
 final class PositiveBigDecimalTest extends TestCase
 {
@@ -36,35 +37,48 @@ public function testFromString(): void
         self::assertInstanceOf(PositiveBigDecimal::class, $actual);
     }
 
-    #[DataProvider('dataProviderForTestNonPositiveNumber')]
-    public function testNonPositiveNumber(mixed $value): void
+    #[DataProvider('dataProviderForTestNonPositiveValue')]
+    public function testNonPositiveValue(mixed $value): void
     {
         /** @Given a non-positive value */
-        $template = 'The <%.2f> value must be positive.';
+        $template = 'Value <%s> is not valid. Must be a positive number greater than zero.';
 
-        /** @Then a NonPositiveNumber exception should be thrown with the correct message */
-        $this->expectException(NonPositiveNumber::class);
+        /** @Then a NonPositiveValue exception should be thrown with the correct message */
+        $this->expectException(NonPositiveValue::class);
         $this->expectExceptionMessage(sprintf($template, $value));
 
         /** @When attempting to create a PositiveBigDecimal with a non-positive value */
         PositiveBigDecimal::fromFloat(value: $value);
     }
 
-    public function testNonPositiveNumberWithNegate(): void
+    public function testNonPositiveValueWithNegate(): void
     {
         /** @Given a PositiveBigDecimal value */
-        $template = 'The <%.2f> value must be positive.';
+        $template = 'Value <%s> is not valid. Must be a positive number greater than zero.';
 
-        /** @Then a NonPositiveNumber exception should be thrown when the value is negated */
-        $this->expectException(NonPositiveNumber::class);
+        /** @Then a NonPositiveValue exception should be thrown when the value is negated */
+        $this->expectException(NonPositiveValue::class);
         $this->expectExceptionMessage(sprintf($template, -1.00));
 
         /** @When negating a positive number, it should trigger an exception */
         $positive = PositiveBigDecimal::fromFloat(value: 10.155);
         $positive->negate();
     }
 
-    public static function dataProviderForTestNonPositiveNumber(): array
+    public function testNonPositiveValueWithCustomClass(): void
+    {
+        /** @Given a non-positive value */
+        $template = 'Value <%s> is not valid. Must be a positive number greater than zero.';
+
+        /** @Then a NonPositiveValue exception should be thrown with the correct message */
+        $this->expectException(NonPositiveValue::class);
+        $this->expectExceptionMessage(sprintf($template, -1.00));
+
+        /** @When attempting to create a CustomPositiveBigDecimal with a non-positive value */
+        CustomPositiveBigDecimal::fromFloat(value: -1.00);
+    }
+
+    public static function dataProviderForTestNonPositiveValue(): array
     {
         return [
             'Zero value'       => ['value' => 0],