## webgriffe / rational

A data type used to represent rational numbers

Installs: 6 649

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 7

Forks: 0

Open Issues: 0

Requires

- php: ~8.1
- ext-gmp: *
- ext-intl: *

Requires (Dev)

- phpunit/phpunit: ^9.5

# README

## Features

This 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).

In 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.

This library is fundamentally 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.

At 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.

## Setup

Add the library to your `composer.json`

file in your project:

```
{
"require": {
"webgriffe/rational": "^2.0"
}
}
```

Use composer to install the library:

```
$ php composer.phar install
```

Composer 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):

```
require_once __DIR__ . '/vendor/autoload.php';
```

## Minimum Requirements

- PHP 8.1 with the GMP extension installed

## Usage

Since 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.

Creating rational numbers is possible starting from integers or from the various parts of the rational number.

use Webgriffe\Rational; //Creates a zero value $r0 = Rational::zero(); //Creates a one value $r1 = Rational::one(); //Creates a whole number $r2 = Rational::fromWhole(-2); //Creates a variable that stores exactly ⅔ (two thirds), roughly 0.666666... $r3 = Rational::fromFraction(2, 3); //Creates a variable that stores exactly 4 + ⅑ (one ninth), roughly 7.111111... $r4 = Rational::fromWholeAndFraction(4, 1, 9); //Adds $r1 and $r2 so that $r5 equals -1 $r5 = $r1->add($r2); //Adds $r3 to $r5: -1 + ⅔ = -⅓ $r6 = $r5->add($r3); //Subtracts $r6 from $r2: -2 - (-⅓) = -2 + ⅓ = -1 - ⅔ $r7 = $r2->sub($r6); //Multiply $r7 by $r4: (-1 - ⅔) * (4 + ⅑) //= -4 - 1/9 - 8/3 - 2/27 //= -4 - 3/27 - 72/27 - 2/27 //= -4 - 77/27 //= -4 - 2 - 23/27 //= -6 - 23/27 $r8 = $r7->mul($r4); //Divide $r8 by $r3: (-6 - 23/27) / (2/3) //= (-6 - 23/27) * (3/2) //= -9 - 23/18 //= -9 - 1 - 5/18 //= -10 - 5/18 $r9 = $r8->div($r3); //Compute the reciprocal of $r9: 1/(-10 - 5/18) //= 1/((-180 - 5)/18) //= 1/(-185/18) //= 18/-185 //= -18/185 $r10 = $r9->recip(); //$r11 = $r10 + $r1: -18/185 + 1 //= -18/185 + 185/185 //= 167/185 $r11 = $r10->add($r1); //Prints 0,903 echo $r11->format(3, 0, ',', ''); //Forces 2 decimals and prints 0.90. Useful when dealing with prices echo $r11->format(2, 2, '.', ''); //$r12 = $r11 - $r10: 167/185 - (-18/185) //= 167/185 + 18/185 //= 185/185 //= 1 $r12 = $r11->sub($r10);

## Usage in an application

### Extension

It is possible to extend the `Rational`

class to seamlessly use it in application-specific contexts.

For example, if one wants to use the `Rational`

class to represent prices or amounts of money, it is possible to define a `Money`

class that extends `Rational`

:

use Webgriffe\Rational; final class Money extends Rational { }

All 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 `Money`

object is added to another `Money`

, the result will be of type `Money`

as well.

### Containment

Of course, it is also possible to encapsulate instances of `Rational`

inside other classes:

use Webgriffe\Rational; class Money { public function __construct( private readonly Rational $value ) { } public function add(self $other): static { return new static($this->value->add($other->value)); } ... }

This 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 or dividing an amount of money by another amount of money may not be sensible.

The drawback is that one has to manually redefine all the desired arithmetic operations to work on the contained `Rational`

value.

## Internal working

The 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. Intermediate 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.

Immediately 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.

In the context of this library which stores values as `a + b/c`

, a normalized value is one where `c > 0`

, where `a * b >= 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| < b`

(i.e. it is a proper fraction).

## Overflow

At 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.

## License

Webgriffe/Rational is licensed under the MIT License.