Release/3.0.0 (#13)

Author: gustavofreze

README.md

@@ -29,24 +29,38 @@ composer require tiny-blocks/math
 The library exposes some concrete implementations for arbitrary precision numbers. Concrete implementations implement
 the `BigNumber` interface, which provides the behaviors for the respective **BigNumbers**.
 
-### Using the from method
+### Using the fromString method
 
-With the `from` method, a new instance of type `BigNumber` is created from a valid numeric value. You can provide
-a `string` or `float` value.
+With the `fromString` method, a new instance of type `BigNumber` is created from a valid string numeric value.
 
 ```php
-BigDecimal::from(value: '10');
-BigDecimal::from(value: 10);
+BigDecimal::fromString(value: '10');
+BigDecimal::fromString(value: '-123.456');
 ```
 
-It is possible to set a `scale` for the object through the `from` method.
+It is possible to set a `scale` for the object through this method.
 
 ```php
-BigDecimal::from(value: '10', scale: 2);
+BigDecimal::fromString(value: '10', scale: 2);
 ```
 
-Floating point values instantiated from a `float` may not be safe, as they are imprecise by design and may result in a
-loss of precision. Always prefer to instantiate from a `string`, which supports an unlimited amount digits.
+Always prefer to instantiate from a string, which supports an unlimited number of digits and ensures no loss of
+precision.
+
+### Using the fromFloat method
+
+With the `fromFloat` method, a new instance of type `BigNumber` is created from a valid float value.
+
+```php
+BigDecimal::fromFloat(value: 10.0);
+BigDecimal::fromFloat(value: -123.456);
+```
+
+It is also possible to set a `scale` for the object through this method.
+
+```php
+BigDecimal::fromFloat(value: 10.0, scale: 2);
+```
 
 ### Using the methods of mathematical operations
 
@@ -55,8 +69,8 @@ loss of precision. Always prefer to instantiate from a `string`, which supports
 Performs an addition operation between this value and another value.
 
 ```php
-$augend = BigDecimal::from(value: 1);
-$addend = BigDecimal::from(value: '1');
+$augend = BigDecimal::fromString(value: '1');
+$addend = BigDecimal::fromFloat(value: 1.0);
 
 $result = $augend->add(addend: $addend);
 
@@ -68,8 +82,8 @@ $result->toString(); # 2
 Performs a subtraction operation between this value and another value.
 
 ```php
-$minuend = BigDecimal::from(value: 1);
-$subtrahend = BigDecimal::from(value: '1');
+$minuend = BigDecimal::fromString(value: '1');
+$subtrahend = BigDecimal::fromFloat(value: 1.0);
 
 $result = $minuend->subtract(subtrahend: $subtrahend);
 
@@ -81,8 +95,8 @@ $result->toString(); # 0
 Performs a multiplication operation between this value and another value.
 
 ```php
-$multiplicand = BigDecimal::from(value: 1);
-$multiplier = BigDecimal::from(value: '1');
+$multiplicand = BigDecimal::fromString(value: '1');
+$multiplier = BigDecimal::fromFloat(value: 1.0);
 
 $result = $multiplicand->multiply(multiplier: $multiplier);
 
@@ -94,8 +108,8 @@ $result->toString(); # 1
 Performs a division operation between this value and another value.
 
 ```php
-$dividend = BigDecimal::from(value: 1);
-$divisor = BigDecimal::from(value: '1');
+$dividend = BigDecimal::fromString(value: '1');
+$divisor = BigDecimal::fromFloat(value: 1.0);
 
 $result = $dividend->divide(divisor: $divisor);
 
@@ -112,18 +126,18 @@ rounding occurs:
 - `HALF_UP`: Round number away from zero when halfway.
 
     ```php
-    $value = BigDecimal::from(value: 0.9950, scale: 2);
-
+    $value = BigDecimal::fromFloat(value: 0.9950, scale: 2);
+    
     $result = $value->withRounding(mode: RoundingMode::HALF_UP);
-  
+    
     $result->toString(); # 1
     ```
 
 - `HALF_DOWN`: Round number to zero when halfway.
 
     ```php
-    $value = BigDecimal::from(value: 0.9950, scale: 2);
-
+    $value = BigDecimal::fromFloat(value: 0.9950, scale: 2);
+  
     $result = $value->withRounding(mode: RoundingMode::HALF_DOWN);
 
     $result->toString(); # 0.99
@@ -132,20 +146,20 @@ rounding occurs:
 - `HALF_EVEN`: Round number to the nearest even value when halfway.
 
     ```php
-    $value = BigDecimal::from(value: 0.9950, scale: 2);
-
+    $value = BigDecimal::fromFloat(value: 0.9950, scale: 2);
+  
     $result = $value->withRounding(mode: RoundingMode::HALF_EVEN);
-
+  
     $result->toString(); # 1
     ```
 
 - `HALF_ODD`: Round number to the nearest odd value when halfway.
 
     ```php
-    $value = BigDecimal::from(value: 0.9950, scale: 2);
-
+    $value = BigDecimal::fromFloat(value: 0.9950, scale: 2);
+  
     $result = $value->withRounding(mode: RoundingMode::HALF_ODD);
-
+  
     $result->toString(); # 0.99
     ```
 
@@ -154,7 +168,7 @@ rounding occurs:
 Sometimes it is necessary to convert a value to negative, in these cases you can use the `negate` method.
 
 ```php
-$value = BigDecimal::from(value: 1);
+$value = BigDecimal::fromFloat(value: 1);
 
 $result = $value->negate();
 

composer.json

@@ -44,7 +44,6 @@
     },
     "require": {
         "php": "^8.2",
-        "tiny-blocks/value-object": "^2",
         "ext-bcmath": "*"
     },
     "require-dev": {

src/BigDecimal.php

@@ -4,19 +4,23 @@
 
 namespace TinyBlocks\Math;
 
-use TinyBlocks\Math\Internal\BigNumberAdapter;
+use TinyBlocks\Math\Internal\BigNumberBehavior;
 use TinyBlocks\Math\Internal\Number;
 use TinyBlocks\Math\Internal\Scale;
-use TinyBlocks\Vo\ValueObject;
-use TinyBlocks\Vo\ValueObjectAdapter;
 
-final class BigDecimal extends BigNumberAdapter implements BigNumber, ValueObject
+final class BigDecimal extends BigNumberBehavior implements BigNumber
 {
-    use ValueObjectAdapter;
+    public static function fromFloat(float $value, ?int $scale = BigNumber::AUTOMATIC_SCALE): BigNumber
+    {
+        $scale = Scale::from(value: $scale);
+        $number = Number::from(value: $value);
+
+        return new BigDecimal(number: $number, scale: $scale);
+    }
 
-    public static function from(float|string $value, ?int $scale = BigNumber::AUTOMATIC_SCALE): BigDecimal
+    public static function fromString(string $value, ?int $scale = BigNumber::AUTOMATIC_SCALE): BigNumber
     {
-        $scale = new Scale(value: $scale);
+        $scale = Scale::from(value: $scale);
         $number = Number::from(value: $value);
 
         return new BigDecimal(number: $number, scale: $scale);

src/Internal/BigNumberAdapter.php src/Internal/BigNumberBehavior.phpsrc/Internal/BigNumberAdapter.php renamed to src/Internal/BigNumberBehavior.php

@@ -12,7 +12,7 @@
 use TinyBlocks\Math\Internal\Operations\Rounding\Rounder;
 use TinyBlocks\Math\RoundingMode;
 
-abstract class BigNumberAdapter
+abstract class BigNumberBehavior implements BigNumber
 {
     private MathOperations $mathOperations;
 
@@ -23,27 +23,29 @@ protected function __construct(protected readonly Number $number, protected read
         $this->mathOperations = $operationsFactory->build();
     }
 
-    abstract public static function from(float|string $value, ?int $scale = BigNumber::AUTOMATIC_SCALE): BigNumber;
+    abstract public static function fromFloat(float $value, ?int $scale = BigNumber::AUTOMATIC_SCALE): BigNumber;
+
+    abstract public static function fromString(string $value, ?int $scale = BigNumber::AUTOMATIC_SCALE): BigNumber;
 
     public function add(BigNumber $addend): BigNumber
     {
         $result = $this->mathOperations->add(augend: $this, addend: $addend);
 
-        return $this::from(value: $result->number->value, scale: $result->scale->value);
+        return static::fromString(value: $result->number->value, scale: $result->scale->value);
     }
 
     public function subtract(BigNumber $subtrahend): BigNumber
     {
         $result = $this->mathOperations->subtract(minuend: $this, subtrahend: $subtrahend);
 
-        return $this::from(value: $result->number->value, scale: $result->scale->value);
+        return static::fromString(value: $result->number->value, scale: $result->scale->value);
     }
 
     public function multiply(BigNumber $multiplier): BigNumber
     {
         $result = $this->mathOperations->multiply(multiplicand: $this, multiplier: $multiplier);
 
-        return $this::from(value: $result->number->value, scale: $result->scale->value);
+        return static::fromString(value: $result->number->value, scale: $result->scale->value);
     }
 
     public function divide(BigNumber $divisor): BigNumber
@@ -54,27 +56,27 @@ public function divide(BigNumber $divisor): BigNumber
 
         $result = $this->mathOperations->divide(dividend: $this, divisor: $divisor);
 
-        return $this::from(value: $result->number->value, scale: $result->scale->value);
+        return static::fromString(value: $result->number->value, scale: $result->scale->value);
     }
 
     public function withRounding(RoundingMode $mode): BigNumber
     {
         $rounder = new Rounder(mode: $mode, bigNumber: $this);
         $rounded = $rounder->round();
 
-        return $this::from(value: $rounded->value, scale: $this->scale->value);
+        return static::fromString(value: $rounded->value, scale: $this->scale->value);
     }
 
     public function withScale(int $scale): BigNumber
     {
         $number = $this->scale->numberWithScale(number: $this->number, scale: $scale);
 
-        return $this::from(value: $number->value, scale: $scale);
+        return static::fromString(value: $number->value, scale: $scale);
     }
 
     public function negate(): BigNumber
     {
-        $multiplicand = $this->from(value: -1);
+        $multiplicand = static::fromFloat(value: -1);
 
         return $this->multiply(multiplier: $multiplicand);
     }

src/Internal/Operations/Adapters/Scales/Addition.php

@@ -14,8 +14,8 @@
 
     public function __construct(private BigNumber $augend, private BigNumber $addend)
     {
-        $this->augendScale = new Scale(value: $this->augend->getScale());
-        $this->addendScale = new Scale(value: $this->addend->getScale());
+        $this->augendScale = Scale::from(value: $this->augend->getScale());
+        $this->addendScale = Scale::from(value: $this->addend->getScale());
     }
 
     public function applyScale(): Scale

src/Internal/Operations/Adapters/Scales/Division.php

@@ -14,8 +14,8 @@
 
     public function __construct(private BigNumber $dividend, private BigNumber $divisor)
     {
-        $this->dividendScale = new Scale(value: $this->dividend->getScale());
-        $this->divisorScale = new Scale(value: $this->divisor->getScale());
+        $this->dividendScale = Scale::from(value: $this->dividend->getScale());
+        $this->divisorScale = Scale::from(value: $this->divisor->getScale());
     }
 
     public function applyScale(): Scale

src/Internal/Operations/Adapters/Scales/Multiplication.php

@@ -14,8 +14,8 @@
 
     public function __construct(private BigNumber $multiplicand, private BigNumber $multiplier)
     {
-        $this->multiplicandScale = new Scale(value: $this->multiplicand->getScale());
-        $this->multiplierScale = new Scale(value: $this->multiplier->getScale());
+        $this->multiplicandScale = Scale::from(value: $this->multiplicand->getScale());
+        $this->multiplierScale = Scale::from(value: $this->multiplier->getScale());
     }
 
     public function applyScale(): Scale

src/Internal/Operations/Adapters/Scales/Subtraction.php

@@ -14,8 +14,8 @@
 
     public function __construct(private BigNumber $minuend, private BigNumber $subtrahend)
     {
-        $this->minuendScale = new Scale(value: $this->minuend->getScale());
-        $this->subtrahendScale = new Scale(value: $this->subtrahend->getScale());
+        $this->minuendScale = Scale::from(value: $this->minuend->getScale());
+        $this->subtrahendScale = Scale::from(value: $this->subtrahend->getScale());
     }
 
     public function applyScale(): Scale

src/Internal/Operations/MathOperations.php

@@ -10,30 +10,38 @@
 interface MathOperations
 {
     /**
-     * @param BigNumber $augend
-     * @param BigNumber $addend
-     * @return Result
+     * Performs the addition of two BigNumber instances.
+     *
+     * @param BigNumber $augend The number to which another number (addend) will be added.
+     * @param BigNumber $addend The number to be added to the augend.
+     * @return Result The result of adding augend and addend, encapsulated in a Result object.
      */
     public function add(BigNumber $augend, BigNumber $addend): Result;
 
     /**
-     * @param BigNumber $minuend
-     * @param BigNumber $subtrahend
-     * @return Result
+     * Performs the subtraction of one BigNumber instance from another.
+     *
+     * @param BigNumber $minuend The number from which another number (subtrahend) will be subtracted.
+     * @param BigNumber $subtrahend The number to be subtracted from the minuend.
+     * @return Result The result of subtracting subtrahend from minuend, encapsulated in a Result object.
      */
     public function subtract(BigNumber $minuend, BigNumber $subtrahend): Result;
 
     /**
-     * @param BigNumber $multiplicand
-     * @param BigNumber $multiplier
-     * @return Result
+     * Performs the multiplication of two BigNumber instances.
+     *
+     * @param BigNumber $multiplicand The number to be multiplied.
+     * @param BigNumber $multiplier The number by which the multiplicand will be multiplied.
+     * @return Result The result of multiplying multiplicand and multiplier, encapsulated in a Result object.
      */
     public function multiply(BigNumber $multiplicand, BigNumber $multiplier): Result;
 
     /**
-     * @param BigNumber $dividend
-     * @param BigNumber $divisor
-     * @return Result
+     * Performs the division of one BigNumber instance by another.
+     *
+     * @param BigNumber $dividend The number to be divided.
+     * @param BigNumber $divisor The number by which the dividend will be divided.
+     * @return Result The result of dividing dividend by divisor, encapsulated in a Result object.
      */
     public function divide(BigNumber $dividend, BigNumber $divisor): Result;
 }

src/Internal/Scale.php

@@ -11,14 +11,20 @@ final class Scale
 {
     private const MINIMUM = 0;
     private const MAXIMUM = 2147483647;
+    private const ZERO_DECIMAL_PLACE = 0;
 
-    public function __construct(public readonly ?int $value)
+    private function __construct(public readonly ?int $value)
     {
         if (!$this->hasAutomaticScale() && ($this->value < self::MINIMUM || $this->value > self::MAXIMUM)) {
             throw new InvalidScale(value: $this->value, minimum: self::MINIMUM, maximum: self::MAXIMUM);
         }
     }
 
+    public static function from(?int $value): Scale
+    {
+        return new Scale(value: $value);
+    }
+
     public function scaleOf(string $value): Scale
     {
         $number = Number::from(value: $value);
@@ -41,7 +47,7 @@ public function numberWithScale(Number $number, int $scale): Number
         }
 
         $decimal = $result[0];
-        $decimalPlaces = substr($result[1], 0, $scale);
+        $decimalPlaces = substr($result[1], self::ZERO_DECIMAL_PLACE, $scale);
 
         $template = '%s.%s';
         $value = sprintf($template, $decimal, $decimalPlaces);