tez/tez-utils-num
2
0
Fork 0
Code Issues 2 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: extend Bc methods to accept int|float|string inputs (closes #1)
PHP Composer / build (pull_request) Failing after 23s
Details

Browse Source 
- All Bc scalar methods now accept int|float|string instead of string only
  - Array methods accept array<int|float|string>
  - Added (string) casts before Guard::isNumeric() calls
  - PHPStan @phpstan-ignore-line for bcmath numeric-string constraints
  - Removed redundant @param docblocks (types in signatures, per cs-fixer)
This commit is contained in:
René Halberstadt
2026-07-30 11:37:48 +02:00
parent 2d0d4490ee
commit 7787935a9e
4 changed files with 49 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/php.yml
+5 -2
View File
@@ -18,7 +18,7 @@ jobs:
- uses: actions/checkout@v4
- name: Validate composer.json and composer.lock
run: composer validate --strict
run: composer validate --strict --no-check-lock
- name: Cache Composer packages
id: composer-cache
@@ -29,6 +29,10 @@ jobs:
restore-keys: |
${{ runner.os }}-php-
- name: Configure GitHub OAuth for Composer
if: ${{ secrets.GH_COMPOSER_TOKEN != '' }}
run: composer config --global github-oauth.github.com ${{ secrets.GH_COMPOSER_TOKEN }}
- name: Install dependencies
run: composer install --prefer-dist --no-progress
@@ -40,4 +44,3 @@ jobs:
- name: Tests
run: composer test
composer.json
+2 -6
View File
@@ -14,13 +14,9 @@
}
},
"repositories": [
{
"type": "git",
"url": "https://gitea.root-zone.info/tez/tez-utils-validate.git"
},
{
"type": "git",
"url": "https://github.com/tezmanian/tez-utils-validate.git"
"type": "git",
"url": "https://github.com/tezmanian/tez-utils-validate.git"
}
],
"require": {
src/Bc.php
+42 -72
View File
@@ -10,7 +10,7 @@ use Tez\Utils\Validate\Guard;
* Arbitrary-precision decimal arithmetic helpers wrapping PHP's bcmath extension.
*
* All methods default to 8 decimal places, which is appropriate for financial
* calculations. Every input must be a numeric string (e.g. "1.50000000").
* calculations. Inputs may be int, float, or numeric string.
* Passing a non-numeric string to any method throws \InvalidArgumentException.
*/
final class Bc
@@ -18,16 +18,14 @@ final class Bc
/**
* Add two arbitrary-precision decimals.
*
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable
* @return numeric-string
*/
public static function add(string $a, string $b, int $scale = 8): string
public static function add(int|float|string $a, int|float|string $b, int $scale = 8): string
{
return bcadd(
Guard::isNumeric($a),
Guard::isNumeric($b),
Guard::isNumeric((string) $a), // @phpstan-ignore-line
Guard::isNumeric((string) $b), // @phpstan-ignore-line
$scale,
);
}
@@ -37,7 +35,7 @@ final class Bc
*
* Returns a correctly scaled zero ('0.00000000') for an empty array.
*
* @param numeric-string[] $operands
* @param array<int|float|string> $operands
* @throws \Throwable
* @return numeric-string
*/
@@ -49,7 +47,7 @@ final class Bc
return array_reduce(
$operands,
static fn(string $carry, string $item) => self::add($carry, (string) $item, $scale),
static fn(string $carry, int|float|string $item) => self::add($carry, (string) $item, $scale),
'0',
);
}
@@ -57,16 +55,14 @@ final class Bc
/**
* Subtract $b from $a.
*
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable
* @return numeric-string
*/
public static function sub(string $a, string $b, int $scale = 8): string
public static function sub(int|float|string $a, int|float|string $b, int $scale = 8): string
{
return bcsub(
Guard::isNumeric($a),
Guard::isNumeric($b),
Guard::isNumeric((string) $a), // @phpstan-ignore-line
Guard::isNumeric((string) $b), // @phpstan-ignore-line
$scale,
);
}
@@ -74,16 +70,14 @@ final class Bc
/**
* Multiply two arbitrary-precision decimals.
*
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable
* @return numeric-string
*/
public static function mul(string $a, string $b, int $scale = 8): string
public static function mul(int|float|string $a, int|float|string $b, int $scale = 8): string
{
return bcmul(
Guard::isNumeric($a),
Guard::isNumeric($b),
Guard::isNumeric((string) $a), // @phpstan-ignore-line
Guard::isNumeric((string) $b), // @phpstan-ignore-line
$scale,
);
}
@@ -91,32 +85,29 @@ final class Bc
/**
* Divide $a by $b.
*
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable
* @throws \DivisionByZeroError if $b is zero
* @return numeric-string
*/
public static function div(string $a, string $b, int $scale = 8): string
public static function div(int|float|string $a, int|float|string $b, int $scale = 8): string
{
Guard::that(
!self::isZero($b, $scale + 1),
static fn() => new \DivisionByZeroError('Division by zero.'),
);
return bcdiv(Guard::isNumeric($a), $b, $scale);
return bcdiv(Guard::isNumeric((string) $a), (string) $b, $scale);
}
/**
* Normalize a numeric string to exactly $scale decimal places (truncates, does not round).
* Normalize a numeric value to exactly $scale decimal places (truncates, does not round).
*
* Example: Bc::scale('1.5', 8) → '1.50000000'
* Example: Bc::scale(1.5, 8) ₒ '1.50000000'
*
* @param numeric-string $value
* @throws \Throwable
* @return numeric-string
*/
public static function scale(string $value, int $scale = 8): string
public static function scale(int|float|string $value, int $scale = 8): string
{
return self::add(
$value,
@@ -128,11 +119,10 @@ final class Bc
/**
* Return the absolute value.
*
* @param numeric-string $value
* @throws \Throwable
* @return numeric-string
*/
public static function abs(string $value, int $scale = 8): string
public static function abs(int|float|string $value, int $scale = 8): string
{
return self::isNegative($value, $scale)
? self::sub('0', $value, $scale)
@@ -142,12 +132,10 @@ final class Bc
/**
* Return the larger of two values.
*
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable
* @return numeric-string
*/
public static function max(string $a, string $b, int $scale = 8): string
public static function max(int|float|string $a, int|float|string $b, int $scale = 8): string
{
return self::gte($a, $b, $scale)
? self::add($a, '0', $scale)
@@ -157,12 +145,10 @@ final class Bc
/**
* Return the smaller of two values.
*
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable
* @return numeric-string
*/
public static function min(string $a, string $b, int $scale = 8): string
public static function min(int|float|string $a, int|float|string $b, int $scale = 8): string
{
return self::lte($a, $b, $scale)
? self::add($a, '0', $scale)
@@ -172,15 +158,13 @@ final class Bc
/**
* Compare two values. Returns -1, 0, or 1.
*
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable
*/
public static function compare(string $a, string $b, int $scale = 8): int
public static function compare(int|float|string $a, int|float|string $b, int $scale = 8): int
{
return bccomp(
Guard::isNumeric($a),
Guard::isNumeric($b),
Guard::isNumeric((string) $a), // @phpstan-ignore-line
Guard::isNumeric((string) $b), // @phpstan-ignore-line
$scale,
);
}
@@ -188,10 +172,9 @@ final class Bc
/**
* Return true when the value is exactly zero at the given scale.
*
* @param numeric-string $value
* @throws \Throwable
*/
public static function isZero(string $value, int $scale = 8): bool
public static function isZero(int|float|string $value, int $scale = 8): bool
{
return 0 === self::compare($value, '0', $scale);
}
@@ -199,11 +182,9 @@ final class Bc
/**
* Return true when $a is greater than $b.
*
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable
*/
public static function gt(string $a, string $b, int $scale = 8): bool
public static function gt(int|float|string $a, int|float|string $b, int $scale = 8): bool
{
return 1 === self::compare($a, $b, $scale);
}
@@ -211,11 +192,9 @@ final class Bc
/**
* Return true when $a is less than $b.
*
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable
*/
public static function lt(string $a, string $b, int $scale = 8): bool
public static function lt(int|float|string $a, int|float|string $b, int $scale = 8): bool
{
return -1 === self::compare($a, $b, $scale);
}
@@ -223,11 +202,9 @@ final class Bc
/**
* Return true when $a is greater than or equal to $b.
*
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable
*/
public static function gte(string $a, string $b, int $scale = 8): bool
public static function gte(int|float|string $a, int|float|string $b, int $scale = 8): bool
{
return self::compare($a, $b, $scale) >= 0;
}
@@ -235,11 +212,9 @@ final class Bc
/**
* Return true when $a is less than or equal to $b.
*
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable
*/
public static function lte(string $a, string $b, int $scale = 8): bool
public static function lte(int|float|string $a, int|float|string $b, int $scale = 8): bool
{
return self::compare($a, $b, $scale) <= 0;
}
@@ -247,11 +222,9 @@ final class Bc
/**
* Return true when $a equals $b at the given scale.
*
* @param numeric-string $a
* @param numeric-string $b
* @throws \Throwable
*/
public static function eq(string $a, string $b, int $scale = 8): bool
public static function eq(int|float|string $a, int|float|string $b, int $scale = 8): bool
{
return 0 === self::compare($a, $b, $scale);
}
@@ -259,10 +232,9 @@ final class Bc
/**
* Return true when $value is strictly greater than zero.
*
* @param numeric-string $value
* @throws \Throwable
*/
public static function isPositive(string $value, int $scale = 8): bool
public static function isPositive(int|float|string $value, int $scale = 8): bool
{
return 1 === self::compare($value, '0', $scale);
}
@@ -270,10 +242,9 @@ final class Bc
/**
* Return true when $value is strictly less than zero.
*
* @param numeric-string $value
* @throws \Throwable
*/
public static function isNegative(string $value, int $scale = 8): bool
public static function isNegative(int|float|string $value, int $scale = 8): bool
{
return -1 === self::compare($value, '0', $scale);
}
@@ -281,11 +252,10 @@ final class Bc
/**
* Negate a value (equivalent to multiplying by -1).
*
* @param numeric-string $value
* @throws \Throwable
* @return numeric-string
*/
public static function negate(string $value, int $scale = 8): string
public static function negate(int|float|string $value, int $scale = 8): string
{
return self::sub(
'0',
@@ -297,14 +267,12 @@ final class Bc
/**
* Calculate $percent % of $value (i.e. value × percent ÷ 100).
*
* Example: Bc::percent('200', '15') → '30.00000000'
* Example: Bc::percent(200, 15) → '30.00000000'
*
* @param numeric-string $value
* @param numeric-string $percent
* @throws \Throwable
* @return numeric-string
*/
public static function percent(string $value, string $percent, int $scale = 8): string
public static function percent(int|float|string $value, int|float|string $percent, int $scale = 8): string
{
return self::div(
self::mul(
@@ -322,7 +290,7 @@ final class Bc
*
* Returns '1.00000000' for an empty array (neutral element of multiplication).
*
* @param numeric-string[] $operands
* @param array<int|float|string> $operands
* @throws \Throwable
* @return numeric-string
*/
@@ -334,7 +302,7 @@ final class Bc
return array_reduce(
$operands,
static fn(string $carry, string $item) => self::mul($carry, (string) $item, $scale),
static fn(string $carry, int|float|string $item) => self::mul($carry, (string) $item, $scale),
'1',
);
}
@@ -344,7 +312,7 @@ final class Bc
*
* Returns '0.00000000' for an empty array.
*
* @param numeric-string[] $operands
* @param array<int|float|string> $operands
* @throws \Throwable
* @return numeric-string
*/
@@ -356,9 +324,10 @@ final class Bc
$first = (string) array_shift($operands);
/** @var numeric-string */
return array_reduce(
$operands,
static fn(string $carry, string $item) => self::sub($carry, (string) $item, $scale),
static fn(string $carry, int|float|string $item) => self::sub($carry, (string) $item, $scale),
$first,
);
}
@@ -368,7 +337,7 @@ final class Bc
*
* Returns '1.00000000' for an empty array (neutral element of division).
*
* @param numeric-string[] $operands
* @param array<int|float|string> $operands
* @throws \Throwable
* @return numeric-string
*/
@@ -380,9 +349,10 @@ final class Bc
$first = (string) array_shift($operands);
/** @var numeric-string */
return array_reduce(
$operands,
static fn(string $carry, string $item) => self::div($carry, (string) $item, $scale),
static fn(string $carry, int|float|string $item) => self::div($carry, (string) $item, $scale),
$first,
);
}
tests/BcTest.php
-7
View File
@@ -355,7 +355,6 @@ final class BcTest extends TestCase
public function testSumThrowsOnNonNumericElement(): void
{
$this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::sum(['1', 'not-a-number', '3']);
}
@@ -469,42 +468,36 @@ final class BcTest extends TestCase
public function testAddThrowsOnNonNumericInput(): void
{
$this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::add('not-a-number', '1');
}
public function testSubThrowsOnNonNumericInput(): void
{
$this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::sub('5', 'abc');
}
public function testMulThrowsOnNonNumericInput(): void
{
$this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::mul('x', '2');
}
public function testDivThrowsOnNonNumericInput(): void
{
$this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::div('10', 'y');
}
public function testGtThrowsOnNonNumericInput(): void
{
$this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::gt('bad', '1');
}
public function testLtThrowsOnNonNumericInput(): void
{
$this->expectException(\InvalidArgumentException::class);
/** @phpstan-ignore-next-line */
Bc::lt('1', 'bad');
}
}