Skip to content

Commit 4f5b0d3

Browse files
BenMorelBenMorel
committed
wip
1 parent 3bc9b75 commit 4f5b0d3

File tree

4 files changed

+114
-38
lines changed

4 files changed

+114
-38
lines changed

‎src/BigDecimal.php‎

Lines changed: 28 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -142,13 +142,13 @@ public static function ten() : BigDecimal
142142
/**
143143
* Returns the sum of this number and the given one.
144144
*
145-
* The result has a scale of `max($this->scale, $that->scale)`.
145+
* The operand must be convertible to a BigDecimal.
146+
* The result is a BigDecimal with a scale of `max($this->scale, $that->scale)`.
146147
*
147-
* @param BigNumber|int|float|string $that The number to add. Must be convertible to a BigDecimal.
148-
*
149-
* @throws MathException If the number is not valid, or is not convertible to a BigDecimal.
148+
* @throws MathException If the operand is not a valid number or is not convertible to a BigDecimal.
150149
*/
151-
public function plus(BigNumber|int|float|string $that) : BigDecimal
150+
#[Override]
151+
public function plus(BigNumber|int|float|string $that) : static
152152
{
153153
$that = BigDecimal::of($that);
154154

@@ -171,13 +171,13 @@ public function plus(BigNumber|int|float|string $that) : BigDecimal
171171
/**
172172
* Returns the difference of this number and the given one.
173173
*
174-
* The result has a scale of `max($this->scale, $that->scale)`.
175-
*
176-
* @param BigNumber|int|float|string $that The number to subtract. Must be convertible to a BigDecimal.
174+
* The operand must be convertible to a BigDecimal.
175+
* The result is a BigDecimal with a scale of `max($this->scale, $that->scale)`.
177176
*
178-
* @throws MathException If the number is not valid, or is not convertible to a BigDecimal.
177+
* @throws MathException If the operand is not a valid number or is not convertible to a BigDecimal.
179178
*/
180-
public function minus(BigNumber|int|float|string $that) : BigDecimal
179+
#[Override]
180+
public function minus(BigNumber|int|float|string $that) : static
181181
{
182182
$that = BigDecimal::of($that);
183183

@@ -196,13 +196,13 @@ public function minus(BigNumber|int|float|string $that) : BigDecimal
196196
/**
197197
* Returns the product of this number and the given one.
198198
*
199-
* The result has a scale of `$this->scale + $that->scale`.
200-
*
201-
* @param BigNumber|int|float|string $that The multiplier. Must be convertible to a BigDecimal.
199+
* The operand must be convertible to a BigDecimal.
200+
* The result is a BigDecimal with a scale of `$this->scale + $that->scale`.
202201
*
203-
* @throws MathException If the multiplier is not a valid number, or is not convertible to a BigDecimal.
202+
* @throws MathException If the operand is not a valid number or is not convertible to a BigInteger.
204203
*/
205-
public function multipliedBy(BigNumber|int|float|string $that) : BigDecimal
204+
#[Override]
205+
public function multipliedBy(BigNumber|int|float|string $that) : static
206206
{
207207
$that = BigDecimal::of($that);
208208

@@ -223,14 +223,23 @@ public function multipliedBy(BigNumber|int|float|string $that) : BigDecimal
223223
/**
224224
* Returns the result of the division of this number by the given one, at the given scale.
225225
*
226+
* The operand must be convertible to a BigDecimal.
227+
* The result is a BigDecimal, which by default has the same scale as this number.
228+
* The `$scale` parameter can be used to change the scale of the result.
229+
*
230+
* By default, this method performs an exact division and throws an exception if rounding is necessary.
231+
* The `$roundingMode` parameter can be used to change this behavior.
232+
*
226233
* @param BigNumber|int|float|string $that The divisor.
227234
* @param int|null $scale The desired scale, or null to use the scale of this number.
228-
* @param RoundingMode $roundingMode An optional rounding mode, defaults to UNNECESSARY.
235+
* @param RoundingMode $roundingMode An optional rounding mode, defaults to `UNNECESSARY`.
229236
*
230-
* @throws \InvalidArgumentException If the scale or rounding mode is invalid.
231-
* @throws MathException If the number is invalid, is zero, or rounding was necessary.
237+
* @throws \InvalidArgumentException If the scale is negative.
238+
* @throws MathException If the operand is not a valid number, is not convertible to a BigDecimal, is
239+
* zero, or rounding is necessary but `RoundingMode::UNNECESSARY` was provided.
232240
*/
233-
public function dividedBy(BigNumber|int|float|string $that, ?int $scale = null, RoundingMode $roundingMode = RoundingMode::UNNECESSARY) : BigDecimal
241+
#[Override]
242+
public function dividedBy(BigNumber|int|float|string $that, ?int $scale = null, RoundingMode $roundingMode = RoundingMode::UNNECESSARY) : static
234243
{
235244
$that = BigDecimal::of($that);
236245

‎src/BigInteger.php‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -361,9 +361,12 @@ public static function gcdMultiple(BigInteger $a, BigInteger ...$n): BigInteger
361361
*
362362
* @param BigNumber|int|float|string $that The number to add. Must be convertible to a BigInteger.
363363
*
364-
* @throws MathException If the number is not valid, or is not convertible to a BigInteger.
364+
* @return static The sum, as a BigInteger.
365+
*
366+
* @throws MathException If the operand is not a valid number or is not convertible to a BigInteger.
365367
*/
366-
public function plus(BigNumber|int|float|string $that) : BigInteger
368+
#[Override]
369+
public function plus(BigNumber|int|float|string $that) : static
367370
{
368371
$that = BigInteger::of($that);
369372

@@ -385,9 +388,12 @@ public function plus(BigNumber|int|float|string $that) : BigInteger
385388
*
386389
* @param BigNumber|int|float|string $that The number to subtract. Must be convertible to a BigInteger.
387390
*
388-
* @throws MathException If the number is not valid, or is not convertible to a BigInteger.
391+
* @return static The difference, as a BigInteger.
392+
*
393+
* @throws MathException If the operand is not a valid number or is not convertible to a BigInteger.
389394
*/
390-
public function minus(BigNumber|int|float|string $that) : BigInteger
395+
#[Override]
396+
public function minus(BigNumber|int|float|string $that) : static
391397
{
392398
$that = BigInteger::of($that);
393399

@@ -405,9 +411,12 @@ public function minus(BigNumber|int|float|string $that) : BigInteger
405411
*
406412
* @param BigNumber|int|float|string $that The multiplier. Must be convertible to a BigInteger.
407413
*
408-
* @throws MathException If the multiplier is not a valid number, or is not convertible to a BigInteger.
414+
* @return static The product, as a BigInteger.
415+
*
416+
* @throws MathException If the multiplier is not a valid number or is not convertible to a BigInteger.
409417
*/
410-
public function multipliedBy(BigNumber|int|float|string $that) : BigInteger
418+
#[Override]
419+
public function multipliedBy(BigNumber|int|float|string $that) : static
411420
{
412421
$that = BigInteger::of($that);
413422

@@ -428,12 +437,13 @@ public function multipliedBy(BigNumber|int|float|string $that) : BigInteger
428437
* Returns the result of the division of this number by the given one.
429438
*
430439
* @param BigNumber|int|float|string $that The divisor. Must be convertible to a BigInteger.
431-
* @param RoundingMode $roundingMode An optional rounding mode, defaults to UNNECESSARY.
440+
* @param RoundingMode $roundingMode An optional rounding mode, defaults to `UNNECESSARY`.
432441
*
433442
* @throws MathException If the divisor is not a valid number, is not convertible to a BigInteger, is zero,
434-
* or RoundingMode::UNNECESSARY is used and the remainder is not zero.
443+
* or rounding is necessary but `RoundingMode::UNNECESSARY` was provided.
435444
*/
436-
public function dividedBy(BigNumber|int|float|string $that, RoundingMode $roundingMode = RoundingMode::UNNECESSARY) : BigInteger
445+
#[Override]
446+
public function dividedBy(BigNumber|int|float|string $that, RoundingMode $roundingMode = RoundingMode::UNNECESSARY) : static
437447
{
438448
$that = BigInteger::of($that);
439449

‎src/BigNumber.php‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -348,6 +348,59 @@ private static function cleanUp(string|null $sign, string $number) : string
348348
return $sign === '-' ? '-' . $number : $number;
349349
}
350350

351+
/**
352+
* Returns the sum of this number and the given one.
353+
*
354+
* The operand must be convertible to an instance of the class this method is called on.
355+
* The result is of the same type as the class this method is called on.
356+
*
357+
* @param BigNumber|int|float|string $that The number to add.
358+
*
359+
* @return static The sum.
360+
*
361+
* @throws MathException If the operand is not a valid number or is not convertible to an instance of the class
362+
* this method is called on.
363+
*/
364+
abstract public function plus(BigNumber|int|float|string $that) : static;
365+
366+
/**
367+
* Returns the difference of this number and the given one.
368+
*
369+
* The operand must be convertible to an instance of the class this method is called on.
370+
* The result is of the same type as the class this method is called on.
371+
*
372+
* @throws MathException If the operand is not a valid number or is not convertible to an instance of the class
373+
* this method is called on.
374+
*/
375+
abstract public function minus(BigNumber|int|float|string $that) : static;
376+
377+
/**
378+
* Returns the product of this number and the given one.
379+
*
380+
* The operand must be convertible to an instance of the class this method is called on.
381+
* The result is of the same type as the class this method is called on.
382+
*
383+
* @throws MathException If the operand is not a valid number or is not convertible to an instance of the class
384+
* this method is called on.
385+
*/
386+
abstract public function multipliedBy(BigNumber|int|float|string $that) : static;
387+
388+
/**
389+
* Returns the result of the division of this number by the given one.
390+
*
391+
* The operand must be convertible to an instance of the class this method is called on.
392+
* The result is of the same type as the class this method is called on.
393+
*
394+
* By default, this method performs an exact division and throws an exception if rounding is necessary.
395+
* Where relevant, subclasses provide optional parameters to control the rounding behavior:
396+
* - BigInteger has optional rounding mode
397+
* - BigDecimal has optional scale and rounding mode
398+
*
399+
* @throws MathException If the operand is not a valid number, is not convertible to an instance of the class this
400+
* method is called on, is zero, or rounding is necessary but no rounding mode was provided.
401+
*/
402+
abstract public function dividedBy(BigNumber|int|float|string $that) : static;
403+
351404
/**
352405
* Checks if this number is equal to the given one.
353406
*/

‎src/BigRational.php‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -194,7 +194,8 @@ public function quotientAndRemainder() : array
194194
*
195195
* @throws MathException If the number is not valid.
196196
*/
197-
public function plus(BigNumber|int|float|string $that) : BigRational
197+
#[Override]
198+
public function plus(BigNumber|int|float|string $that) : static
198199
{
199200
$that = BigRational::of($that);
200201

@@ -208,11 +209,12 @@ public function plus(BigNumber|int|float|string $that) : BigRational
208209
/**
209210
* Returns the difference of this number and the given one.
210211
*
211-
* @param BigNumber|int|float|string $that The number to subtract.
212+
* The result is a BigRational.
212213
*
213-
* @throws MathException If the number is not valid.
214+
* @throws MathException If the operand is not a valid number.
214215
*/
215-
public function minus(BigNumber|int|float|string $that) : BigRational
216+
#[Override]
217+
public function minus(BigNumber|int|float|string $that) : static
216218
{
217219
$that = BigRational::of($that);
218220

@@ -226,11 +228,12 @@ public function minus(BigNumber|int|float|string $that) : BigRational
226228
/**
227229
* Returns the product of this number and the given one.
228230
*
229-
* @param BigNumber|int|float|string $that The multiplier.
231+
* The result is a BigRational.
230232
*
231-
* @throws MathException If the multiplier is not a valid number.
233+
* @throws MathException If the operand is not a valid number.
232234
*/
233-
public function multipliedBy(BigNumber|int|float|string $that) : BigRational
235+
#[Override]
236+
public function multipliedBy(BigNumber|int|float|string $that) : static
234237
{
235238
$that = BigRational::of($that);
236239

@@ -243,11 +246,12 @@ public function multipliedBy(BigNumber|int|float|string $that) : BigRational
243246
/**
244247
* Returns the result of the division of this number by the given one.
245248
*
246-
* @param BigNumber|int|float|string $that The divisor.
249+
* The result is a BigRational.
247250
*
248-
* @throws MathException If the divisor is not a valid number, or is zero.
251+
* @throws MathException If the operand is not a valid number, or is zero.
249252
*/
250-
public function dividedBy(BigNumber|int|float|string $that) : BigRational
253+
#[Override]
254+
public function dividedBy(BigNumber|int|float|string $that) : static
251255
{
252256
$that = BigRational::of($that);
253257

0 commit comments

Comments
 (0)