diff --git a/docs/README.md b/docs/README.md index c067bae..b586b0a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -36,7 +36,7 @@ Transformation: These return a new object: - `absolute()`: Returns the absolute (positive) value of this decimal. - `negate()`: Returns the negation (positive if negative and vice versa). -- `trim()`: Remove trailing zeros after the comma (same value, but different semantic meaning in term of precision/scale). +- `trim()`: Remove trailing zeros after the comma (same value, but different semantic meaning in terms of precision/scale). There is only one static method and acts as a convenience wrapper to create an object: - `create()`: Internally does `new Decimal($value)`, allows for easier chaining without need of `()` wrapping. @@ -81,20 +81,26 @@ $decimalAdded = $decimalOne->add($decimalTwo); // Now '3.3' Note that due to immutability `$decimalOne` is not modified here. The re-assignment is necessary for the operation to persist. ### Precision/Scale -Operations like `add()` use the higher of the scales of the operands. +Operations like `add()` use the higher one of the scales of the operands. If both are the same, they would also stay the same. -With other operations like `multiply()`, they scale would be the addition of both operands' scale: +With other operations like `multiply()`, the scale would be the addition of both operands' scale by default: ```php $decimalOne = Decimal::create('1.55'); $decimalTwo = Decimal::create('2.00'); echo $decimalOne->multiply($decimalTwo); // Prints '3.1000' +``` + +To produce a result with a different number of decimal places, provide a value for the `$scale` parameter: +```php +$decimalOne = Decimal::create('1.55'); +$decimalTwo = Decimal::create('2.00'); -// Keeping 2 digit scale requires a 2nd argument echo $decimalOne->multiply($decimalTwo, 2); // Prints '3.10' ``` + ## Contributing You can contribute as pull request directly: diff --git a/src/Decimal.php b/src/Decimal.php index ccd21dc..c70492d 100644 --- a/src/Decimal.php +++ b/src/Decimal.php @@ -56,13 +56,15 @@ class Decimal implements JsonSerializable, Stringable protected bool $negative = false; /** + * Decimal places to be applied to results + * * decimal(10,6) => 6 */ protected int $scale = 0; /** * @param object|string|float|int $value - * @param int|null $scale Leave empty to auto-detect. + * @param int|null $scale Decimal places in the result. Omit to enable auto-detection. */ public function __construct(object|string|float|int $value, ?int $scale = null) { @@ -143,7 +145,7 @@ protected function normalizeValue(string $value): string * it. * * @param object|string|float|int $value - * @param int|null $scale Leave empty to auto-detect. + * @param int|null $scale Decimal places in the result. Omit to enable auto-detection. * * @return static */ @@ -247,7 +249,7 @@ public function compareTo(self|string|float|int $value): int * Add $value to this Decimal and return the sum as a new Decimal. * * @param static|string|float|int $value - * @param int|null $scale Leave empty to auto-detect. + * @param int|null $scale Decimal places in the result. Omit to enable auto-detection. * * @return static */ @@ -281,7 +283,7 @@ protected function resultScale(self $a, self $b, ?int $scale = null): int * Decimal. * * @param static|string|float|int $value - * @param int|null $scale Leave empty to auto-detect. + * @param int|null $scale Decimal places in the result. Omit to enable auto-detection. * * @return static */ @@ -389,7 +391,7 @@ public function isPositive(): bool * Multiply this Decimal by $value and return the product as a new Decimal. * * @param static|string|float|int $value - * @param int|null $scale Leave empty to auto-detect. + * @param int|null $scale Decimal places in the result. Omit to enable auto-detection. * * @return static */ @@ -407,7 +409,7 @@ public function multiply(self|string|int|float $value, ?int $scale = null): stat * Divide this Decimal by $value and return the quotient as a new Decimal. * * @param static|string|float|int $value - * @param int $scale + * @param int $scale Decimal places in the result * * @throws \DivisionByZeroError if $value is zero. * @@ -427,7 +429,7 @@ public function divide(self|string|int|float $value, int $scale): static * This method is equivalent to the ** operator. * * @param static|string|int $exponent - * @param int|null $scale Leave empty to use current. + * @param int|null $scale Decimal places in the result. Omit to enable auto-detection. * * @return static */ @@ -443,7 +445,7 @@ public function pow(self|string|int $exponent, ?int $scale = null): static /** * Returns the square root of this decimal, with the same scale as this decimal. * - * @param int|null $scale Leave empty to use current. + * @param int|null $scale Decimal places in the result. Omit to enable auto-detection. * * @return static */ @@ -460,7 +462,7 @@ public function sqrt(?int $scale = null): static * This method is equivalent to the % operator. * * @param static|string|int $value - * @param int|null $scale Leave empty to use current. + * @param int|null $scale Decimal places in the result. Omit to enable auto-detection. * * @return static */ @@ -474,7 +476,7 @@ public function mod(self|string|int $value, ?int $scale = null): static } /** - * @param int $scale + * @param int $scale Decimal places in the result (only used with mode "half up") * @param int $roundMode * * @return static @@ -524,7 +526,7 @@ public function ceil(): static /** * The result of discarding all digits behind the defined scale. * - * @param int $scale + * @param int $scale Decimal places in the result * * @throws \InvalidArgumentException *