tiny-blocks/math

Value Objects for handling arbitrary precision numbers.

3.5.0 2024-12-11 16:00 UTC

Requires

• php: ^8.3
• ext-bcmath: *

Requires (Dev)

• infection/infection: ^0
• phpmd/phpmd: ^2.15
• phpstan/phpstan: ^1
• phpunit/phpunit: ^11
• squizlabs/php_codesniffer: ^3.11

Suggests

• ext-bcmath: Enables the extension which is an interface to the GNU implementation as a Basic Calculator utility library.

MIT

• Gustavo Freze de Araujo Santos

• math
• arithmetic
• psr
• Arbitrary-precision
• value-object
• vo
• tiny-blocks
• big-number

README

• Overview
• Installation
• How to use
• License
• Contributing

Overview

Value Objects for handling arbitrary precision numbers.

Installation

composer require tiny-blocks/math

How to use

The library exposes some concrete implementations for arbitrary precision numbers. Concrete implementations implement the BigNumber interface, which provides the behaviors for the respective BigNumbers.

Using the fromString method

With the fromString method, a new instance of type BigNumber is created from a valid string numeric value.

BigDecimal::fromString(value: '10');
BigDecimal::fromString(value: '-123.456');

It is possible to set a scale for the object through this method.

BigDecimal::fromString(value: '10', scale: 2);

Always prefer to instantiate from a string, which supports an unlimited number of digits and ensures no loss of precision.

Using the fromFloat method

With the fromFloat method, a new instance of type BigNumber is created from a valid float value.

BigDecimal::fromFloat(value: 10.0);
BigDecimal::fromFloat(value: -123.456);

It is also possible to set a scale for the object through this method.

BigDecimal::fromFloat(value: 10.0, scale: 2);

Using the methods of mathematical operations

Addition

Performs an addition operation between this value and another value.

$augend = BigDecimal::fromString(value: '1');
$addend = BigDecimal::fromFloat(value: 1.0);

$result = $augend->add(addend: $addend);

$result->toString(); # 2

Subtraction

Performs a subtraction operation between this value and another value.

$minuend = BigDecimal::fromString(value: '1');
$subtrahend = BigDecimal::fromFloat(value: 1.0);

$result = $minuend->subtract(subtrahend: $subtrahend);

$result->toString(); # 0

Multiplication

Performs a multiplication operation between this value and another value.

$multiplicand = BigDecimal::fromString(value: '1');
$multiplier = BigDecimal::fromFloat(value: 1.0);

$result = $multiplicand->multiply(multiplier: $multiplier);

$result->toString(); # 1

Division

Performs a division operation between this value and another value.

$dividend = BigDecimal::fromString(value: '1');
$divisor = BigDecimal::fromFloat(value: 1.0);

$result = $dividend->divide(divisor: $divisor);

$result->toString(); # 1

Using other resources

If you need to perform rounding, you can use the withRounding method.

Use one of the following constants to specify the mode in which rounding occurs:

• HALF_UP: Round number away from zero when halfway.

  $value = BigDecimal::fromFloat(value: 0.9950, scale: 2);
  
  $result = $value->withRounding(mode: RoundingMode::HALF_UP);
  
  $result->toString(); # 1

• HALF_DOWN: Round number to zero when halfway.

  $value = BigDecimal::fromFloat(value: 0.9950, scale: 2);
  
  $result = $value->withRounding(mode: RoundingMode::HALF_DOWN);
  
  $result->toString(); # 0.99

• HALF_EVEN: Round number to the nearest even value when halfway.

  $value = BigDecimal::fromFloat(value: 0.9950, scale: 2);
  
  $result = $value->withRounding(mode: RoundingMode::HALF_EVEN);
  
  $result->toString(); # 1

• HALF_ODD: Round number to the nearest odd value when halfway.

  $value = BigDecimal::fromFloat(value: 0.9950, scale: 2);
  
  $result = $value->withRounding(mode: RoundingMode::HALF_ODD);
  
  $result->toString(); # 0.99

Others

Check out other available resources by looking at the BigNumber interface.

License

Math is licensed under MIT.

Contributing

Please follow the contributing guidelines to contribute to the project.