{"id":15740083,"url":"https://github.com/marcospassos/phpcommon-intmath","last_synced_at":"2025-03-13T08:31:52.879Z","repository":{"id":57040295,"uuid":"60445417","full_name":"marcospassos/phpcommon-intmath","owner":"marcospassos","description":"PHP 5.3+ library for arithmetic operations on integers that wraps around upon overflow.","archived":false,"fork":false,"pushed_at":"2016-07-04T01:03:53.000Z","size":91,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-26T19:27:35.753Z","etag":null,"topics":["hash","hashing","math","overflow","php","php-library"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcospassos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-06-05T05:52:03.000Z","updated_at":"2019-02-27T11:23:17.000Z","dependencies_parsed_at":"2022-08-24T00:50:55.979Z","dependency_job_id":null,"html_url":"https://github.com/marcospassos/phpcommon-intmath","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcospassos%2Fphpcommon-intmath","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcospassos%2Fphpcommon-intmath/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcospassos%2Fphpcommon-intmath/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcospassos%2Fphpcommon-intmath/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcospassos","download_url":"https://codeload.github.com/marcospassos/phpcommon-intmath/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243369893,"owners_count":20280097,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hash","hashing","math","overflow","php","php-library"],"created_at":"2024-10-04T02:11:19.944Z","updated_at":"2025-03-13T08:31:52.497Z","avatar_url":"https://github.com/marcospassos.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PHPCommon IntMath\n\n[![Build Status](https://travis-ci.org/marcospassos/phpcommon-intmath.svg?branch=master)](https://travis-ci.org/marcospassos/phpcommon-intmath)\n[![Code Coverage](https://scrutinizer-ci.com/g/marcospassos/phpcommon-intmath/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/marcospassos/phpcommon-intmath/?branch=master)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/marcospassos/phpcommon-intmath/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/marcospassos/phpcommon-intmath/?branch=master)\n[![StyleCI](https://styleci.io/repos/60445417/shield)](https://styleci.io/repos/60445417)\n[![Latest Stable Version](https://poser.pugx.org/phpcommon/intmath/v/stable)](https://packagist.org/packages/phpcommon/intmath)\n[![Dependency Status](https://www.versioneye.com/user/projects/5753c83a7757a0003bd4af4a/badge.svg?style=flat)](https://www.versioneye.com/user/projects/5753c83a7757a0003bd4af4a)\n\nLatest release: [1.0.0-beta](https://packagist.org/packages/phpcommon/intmath#1.0.0)\n\nPHP 5.3+ library for arithmetic operations on integers that wraps around upon\noverflow.\n\n\u003e **Attention**\n\u003e \n\u003e This library is not intended for use as a way to properly perform arithmetic\n\u003e operations on integers and should not be used in place of the native\n\u003e arithmetic operators or any other library designed for such purpose.\n\nUnlike other languages that overflow large positive integers into large\nnegative integers, PHP actually overflows integers to floating-point\nnumbers. In most cases, arithmetic overflows must be treated as an unusual\ncircumstance which requires special handling. However, there are some cases\nwhere such _wrap-around_ behavior is actually useful - for example with TCP\nsequence numbers or certain algorithms, such as hash calculation. This\nutility class provides basic arithmetic functions that operate in accordance\nto that behaviour. \n\nTo illustrate, consider the following example:\n\n```php\n// Output on 64-bit system: float(9.2233720368548E+18)\nvar_dump(PHP_MAX_INT + 1);\n\n// Output on 64-bit system: int(-9223372036854775808)\nvar_dump(IntMath::add(PHP_MAX_INT, 1));\n```\nAs previously shown, adding one to the largest integer supported using\nnative arithmetic operators will result in a floating-point number. By\ncontrast, using [IntMath::add()](#addition) will cause an overflow, resulting\nin the smallest integer supported in this build of PHP.\n\nThe API is extensively documented in the source code. In addition, an\n[HTML version][link-api-doc] is also available for more convenient viewing in\nbrowser.\n\n## Installation\n\nUse [Composer][link-composer] to install the package:\n\n```sh\n$ composer require phpcommon/intmath\n```\n\n## Operations\n\nCurrently, only the four basic arithmetic operations (addition, subtraction,\nmultiplication and division) and negation are supported.\n\n### Negation\n\nFor integer values, negation is the same as subtraction from zero. Because PHP\nuses two's-complement representation for integers and the range of\ntwo's-complement values is not symmetric, the negation of the maximum negative\ninteger results in that same maximum negative number. Despite the fact that\noverflow has occurred, no exception is thrown.\n    \nFor all integer values `$a`, `-$a` equals `(~$a) + 1`.\n\nAPI example usage:\n ```php\n // Outputs int(-100)\n var_dump(IntMath::negate(100));\n ```\n\n### Addition\n\nThe result of adding two integers is the low-order bits of the true\nmathematical result as represented in a sufficiently wide two's-complement\nformat. If overflow occurs, then the sign of the result may not be the same as\nthe sign of the mathematical sum of the two values. Despite the overflow, no\nexception is thrown in this case.\n\nAPI example usage:\n ```php\n // Outputs int(300)\n var_dump(IntMath::add(100, 200));\n ```\n\n### Subtraction\n\nThe subtraction of a positive number yields the same result as the addition of\na negative number of equal magnitude. Furthermore, the subtraction from zero is\nthe same as negation. The result is the low-order bits of the true mathematical\nresult as represented in a sufficiently wide two's-complement format. If\noverflow occurs, then the sign of the result may not be the same as the sign of\nthe mathematical difference of the two values. Despite the overflow, no\nexception is thrown in this case.\n\nAPI example usage:\n ```php\n // Outputs int(90)\n IntMath::subtract(100, 10);\n ```\n\n### Multiplication\n\nThe result of multiplying two integers is the low-order bits of the true\nmathematical result as represented in a sufficiently wide two's-complement\nformat. If overflow occurs, then the sign of the result may not be the same as\nthe sign of the mathematical product of the two values. Despite the overflow,\nno exception is thrown in this case.\n\nAPI example usage:\n ```php\n // Outputs int(200)\n IntMath::multiply(100, 2);\n ```\n\n### Division\n\nThe division rounds the result towards zero. Thus the absolute value of the \nresult is the largest possible integer that is less than or equal to the\nabsolute value of the quotient of the two operands. The result is zero or\npositive when the two operands have the same sign and zero or negative when the\ntwo operands have opposite signs.\n\nThere is one special case that does not satisfy this rule: if the dividend is\nthe negative integer of largest possible magnitude for its type, and the\ndivisor is `-1`, then integer overflow occurs and the result is equal to the\ndividend. Despite the overflow, no exception is thrown in this case. On the\nother hand if the value of the divisor in an integer division is `0`, then a\n`DivisionByZeroException` is thrown.\n\nAPI example usage:\n ```php\n // Outputs int(50)\n IntMath::divide(100, 2);\n ```\n \n## Change log\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.\n\n\n## Testing\n\n```sh\n$ composer test\n```\n\nCheck out the [Test Documentation][link-testsdoc] for more details.\n\n## Contributing\n\nContributions to the package are always welcome!\n\n* Report any bugs or issues you find on the [issue tracker][link-issue-tracker].\n* You can grab the source code at the package's\n[Git repository][link-repository].\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) and [CONDUCT](CONDUCT.md) for\ndetails.\n\n## Security\n\nIf you discover any security related issues, please email\nmarcos@marcospassos.com instead of using the issue tracker.\n\n## Credits\n\n* [Marcos Passos][link-author]\n- [All Contributors][link-contributors]\n\n## License\n\nAll contents of this package are licensed under the [MIT license](LICENSE).\n\n[link-api-doc]: http://marcospassos.github.io/phpcommon-intmath/docs/api\n[link-testsdoc]: http://marcospassos.github.io/phpcommon-intmath/docs/test\n[link-composer]: https://getcomposer.org\n[link-author]: http://github.com/marcospassos\n[link-contributors]: https://github.com/marcospassos/phpcommon-intmath/graphs/contributors\n[link-issue-tracker]: https://github.com/marcospassos/phpcommon-intmath/issues\n[link-repository]: https://github.com/marcospassos/phpcommon-intmath\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcospassos%2Fphpcommon-intmath","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcospassos%2Fphpcommon-intmath","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcospassos%2Fphpcommon-intmath/lists"}