Skip to content

Commit

Permalink
Small updates to the documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
JordanRL committed Nov 2, 2022
1 parent 60844c9 commit 3dc8839
Show file tree
Hide file tree
Showing 2 changed files with 8 additions and 26 deletions.
6 changes: 6 additions & 0 deletions docs/fermat-vs-alternatives.md
Expand Up @@ -28,6 +28,12 @@ By providing objects which have a fluent interface and are aware of how the rest

There are other libraries that provide arbitrary precision math, or provide complex mathematical functions. This is the only PHP library that provides both.

### Compared to 'markrogoyski/math-php'

MathPHP does a great job with providing a large set of complex mathematical features. In fact, it currently has a more complete set of these features than Fermat does.

However, it doesn't provide library-wide support for arbitrary precision, and it can therefore be easy to lose precision while using any of the advanced features.

### Compared to 'brick/math'

This library does a fantastic job of providing a similarly fluent and consistent developer experience for dealing with arbitrary precision math, however it is limited to only the basic arithmetic which can be performed via the ext-bcmath extension.
Expand Down
28 changes: 2 additions & 26 deletions docs/index.md
Expand Up @@ -61,7 +61,7 @@ Provides a consistent abstraction for nearly any math concept that is likely to

While Fermat has different modes that allow you to control performance to a degree, the abstraction and comprehensive nature of the library means that for certain uses, such as working with complex numbers, a large number of object instances may be created temporarily during a calculation, leading to significantly more overhead than using operands directly when doing basic math within common scale limitations.

Despite the fact that performance is not a primary goal of this library, it does use built in functions wherever possible (where doing so does not affect scale), and it will utilize the GMP functions, the Decimal extension, and PHP-DS types if those extensions are present in your installation of PHP. Installing these extensions should increase performance in most use-cases.
Despite the fact that performance is not a primary goal of this library, it does use built-in functions wherever possible (where doing so does not affect scale), and it will utilize the GMP functions, the Decimal extension, and PHP-DS types if those extensions are present in your installation of PHP. Installing these extensions should increase performance in most use-cases.

Detailed information about performance can be reviewed in the [Performance](performance/overview.md) section. While performance is not the primary goal of this library, using the available [Calculation Modes](configuration/calculation-modes.md) it should be performant enough for most applications.

Expand Down Expand Up @@ -129,28 +129,4 @@ This is related to PHP's internal structure of hashtables and zvals, and how the
See the [php.net page](https://www.php.net/manual/en/language.oop5.references.php) for more information.

!!! see-also "See Also"
More information about mutable and immutable objects, as well as how they are implemented and used with this library, is available on the [Mutable vs. Immutable](getting-started/mutability.md) documentation page.

### This Library Can't Be Reliably Used With Math Operators

Because PHP doesn't allow operator overloading, using the native math operators on Fermat objects directly can very easily result in loss of scale, overflows and underflows, PHP fatal errors (f.e. when the object is in a non-base-10 format), and incorrect calculation (f.e. with complex and imaginary numbers).

!!! fail "Non-Base-10 Values With Native Operators"
Using a value that is in a base larger than base-10 with math operators can result in PHP fatal errors. For instance, the value `15` in base `16` will output the string `F`. When used with the operator `/` as the value on the right of the operator, this would result in a "Division by Zero" PHP fatal error.

This occurs because PHP will attempt to cast the string `F` to an `integer`, which will result in the value `0`.

!!! danger "Complex Numbers With Native Operators"
Using a `ComplexNumber` instance with native operators will throw only a notice and discard the imaginary component, making it very difficult to pin down the source of the incorrect result if notices are not turned on with the `E_NOTICE` or `E_ALL` levels in `php.ini`.

``` php
<?php

use Samsara\Fermat\Core\Values\ImmutableComplexNumber;

$complexNumber = ImmutableComplexNumber::makeFromString('2+2i');

echo $complexNumber + 2;
// Prints: 4
// Issues: PHP Notice
```
More information about mutable and immutable objects, as well as how they are implemented and used with this library, is available on the [Mutable vs. Immutable](getting-started/mutability.md) documentation page.

0 comments on commit 3dc8839

Please sign in to comment.