Add min, max and clamp (#14)

* Add min / max / clamp methods

* Add tests for min / max / clamp

* Add phpro/grumphp to allow-plugins

* Update php-cs-fixer workflow

* Update php-cs-fixer workflow

* Improve Github workflow

* Update composer.json

* Add documentation to README.md about min, max and clamp

* Improve testClamp

Author: bobmulder

.github/workflows/php-cs-fixer.yml

@@ -8,15 +8,17 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           ref: ${{ github.head_ref }}
 
       - name: Run composer install
         run: composer install -n --prefer-dist
 
       - name: Run PHP CS Fixer
-        run: composer format
+          uses: docker://oskarstark/php-cs-fixer-ga
+          with:
+            args: --config=.php-cs-fixer.dist.php --allow-risky=yes
 
       - name: Commit changes
         uses: stefanzweifel/git-auto-commit-action@v4

.github/workflows/run-tests.yml

@@ -32,7 +32,7 @@ jobs:
           coverage: none
 
       - name: Install dependencies
-        run: composer update --${{ matrix.dependency-version }} --prefer-dist --no-interaction --no-suggest
+        run: composer update --${{ matrix.dependency-version }} --prefer-dist --no-interaction
 
       - name: Execute tests
         run: vendor/bin/phpunit

README.md

@@ -40,6 +40,7 @@ to the desired needs of your business.
     - [Modulus](#modulus)
     - [State & Comparison](#state--comparison)
     - [Absolute & opposite values](#absolute--opposite-values)
+    - [Limiting values](#limiting-values)
     - [Rounding](#rounding)
     - [Immutable & Chaining](#immutable--chaining)
     - [Extensibility](#extensibility)
@@ -191,6 +192,28 @@ $absolute = $number->opposite();
 $abs = $number->opp();
 ```
 
+### Limiting values
+To make sure the current number is not higher or lower than expected:
+
+```php
+$number = new Number('200');
+
+// $result will be 250
+$result = $number->min('250');
+
+// $result will be 100
+$result = $number->max('100');
+```
+
+To use a min and max 'clamp' at the same time:
+
+```php
+$number = new Number('200');
+
+// $result will be 150
+$result = $number->clamp('100', '150');
+```
+
 ### Rounding
 To round the current number instance, the following methods are available:
 

composer.json

@@ -43,7 +43,11 @@
         "format": "vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.dist.php --allow-risky=yes"
     },
     "config": {
-        "sort-packages": true
+        "sort-packages": true,
+        "allow-plugins": {
+            "phpro/grumphp": true,
+            "ocramius/package-versions": true
+        }
     },
     "minimum-stability": "dev",
     "prefer-stable": true

src/AbstractNumber.php

@@ -298,6 +298,54 @@ public function opp(): self
         return $this->opposite();
     }
 
+    /**
+     * Prevent the current value to be less than the given value.
+     *
+     * @param AbstractNumber|string|float|int $value
+     */
+    public function min($value = null): self
+    {
+        $value = $this->getNumberFromInput($value);
+
+        if ($this->isLessThan($value)) {
+            return $this->init((string) $value);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Prevent the current value to be more than the given value.
+     *
+     * @param AbstractNumber|string|float|int $value
+     */
+    public function max($value = null): self
+    {
+        $value = $this->getNumberFromInput($value);
+
+        if ($this->isGreaterThan($value)) {
+            return $this->init((string) $value);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Put a clamp on the current value.
+     *
+     * @param AbstractNumber|string|float|int $min
+     * @param AbstractNumber|string|float|int $max
+     */
+    public function clamp($min, $max): self
+    {
+        $result = $this;
+
+        $result = $result->min($min);
+        $result = $result->max($max);
+
+        return $this->init((string) $result);
+    }
+
     /**
      * Return boolean if the current value is a positive number.
      */

tests/NumberTest.php

@@ -488,6 +488,34 @@ public function testOpposite()
         $this->assertEquals('-0.3000', Number::create('0.3000')->opposite()->toString());
     }
 
+    public function testMin()
+    {
+        $number = new Number('200');
+
+        $this->assertEquals('200.000', $number->min('200'));
+        $this->assertEquals('200.000', $number->min('150'));
+        $this->assertEquals('250.000', $number->min('250'));
+    }
+
+    public function testMax()
+    {
+        $number = new Number('200');
+
+        $this->assertEquals('200.000', $number->max('200'));
+        $this->assertEquals('150.000', $number->max('150'));
+        $this->assertEquals('200.000', $number->max('250'));
+    }
+
+    public function testClamp()
+    {
+        $number = new Number('200');
+
+        $this->assertEquals('200.000', $number->clamp('100', '200'));
+        $this->assertEquals('200.000', $number->clamp('100', '300'));
+        $this->assertEquals('100.000', $number->clamp('50', '100'));
+        $this->assertEquals('250.000', $number->clamp('250', '300'));
+    }
+
     public function testIsPositive(): void
     {
         $this->assertTrue((new Number('200'))->isPositive());