tetthys/bc

Bc is a small and simple but accurate tool for calculation.

1.0.0 2024-07-03 15:09 UTC

Requires

• php: >=8.1

Requires (Dev)

• pestphp/pest: ^2.34

MIT

• tetthys

• decimal
• math
• calculation
• number
• arithmetic
• precision
• bcmath
• integer
• rounding
• scale
• operation
• float
• bc

README

• System Requirements
• Bc
• Why Bc?
• Usage Examples
  • Calculation
  • Comparison
• About num method
• About scale method
• Supported Calculation Methods
  • add
  • sub
  • mul
  • div
  • mod
  • pow
  • powmod
  • sqrt
• Supported Comparison Methods
  • isGreaterThan
  • isGreaterThanOrEqual
  • isLessThan
  • isLessThanOrEqual
  • isEqual
  • isDifferent
  • gt
  • gte
  • lt
  • lte
  • is
  • isNot
• Runtime Exceptions
  • ScaleCannotBeUsedForOperation
  • ValueCannotBeUsedForOperation
• How to contribute and test in same environment?
  • docker-compose up
  • attach shell to phptestenv container
  • install dependencies with composer
  • run test
• What I want to say

System Requirements

• php 8.1 or later
• php bcmath extension

Bc

Bc is a small and simple but accurate tool for calculation. It uses bcmath functions internally.

You can get the exact result you want.

There are no rounding issues if you have enough memory.

It's like calculating to N decimal places using a pen and paper with your hands.

Why Bc?

Do you think below test will pass?

it('shows that 0.1 + 0.2 = 0.3', function () {
    expect(0.1 + 0.2)->toBe(0.3);
});

Unfortunately, 0.1 + 0.2 is not 0.3 in php

It fails for the following reason:

Failed asserting that 0.30000000000000004 is identical to 0.3.

That's why I made this.

Usage Examples

Calculation

After giving a scale value, you can calculate in order.

(new Bc)->scale(2)->num('1')->add('2')->mul('3')->value(); // '9.00'

It also can be used like below:

(new Bc('1'))->add(new Bc('2'))->mul(new Bc('3'))->value(); // '9'

(new Bc)->scale(2)->num((new Bc('1')))->add(new Bc('2'))->mul(new Bc('3'))->value(); // '9.00'

Comparison

After giving a scale value, you can compare.

// true for '10.00' > '1.00'
(new Bc)->scale(2)->num('10')
    ->isGreaterThan('1');

It also can be used like below:

// true for '30.00' > '3.00'
(new Bc)->scale(2)->num('10')->add('20')
    ->isGreaterThan((new Bc)->scale(2)->num('1')->add('2'));

About num method

It specifies a number at which the calculation begins. It always returns Bc instance.

(new Bc)->num('1')

Or you can use the below instead:

(new Bc('1'))

About scale method

It specifies a scale value to be passed on to a next operation. The default value is 0.

(new Bc)->num('1')->add('2')->value(); // '3'

It supports chaining:

// With scale 0, '1' + '2' = '3'
// With scale 2, '3.00' * '3.00' = '9.00'
(new Bc)->num('1')->add('2')->scale(2)->mul('3')->value(); // '9.00'

Supported Calculation Methods

Calculation methods expect string or Bc instance. And they always return Bc instance.

add

It adds a number

(new Bc)->num('1')->add('2')->value(); // '3'

sub

It subtracts a number

(new Bc)->num('2')->sub('1')->value(); // '1'

mul

It multiplies a number

(new Bc)->num('2')->mul('3')->value(); // '6'

div

It divides a number

(new Bc)->num('6')->div('3')->value(); // '2'

mod

It calculates the modulus of a number

(new Bc)->num('10')->mod('7')->value(); // '3'

pow

It calculates the power of a number

(new Bc)->num('2')->pow('3')->value(); // '8'

powmod

It calculates the power of a number with modulus

(new Bc)->num('2')->powmod('5', '3')->value(); // '2'

sqrt

It calculates the square root of a number

(new Bc)->num('9')->sqrt()->value(); // '3'

Supported Comparison Methods

Comparison methods expect string or Bc instance. And they always return bool.

isGreaterThan

It checks if a number is greater than another number

(new Bc)->num('10')->isGreaterThan('1'); // true

isGreaterThanOrEqual

It checks if a number is greater than or equal to another number

(new Bc)->num('10')->isGreaterThanOrEqual('10'); // true

isLessThan

It checks if a number is less than another number

(new Bc)->num('1')->isLessThan('10'); // true

isLessThanOrEqual

It checks if a number is less than or equal to another number

(new Bc)->num('10')->isLessThanOrEqual('10'); // true

isEqual

It checks if a number is equal to another number

(new Bc)->num('10')->isEqual('10'); // true

isDifferent

It checks if a number is different from another number

(new Bc)->num('10')->isDifferent('1'); // true

gt

Same as isGreaterThan

(new Bc)->num('10')->gt('1'); // true

gte

Same as isGreaterThanOrEqual

(new Bc)->num('10')->gte('10'); // true

lt

Same as isLessThan

(new Bc)->num('1')->lt('10'); // true

lte

Same as isLessThanOrEqual

(new Bc)->num('10')->lte('10'); // true

is

Same as isEqual

(new Bc)->num('10')->is('10'); // true

isNot

Same as isDifferent

(new Bc)->num('10')->isNot('1'); // true

Runtime Exceptions

ScaleCannotBeUsedForOperation

throw new \Tetthys\Bc\Exceptions\ScaleCannotBeUsedForOperation;

This is thrown when scale is less than 0.

ValueCannotBeUsedForOperation

throw new \Tetthys\Bc\Exceptions\ValueCannotBeUsedForOperation;

This is thrown when value is not a number.

How to contribute and test in same environment?

docker-compose up

docker-compose up

attach shell to phptestenv container

bash ./run/shell/phptestenv.sh

install dependencies with composer

composer install

run test

./vendor/bin/pest

Or, you can run test from host OS using

bash ./run/test.sh

What I want to say

It is currently June 2024.

I'm still learning commit and branch naming conventions and php composer rules.

I hope you understand even if some of the names are bad.

Thank you.