feat: narrow types (#108)

Author: simPod

src/BigDecimal.php

@@ -242,7 +242,7 @@ public function multipliedBy(BigNumber|int|string $that): BigDecimal
      * Returns the result of the division of this number by the given one, at the given scale.
      *
      * @param BigNumber|int|string $that         The divisor. Must be convertible to a BigDecimal.
-     * @param int                  $scale        The desired scale. Must be non-negative.
+     * @param non-negative-int     $scale        The desired scale. Must be non-negative.
      * @param RoundingMode         $roundingMode An optional rounding mode, defaults to Unnecessary.
      *
      * @throws MathException              If the divisor is not valid, or is not convertible to a BigDecimal.
@@ -255,7 +255,7 @@ public function multipliedBy(BigNumber|int|string $that): BigDecimal
      */
     public function dividedBy(BigNumber|int|string $that, int $scale, RoundingMode $roundingMode = RoundingMode::Unnecessary): BigDecimal
     {
-        if ($scale < 0) {
+        if ($scale < 0) { // @phpstan-ignore smaller.alwaysFalse
             throw InvalidArgumentException::negativeScale();
         }
 
@@ -331,6 +331,8 @@ public function dividedByExact(BigNumber|int|string $that): BigDecimal
      *
      * The result has a scale of `$this->scale * $exponent`.
      *
+     * @param non-negative-int $exponent
+     *
      * @throws InvalidArgumentException If the exponent is negative.
      *
      * @pure
@@ -345,7 +347,7 @@ public function power(int $exponent): BigDecimal
             return $this;
         }
 
-        if ($exponent < 0) {
+        if ($exponent < 0) { // @phpstan-ignore smaller.alwaysFalse
             throw InvalidArgumentException::negativeExponent();
         }
 
@@ -470,8 +472,8 @@ public function quotientAndRemainder(BigNumber|int|string $that): array
     /**
      * Returns the square root of this number, rounded to the given scale according to the given rounding mode.
      *
-     * @param int          $scale        The target scale. Must be non-negative.
-     * @param RoundingMode $roundingMode An optional rounding mode, defaults to Unnecessary.
+     * @param non-negative-int $scale        The target scale. Must be non-negative.
+     * @param RoundingMode     $roundingMode An optional rounding mode, defaults to Unnecessary.
      *
      * @throws InvalidArgumentException   If the scale is negative.
      * @throws NegativeNumberException    If this number is negative.
@@ -482,7 +484,7 @@ public function quotientAndRemainder(BigNumber|int|string $that): array
      */
     public function sqrt(int $scale, RoundingMode $roundingMode = RoundingMode::Unnecessary): BigDecimal
     {
-        if ($scale < 0) {
+        if ($scale < 0) { // @phpstan-ignore smaller.alwaysFalse
             throw InvalidArgumentException::negativeScale();
         }
 
@@ -731,7 +733,7 @@ public function toBigRational(): BigRational
     #[Override]
     public function toScale(int $scale, RoundingMode $roundingMode = RoundingMode::Unnecessary): BigDecimal
     {
-        if ($scale < 0) {
+        if ($scale < 0) { // @phpstan-ignore smaller.alwaysFalse
             throw InvalidArgumentException::negativeScale();
         }
 

src/BigInteger.php

@@ -78,8 +78,8 @@ protected function __construct(string $value)
      *
      * For bases greater than 36, and/or custom alphabets, use the fromArbitraryBase() method.
      *
-     * @param string $number The number to convert, in the given base.
-     * @param int    $base   The base of the number, between 2 and 36.
+     * @param string     $number The number to convert, in the given base.
+     * @param int<2, 36> $base   The base of the number, between 2 and 36.
      *
      * @throws NumberFormatException    If the number is empty, or contains invalid chars for the given base.
      * @throws InvalidArgumentException If the base is out of range.
@@ -88,7 +88,7 @@ protected function __construct(string $value)
      */
     public static function fromBase(string $number, int $base): BigInteger
     {
-        if ($base < 2 || $base > 36) {
+        if ($base < 2 || $base > 36) { // @phpstan-ignore smaller.alwaysFalse, greater.alwaysFalse, booleanOr.alwaysFalse
             throw InvalidArgumentException::baseOutOfRange($base);
         }
 
@@ -232,7 +232,7 @@ public static function fromBytes(string $value, bool $signed = true): BigInteger
      *
      * Using the default random bytes generator, this method is suitable for cryptographic use.
      *
-     * @param int                          $bitCount             The number of bits.
+     * @param non-negative-int             $bitCount             The number of bits.
      * @param (callable(int): string)|null $randomBytesGenerator A function that accepts a number of bytes, and returns
      *                                                           a string of random bytes of the given length. Defaults
      *                                                           to the `random_bytes()` function.
@@ -242,7 +242,7 @@ public static function fromBytes(string $value, bool $signed = true): BigInteger
      */
     public static function randomBits(int $bitCount, ?callable $randomBytesGenerator = null): BigInteger
     {
-        if ($bitCount < 0) {
+        if ($bitCount < 0) { // @phpstan-ignore smaller.alwaysFalse
             throw InvalidArgumentException::negativeBitCount();
         }
 
@@ -527,6 +527,8 @@ public function dividedBy(BigNumber|int|string $that, RoundingMode $roundingMode
     /**
      * Returns this number exponentiated to the given value.
      *
+     * @param non-negative-int $exponent
+     *
      * @throws InvalidArgumentException If the exponent is negative.
      *
      * @pure
@@ -541,7 +543,7 @@ public function power(int $exponent): BigInteger
             return $this;
         }
 
-        if ($exponent < 0) {
+        if ($exponent < 0) { // @phpstan-ignore smaller.alwaysFalse
             throw InvalidArgumentException::negativeExponent();
         }
 
@@ -1004,6 +1006,8 @@ public function shiftedRight(int $bits): BigInteger
      * For positive BigIntegers, this is equivalent to the number of bits in the ordinary binary representation.
      * Computes (ceil(log2(this < 0 ? -this : this+1))).
      *
+     * @return non-negative-int
+     *
      * @pure
      */
     public function getBitLength(): int
@@ -1047,15 +1051,15 @@ public function getLowestSetBit(): int
      *
      * Computes ((this & (1<<bitIndex)) != 0).
      *
-     * @param int $bitIndex The bit to test, 0-based.
+     * @param non-negative-int $bitIndex The bit to test, 0-based.
      *
      * @throws InvalidArgumentException If the bit to test is negative.
      *
      * @pure
      */
     public function isBitSet(int $bitIndex): bool
     {
-        if ($bitIndex < 0) {
+        if ($bitIndex < 0) { // @phpstan-ignore smaller.alwaysFalse
             throw InvalidArgumentException::negativeBitIndex();
         }
 
@@ -1147,6 +1151,8 @@ public function toFloat(): float
      *
      * The output will always be lowercase for bases greater than 10.
      *
+     * @param int<2, 36> $base
+     *
      * @throws InvalidArgumentException If the base is out of range.
      *
      * @pure
@@ -1157,7 +1163,7 @@ public function toBase(int $base): string
             return $this->value;
         }
 
-        if ($base < 2 || $base > 36) {
+        if ($base < 2 || $base > 36) { // @phpstan-ignore smaller.alwaysFalse, greater.alwaysFalse, booleanOr.alwaysFalse
             throw InvalidArgumentException::baseOutOfRange($base);
         }
 

src/BigNumber.php

@@ -425,8 +425,8 @@ abstract public function toBigRational(): BigRational;
     /**
      * Converts this number to a BigDecimal with the given scale, using rounding if necessary.
      *
-     * @param int          $scale        The scale of the resulting `BigDecimal`. Must be non-negative.
-     * @param RoundingMode $roundingMode An optional rounding mode, defaults to Unnecessary.
+     * @param non-negative-int $scale        The scale of the resulting `BigDecimal`. Must be non-negative.
+     * @param RoundingMode     $roundingMode An optional rounding mode, defaults to Unnecessary.
      *
      * @throws InvalidArgumentException   If the scale is negative.
      * @throws RoundingNecessaryException If RoundingMode::Unnecessary is used, and this number cannot be converted to

src/BigRational.php

@@ -426,7 +426,7 @@ public function toBigRational(): BigRational
     #[Override]
     public function toScale(int $scale, RoundingMode $roundingMode = RoundingMode::Unnecessary): BigDecimal
     {
-        if ($scale < 0) {
+        if ($scale < 0) { // @phpstan-ignore smaller.alwaysFalse
             throw InvalidArgumentException::negativeScale();
         }
 

src/Internal/DecimalHelper.php

@@ -33,13 +33,17 @@ private function __construct()
      *
      * @param string $denominator The denominator of the reduced fraction. Must be strictly positive.
      *
+     * @return non-negative-int|null
+     *
      * @pure
      */
     public static function computeScaleFromReducedFractionDenominator(string $denominator): ?int
     {
         $calculator = CalculatorRegistry::get();
 
         $d = rtrim($denominator, '0');
+
+        /** @var non-negative-int $scale rtrim can only shorten a string */
         $scale = strlen($denominator) - strlen($d);
 
         foreach ([5, 2] as $prime) {