mpd/util-strint-cmp

Library to compare large integers with arbitrary precisions, provides own pure php implementation, but can also use bcmath or GMP on background when available

v1.0.1 2025-01-04 23:44 UTC

Requires

• php: >=7.1

Requires (Dev)

• php: >=8.0
• phpunit/phpunit: ^11

Suggests

• ext-bcmath: *
• ext-gmp: *

LGPL-3.0-only

README

mpd\Util\StrIntCmp

Library to compare large integers with arbitrary precisions, provides own pure php implementation, but can also use bcmath or GMP on background when available

Installation

composer require mpd/util-strint-cmp
Compatible ^php7.1, ^php8. Tests require php8

Usage

use mpd\Util\StrIntCmp\StrIntCmp;

$a = '-350317994473186284556312754796813594860152465582658277960247';
$b = '-63245865813051830934382781315128857497460797902242257911260';

//use the best backend available. in order(gmp > bcmath > StrIntCmp::strIntCmp)
echo(StrIntCmp::cmp($a, $b)); // -1
//force use own implementation
echo(StrIntCmp::strIntCmp($a, $b)); // -1

echo(StrIntCmp::cmp("5", "2")); //  1
echo(StrIntCmp::cmp("2", "5")); // -1
echo(StrIntCmp::cmp("7", "7")); //  0

echo(StrIntCmp::isValidInt("75a")); // false
echo(StrIntCmp::isValidInt("14"));  // true

For performance reasons valid integer strings are assumed and no additional validation is done, it's your responsibility to provide valid format [+-]?[0-9]+. You can use isValidInt() to check if you cant be sure. invalid integers are basically undefined behaviour.
Yes + prefixed numbers are handled correctly too.
Note -0 is considered UB, depending on backend -0 == 0 or -0 < 0

class StrIntCmp {
    /* Properties */
    const SIZE; 
    public static $handler;
    /* Methods */
    public static cmp($a, $b): int
    public static strIntCmp($a, $b): int
    public static isValidInt($a): bool
    public static init(): void
}

• SIZE maximal length of decimal represented string that can be represented as native int on current platform
• $handler comparator to use. automatically set to optimal known, but you can set it to any function providing standard three-way comparison if you want
• cmp() unified api of all backends
• strIntCmp() direct call to backend implemented by this pkg
• isValidInt() check if string is considered valid integer
• init() resets $handler to optimal backend. Normally is not needed to call unless you wish to undo manual change of $handler or additional extensions was loaded during runtime

Motivation

We have been in need to compare large numbers with arbitrary precision anywhere, which is problematic on some hostings, and problems starts earlier than you might think.

platform (64bit scope)
When host system is 32bit php int is to, larger numbers silently become floats which sometimes results in incorrect results

polyfill
you can easily solve this by using libraries like bcmath or gmp... but these are not written in php, they are php extensions which needs to be installed physically in the system, and most standard web hosting dost let you touch that, they are sometimes available, but you need to modify your code depending on which one is available and sometimes there is none.
This library isolates you from this, you just call compare method, and receive result. It has its own pure php implementation, but prefers to use gmp/bcmath when available for better performance.

writing new
Research for similar library wasn't much successful, few pure php math implementations was found, but they usually looks abandoned since php5 was new and tends to be very large, and also don't act as "polyfill"

only comparators?
Idea of universal polyfill is tempting, but currently there is no need for more functionality rather for things being quickly done, and it also allows this lib to be small.
On internal or even external request it might become reality.
But anyway if you're doing that sensitive operations maybe you should look for better hosting that provides php extension.

Testing

composer run test
Test set is mainly based on random asserts generated by gen.py <no of tests>. Note due to how phpunit works, is not recommended creating more than about 500k asserts. this already takes quite long and requires nearly 4gb of ram for some reason. These generated tests are not included for size reasons. generate your own by running script, which also results in better testing. if you found values that don't work correctly send them to us please.
Recommendations for some critical values welcomed.