Decimals represent numbers which have a decimal representation. They can be equivalent to either a float or an integer, and their $scale setting determines how many places after the decimal are calculated for operations which would affect them.

Abstract Class: Decimal

The following interfaces and traits are available on classes which extend Decimal

Interfaces

Hashable

namespace: Ds

The Hashable interface is part of ext-ds, and implementing it enables a class to be used as an array key in the various types provided by ext-ds.

BaseConversionInterface

namespace: Samsara\Fermat\Types\Base\Interfaces\Characteristics

BaseConversionInterface enables two methods: convertToBase() and getBase(), which do exactly what someone would expect them to.

Base Conversion is Done Just-In-Time

Internally, the values of objects which implement the BaseConversionInterface always store the number in base-10, since this is the only base that arithmetic can actually be performed in by any of the associated extensions.

Base conversion happens when a call is made to getValue(). Even on objects which have a base other than base-10, this can be avoided by calls to getAsBaseTenNumber() and getAsBaseTenRealNumber().

NumberInterface

namespace: Samsara\Fermat\Types\Base\Interfaces\Numbers

NumberInterface contains the base arithmetic methods that are a component of all numbers in mathematics. This includes the basics of addition, subtraction, multiplication, and division, as well as pow and square root.

It also provides the isEqual() method, to enable equality comparison, as well as getScale(). Some classes which implement the NumberInterface don't actually accept scale as an argument, but instead contain objects that do. Fraction is an example of such a class, as both its numerator and denominator are instances of ImmutableDecimal.

In addition, the is and as methods for Real, Imaginary, and Complex are provided by this interface.

SimpleNumberInterface

namespace: Samsara\Fermat\Types\Base\Interfaces\Numbers
extends: NumberInterface

The SimpleNumberInterface extends NumberInterface and adds the methods that are common to all non-complex numbers. This includes things like being positive or negative, inequality comparison, and getting the value as a base-10 real number.

DecimalInterface

namespace: Samsara\Fermat\Types\Base\Interfaces\Numbers
extends: SimpleNumberInterface which extends NumberInterface

The DecimalInterface extends SimpleNumberInterface and adds the methods that are common to all decimal values. This includes trigonometric operations, integer operations such as factorial() or isPrime(), integer and float comparisons and conversions, rounding and truncating functions, and log functions.

While some of these can be done on fractions in pure mathematics, such as trigonometry functions, in practice computers are not well-equipped to handle the algorithms for them without actually performing the division implied by the fraction. Thus, to use these types of functions an explicit call to asDecimal() must first be made on classes that implement Fraction.

Traits

ArithmeticSimpleTrait

namespace

Samsara\Fermat\Types\Traits

uses

ArithmeticScaleTrait
ArithmeticNativeTrait
ArithmeticSelectionTrat

satisfies

SimpleNumberInterface (partially)

The ArithmeticSimpleTrait provides the implementations for all arithmetic functions that exist on values that implement the SimpleNumberInterface. The additional imported traits within this trait provide the various calculation modes that are used internally depending on the mode of object executing the method call.

Accepts Complex Numbers as Arguments

While the ArithmeticSimpleTrait can accept implementations of ComplexNumber as arguments, it cannot be used in implementations of ComplexNumber.

Abstract Methods

The following abstract methods must be implemented on classes which extend Decimal

abstract protected function setValue(string $value, int $scale = null, int $base = 10)

$value: The new value that will be set in the same format as the output of getValue(10)
$scale: The maximum number of digits after the decimal that the value can contain
$base: The base of the value in the final instance
return: An instance of the current class with the given arguments set as properties

This method controls the behavior of setting the $value property, and its different implementations represent the main difference between mutable and immutable versions.

abstract public function continuousModulo($mod): DecimalInterface

$mod: The modulus that will be taken; the base which will be used to calculate the remainder; can be a decimal value
return: The remainder of dividing the current value by the $mod

This method comes from DecimalInterface and must be implemented by the extending class. This is because it might be undesirable for this method to be mutable, even for a mutable class. It takes a decimal value as its input, and returns the remainder of a division operation, even if the number provided is not an integer.

Available Value Objects

The following implementations of Decimal are included with Fermat. These classes may be provided for any argument which accepts a DecimalInterface as a value.

ImmutableDecimal

A number which can be represented as a decimal and has a maximum scale of $2^{63}$ digits. This value is immutable, and all methods called on instances of the class will return a new instance of the same class while leaving the existing instance at its original value.

MutableDecimal

A number which can be represented as a decimal and has a maximum scale of $2^{63}$ digits. This value is mutable, and all methods called on instances of the class will return the same instance after modification, while the previous value will be lost.