README

bcmath-extended

This PHP library extends the BCMath PHP estension. Since the class BCMath\Number is a final class, this library extends through composition with a child class (Number).

It was inspired by krowinski/bcmath-extended.

Index

• Installation
• Features
• Input types
• Notes
• API documentation

Installation

composer require marcoconsiglio/bcmath-extended

Features

Base features

The following list of features of the Number class are the same as those found in BCMath\Number:

• Base instance $value
• Base instance $scale
• Addition
• Subtracion
• Multiplication
• Division
• Exponentiation
• Square root
• Ceil
• Floor
• Round
• Cast to string type

Missing base features

These are the missing features:

• Spaceship comparison
• Comparison operator overloading
• Serialization/unserialization

Added features

This list consists of the new features added in this library:

• float type input **
• Cast to float type **
• Cast to int type
• Modulo *
• Power & modulo *
• Division & modulo *
• Absolute
• Min
• Max
• Random
• Equal comparison
• Different comparison
• Greater than comparison
• Greater than or equal comparison
• Less than comparison
• Less than or equal comparison
• In range comparison
• In range min excluded comparison
• In range max excluded comparison
• In range both extremes excluded comparison
• Convert to radian
• Convert to degree
• Opposite sign

Input types

This is the input types set available:

• int
• string
• float **
• BCMath\Number
• MarcoConsiglio\BCMathExtended\Number

String numeric format

• Only decimal separator . is allowed.
• Thousand separator is not supported.
• Scientific notation is not supported (use Number::string() method to cast very big or small float numbers to numeric string without scientific notation).

For example "1234567.89" is allowed while "1,234,567.89" is not.

Notes

* Consideration on modulo operation

As already pointed by krowinsky in PHP issue #76287

bcmod() doesn't use floor() but rather truncates towards zero,
which is also defined this way for POSIX fmod(), so that the
result always has the same sign as the dividend.  Therefore, this
is not a bug, but rather a documentation issue.

the modulo operation in BCMath extension is not correct in case the modulus is negative. Therefore in this library the following formula is used:

$$ a \pmod n = a - n \times \left \lfloor {\dfrac{a}{n}} \right \rfloor $$

With this formula a negative modulus $n$ is allowed.

** Consideration on float type

If you need to convert a float to Number and back, prepare for the worst. Keep in mind that floating point arithmetic is full of hidden flaws, that's why aribtrary arithmetic is needed (in this case implemented by BcMath PHP extension).

While this library accept a float type input, it is not recommended to cast a Number instance to float, otherwise nasty things could happen.

Use this library only for end calculations, like print a report. If other subsystem of your software need float type inputs, it is strongly advised to avoid this library for intermediate calculations.

API documentation

You can find the API documentation at docs/html/index.html.