{"id":24780404,"url":"https://github.com/webgriffe/rational","last_synced_at":"2025-07-23T21:10:07.759Z","repository":{"id":44464501,"uuid":"512717487","full_name":"webgriffe/rational","owner":"webgriffe","description":"A PHP representation of a rational number with some basic arithmetic operations","archived":false,"fork":false,"pushed_at":"2025-05-19T10:18:00.000Z","size":42,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-06-21T14:41:36.121Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webgriffe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-11T10:49:38.000Z","updated_at":"2025-05-19T10:18:04.000Z","dependencies_parsed_at":"2025-01-29T10:30:30.505Z","dependency_job_id":"c9fc1e46-f814-4b20-9808-f44a7c8d865a","html_url":"https://github.com/webgriffe/rational","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/webgriffe/rational","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webgriffe%2Frational","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webgriffe%2Frational/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webgriffe%2Frational/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webgriffe%2Frational/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webgriffe","download_url":"https://codeload.github.com/webgriffe/rational/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webgriffe%2Frational/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266748845,"owners_count":23978292,"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","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-01-29T10:30:22.588Z","updated_at":"2025-07-23T21:10:07.751Z","avatar_url":"https://github.com/webgriffe.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rational - A simple rational number implementation\n\n## Features\nThis library implements a numeric data type that represents a rational number, that is a number that can be represented as the division of two integer numbers. This includes periodic numbers (such as 0.333333..., which can be easily represented as 1/3) and those numbers that cannot be represented exactly by a floating point type (such as 0.1, which is a periodic number in binary representation, but which can be easily represented by the fraction 1/10).\n\nIn order to reduce the possibility of large values triggering overflow issues, an integer \"whole\" part is added to the fraction. This means that values are stored as mixed numbers of the form `a + b/c`, where a, b and c are all integers.\n\nCalculations are performed using the GMP extension for arbitrary precision integers. This ensures that there is no possibility of overflow errors being generated by intermediate results before they are simplified and normalized.\n\nAt the end of each operation, after all simplification and normalization steps, if the final results still do not fit into PHP's standard `integer` type, then an overflow exception is generated.\n\nThis library is very similar to https://github.com/markrogoyski/math-php/blob/master/src/Number/Rational.php, with the main exception being that this implementation uses the GMP extension internally to ensure that no overflow issues can arise with the intermediate computation results.\n\n## Setup\nAdd the library to your `composer.json` file in your project:\n```\n{\n  \"require\": {\n      \"webgriffe/rational\": \"^2.0\"\n  }\n}\n```\n\nUse composer to install the library:\n\n```\n$ php composer.phar install\n```\n\nComposer will install the library inside your vendor folder. If you don't already use Composer in your project, you may need to explicitly include its autoload file in order to allow PHP to find the library class(es):\n\n```\nrequire_once __DIR__ . '/vendor/autoload.php';\n```\n\n## Minimum Requirements\n* PHP 8.1 with the GMP extension installed\n\n## Usage\nSince floating point number are inherently inaccurate, it was deliberately decided NOT to provide a way to initialize a rational number from a float. Likewise, no method is provided to convert a rational to a float for the same reason.\n\nCreating rational numbers is possible starting from integers or from the various parts of the rational number.\n```php\nuse Webgriffe\\Rational;\n\n//Creates a zero value\n$r0 = Rational::zero();\n\n//Creates a one value\n$r1 = Rational::one();\n\n//Creates a whole number\n$r2 = Rational::fromWhole(-2);\n\n//Creates a variable that stores exactly ⅔ (two thirds), roughly 0.666666...\n$r3 = Rational::fromFraction(2, 3);\n\n//Creates a variable that stores exactly 4 + ⅑ (one ninth), roughly 7.111111...\n$r4 = Rational::fromWholeAndFraction(4, 1, 9);\n\n//Adds $r1 and $r2 so that $r5 equals -1\n$r5 = $r1-\u003eadd($r2);\n\n//Adds $r3 to $r5: -1 + ⅔ = -⅓\n$r6 = $r5-\u003eadd($r3);\n\n//Subtracts $r6 from $r2: -2 - (-⅓) = -2 + ⅓ = -1 - ⅔\n$r7 = $r2-\u003esub($r6);\n\n//Multiply $r7 by $r4: (-1 - ⅔) * (4 + ⅑)\n//= -4 - 1/9 - 8/3 - 2/27\n//= -4 - 3/27 - 72/27 - 2/27\n//= -4 - 77/27\n//= -4 - 2 - 23/27\n//= -6 - 23/27\n$r8 = $r7-\u003emul($r4);\n\n//Divide $r8 by $r3: (-6 - 23/27) / (2/3)\n//= (-6 - 23/27) * (3/2)\n//= -9 - 23/18\n//= -9 - 1 - 5/18\n//= -10 - 5/18\n$r9 = $r8-\u003ediv($r3);\n\n//Compute the reciprocal of $r9: 1/(-10 - 5/18)\n//= 1/((-180 - 5)/18)\n//= 1/(-185/18)\n//= 18/-185\n//= -18/185\n$r10 = $r9-\u003erecip();\n\n//$r11 = $r10 + $r1: -18/185 + 1\n//= -18/185 + 185/185\n//= 167/185\n$r11 = $r10-\u003eadd($r1);\n\n//Prints 0,903\necho $r11-\u003eformat(3, 0, ',', '');\n\n//Forces 2 decimals and prints 0.90. Useful when dealing with prices\necho $r11-\u003eformat(2, 2, '.', '');\n\n//$r12 = $r11 - $r10: 167/185 - (-18/185)\n//= 167/185 + 18/185\n//= 185/185\n//= 1\n$r12 = $r11-\u003esub($r10);\n```\n\n## Usage in an application\n### Extension\n\nIt is possible to extend the `Rational` class to seamlessly use it in application-specific contexts.\n\nFor example, if one wants to use the `Rational` class to represent percentages, it is possible to define a `Percentage` class that extends `Rational`:\n\n```php\nuse Webgriffe\\Rational;\n\nfinal class Percentage extends Rational {\n}\n```\n\nAll methods are type-hinted in such a way that all results will be identified as having the type of the first operand of each operation. So, for example, if a `Percentage` object is added to another `Percentage`, the result will be of type `Percentage` as well.\n\n### Containment\n\nOf course, it is also possible to encapsulate instances of `Rational` inside other classes:\n\n```php\nuse Webgriffe\\Rational;\n\nclass Money {\n    public function __construct(\n        private readonly Rational $value,\n        private readonly string $currency,\n    ) {\n    }\n\n    public function add(self $other): static {\n        return new static($this-\u003evalue-\u003eadd($other-\u003evalue));\n    }\n    \n    ...\n}\n```\n\nThis has the benefit that one can control precisely what operations are allowed and what are not. For example, for a class that represents amounts of money, the reciprocal operation may not make much sense. Likewise, multiplying an amount of money by another amount of money may not be sensible. while division might make sense, but its result would not be a money object, it would be a plain `Rational` object.\n\nThe drawback is that one has to manually redefine all the desired arithmetic operations to work on the contained `Rational` value.\n\n## Internal working\nThe library stores all components of the rational number as PHP integers. This is to make it easier to store these values to databases and other media where storing arbitrary-length integers may be problematic.\nIntermediate values are handled through the PHP GMP library in order to avoid overflow issues until the final results are computed. If, however, the final result of each operation exceeds the range of PHP integers, the library reports an overflow error.\n\nImmediately after creation and after every operation, each value is normalized. The purpose of this is to reduce the magnitude of the values stored internally and to make it easier to compare rational numbers and to extract other useful information.\n\nIn the context of this library which stores values as `a + b/c`, a normalized value is one where `c \u003e 0`, where `a * b \u003e= 0` (i.e. they do not disagree in sign, though one or both can be zero), where `GCD(|b|, c) == 1` (i.e. the fraction `b/c` is simplified) and `|a| \u003c b` (i.e. it is a proper fraction).\n\n## Overflow\nAt the end of every operation the library converts the intermediate GMP values back to integers. If these values are too large or too small to fit into an integer, a OverflowException is thrown. It is the user's responsibility to catch the exception and act accordingly.\n\n## License\nWebgriffe/Rational is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebgriffe%2Frational","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebgriffe%2Frational","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebgriffe%2Frational/lists"}