mathematicator-core / numbers
Safety operations with numbers.
Installs: 4 781
Dependents: 7
Suggesters: 0
Security: 0
Stars: 2
Watchers: 2
Forks: 1
Open Issues: 2
Requires
- php: >=7.2
- ext-json: *
- brick/math: ^0.8.15 || ^0.9.0
- nette/utils: ^3.0
- symfony/polyfill-php80: ^1.17
Requires (Dev)
- brainmaestro/composer-git-hooks: dev-master
- nette/tester: ^2.3
- phpstan/phpstan: ^0.12.18
- phpstan/phpstan-nette: ^0.12.6
Suggests
- ext-bcmath: For faster math operations
- ext-gmp: Alternative for faster math operations
This package is auto-updated.
Last update: 2024-08-30 01:23:23 UTC
README
Smart PHP Number Utilities
A PHP library to safely store and represent numbers and its equivalents in PHP.
Store lots of number types exactly (integers, decimals, fractions) and convert
them to each other. Expressions can be outputted as a human string (e.g. 1/2
)
or LaTeX (e.g. \frac{1}{2}
).
It is highly recommended to make sure you have enabled BCMath or GMP extension on your PHP server for much faster calculations.
Installation
composer require mathematicator-core/numbers
Features
- SmartNumber - Unified safe storage for all number types with
an arbitrary precision. It supports comparisons.
- Entity\Number Less magic universal arbitrary precision number storage with basic features.
- Fractions:
- Entity\Fraction - Storage for simple or compound fraction that can consist from numbers and other expressions.
- Entity\FractionNumbersOnly - Storage for simple or compound fraction that consists only from numbers and is directly computable.
- LaTeX support: (What is LaTeX?)
- MathLatexBuilder - Create valid LaTeX for mathematical expressions in simple way with a fluent interface.
- MathLatexToolkit - Statical library for LaTeX expressions (includes constants, functions, operators etc.)
- MathLatexSnippet - Storage for LaTeX syntax.
- Human string support:
- MathHumanStringBuilder - same interface as MathLatexBuilder, but produces human strings
- MathHumanStringToolkit - same interface as MathLatexToolkit,
but produces human strings (e.g.
1/2*(3+1)
)
- Set generators
- Primary numbers
- Even numbers
- Odd numbers
- Converters:
- Array to fraction and back
- Decimal to fraction
- Fraction to human string
- Fraction to LaTeX
- Int to Roman and back
- Calculation - simple arithmetic operations (brick/math decorator)
💡 TIP: You can use mathematicator-core/tokenizer for advance user input string tokenization or mathematicator-core/calculator for advance calculations.
Usage
use Brick\Math\RoundingMode; use Mathematicator\Numbers\SmartNumber; $smartNumber = SmartNumber::of('80.500'); echo $smartNumber->toBigDecimal(); // 80.500 echo $smartNumber->toFraction()->getNumerator(); // 161 echo $smartNumber->toFraction()->getDenominator(); // 2 echo Calculation::of($smartNumber)->multipliedBy(-4); // -322.000 echo Calculation::of($smartNumber)->multipliedBy(-4)->abs()->getResult()->toInt(); // 322 echo $smartNumber->toBigDecimal()->toScale(0, RoundingMode::HALF_UP); // 81 $smartNumber2 = SmartNumber::of('161/2'); echo $smartNumber2->toHumanString(); // 161/2 echo $smartNumber2->toHumanString()->plus(5)->equals('90.5'); // 161/2+10=90.5 echo $smartNumber2->toLatex(); // \frac{161}{2} echo $smartNumber2->toBigDecimal(); // 80.5
Recommended libraries
For safe operations with arbitrary length numbers we recommend to use:
- brick/math - Arbitrary precision arithmetic library for PHP with a simple interface.
- PHP BC Math extension - Native PHP extension for arbitrary precision computing.
Working with money
Use one of these libraries if you work with money in your application.
- brick/money - A money and currency library with an interface like brick/math.
- moneyphp/money - Widely adopted PHP implementation of Fowler's Money pattern.
Why float is not safe?
Float stores your number as an approximation with limited precision.
You should never trust float to the last digit. Do not use floats directly for checking equity if you rely on precision (not only monetary calculations).
Example:
$result = 0.1 + 0.2; echo $result; // output: 0.3 echo ($result == 0.3) ? 'true' : 'false'; // output: false
How is float stored in memory?
Read more about float on Wikipedia
Mathematicator Framework tools structure
The biggest advantage is that you can choose which layer best fits your needs and start build on the top of it, immediately, without the need to create everything by yourself. Our tools are tested for bugs and tuned for performance, so you can save a significant amount of your time, money, and effort.
Framework tend to be modular as much as possible, so you should be able to create an extension on each layer and its sublayers.
Mathematicator framework layers ordered from the most concrete one to the most abstract one:
Third-party packages:
⚠️ Not guaranteed!
Contribution
Please help to improve this documentation by sending a Pull request.
Tests
All new contributions should have its unit tests in /tests
directory.
Before you send a PR, please, check all tests pass.
This package uses Nette Tester. You can run tests via command:
composer test
For benchmarking, we use phpbench. You can run benchmarks this way:
composer global require phpbench/phpbench @dev # only the first time
phpbench run
Before PR, please run complete code check via command:
composer cs:install # only the first time composer fix # otherwise pre-commit hook can fail