You can also directly instantiate the Value classes if you wish, and sometimes it is desirable to do so.

Mutable vs. Immutable

This section details the concrete implementations that are available for the various values in Fermat. Many of these implementations have a Mutable and an Immutable version.

For more detailed information about the differences between these, and the situations that each might be useful in, please see the page on mutability.

Values of Decimal

These classes extend the Decimal abstract class, which comes with the following interfaces, traits, and constructor.

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.

See Also

The page for Types & Values > Fractions contains more information on the limitations of fraction representations within Fermat.

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.

See Also

More detailed information on this trait is available on the Arithmetic > Simple Numbers page.

ComparisonTrait

namespace
Samsara\Fermat\Types\Traits
satisfies
SimpleNumberInterface (partially)

The ComparisonTrait provides the implementations of all comparison methods for any class which implements the SimpleNumberInterface.

IntegerMathTrait

namespace
Samsara\Fermat\Types\Traits
satisfies
DecimalInterface (partially)

The IntegerMathTrait provides the implementations of all integer math methods for any class which implements the DecimalInterface. This includes methods such as factorial() and isPrime().

TrigonometryTrait

namespace
Samsara\Fermat\Types\Traits\Decimal
satisfies
DecimalInterface (partially)

The TrigonometryTrait provides the implementations for all basic trigonometry and hyperbolic trigonometry functions.

InverseTrigonometryTrait

namespace
Samsara\Fermat\Types\Traits\Decimal
satisfies
DecimalInterface (partially)

The InverseTrigonometryTrait provides the implementations for all inverse trigonometric functions, sometimes referred to as "arc functions". These are sometimes abbreviated in programming languages as a, such as atan which is equivalent to arctan which is equivalent to inverseTangent.

LogTrait

namespace
Samsara\Fermat\Types\Traits\Decimal
satisfies
DecimalInterface (partially)

The LogTrait provides the implementations for the log, ln, and exp functions.

ScaleTrait

namespace
Samsara\Fermat\Types\Traits\Decimal
satisfies
DecimalInterface (partially)

The ScaleTrait provides the implementations for all rounding and truncating functions for classes which implement DecimalInterface.

Constructor

__construct(mixed $value, int $scale = 10, int $base = 10)

$value
The value to create the instance with
$scale
The maximum number of digits after the decimal that the instance can have
$base
The base of the instance created
return
An instance of Decimal created with the provided arguments as parameters

The constructor will take an integer, a float, or any numeric string (including imaginary values) as its input value. The scale and base must be given as integers, and can be omitted where they will take their default values of 10. This means that by default instances of Decimal will be in base-10 and calculate 10 digits of scale for all operations.

You Might Not Expect

If an instance of Decimal is provided, it will be treated as a string and will construct correctly. However, it will not inherit the $scale or $base settings for the instance provided as a $value.

Warning

If the instance provided is in a base other than 10, the $base provided to the constructor should match that value, or you will eventually get exceptions and potentially PHP fatals.

Danger

Providing an instance of Fraction or ComplexNumber will appear to build the new instance correctly, but will result in a PHP fatal error on calls to any methods on the new instance.

ImmutableNumber

A number which can be represented as a decimal and has a maximum scale of 2632^{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.

MutableNumber

A number which can be represented as a decimal and has a maximum scale of 2632^{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.

Values of Fraction

Used to represent numbers in a fraction format. The / character is used in string representations to denote the fraction bar, and is used to create instances from strings. In these cases, it is assumed that the numerator is to the left of the fraction bar, and the denominator is the right.

The numerator and denominator must also be whole numbers. If a mathematical operation results in non-whole values for either the numerator or denominator, the Fraction is converted to a Decimal using the asDecimal() method on the FractionInterface.

These classes extend the Fraction abstract class, which comes with the following interfaces, traits, and constructor.

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.

FractionInterface

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

The FractionInterface extends SimpleNumberInterface and adds the methods that are common to all fraction values. This includes simplify(), accessors for the numerator and denominator, and the asDecimal() method that returns the Fraction as an instance of DecimalInterface.

ImmutableDecimals Are Returned From asDecimal()

While the interface only defines the DecimalInterface as a return value, the concrete classes returned by all included implementations are instances of ImmutableDecimal.

While some other functions 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.

See Also

The page for Types & Values > Decimals contains more information on the usage of Decimal values.

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.

See Also

More detailed information on this trait is available on the Arithmetic > Simple Numbers page.

ComparisonTrait

namespace
Samsara\Fermat\Types\Traits
satisfies
SimpleNumberInterface (partially)

The ComparisonTrait provides the implementations of all comparison methods for any class which implements the SimpleNumberInterface.

Constructor

__construct(mixed $numerator, mixed $denominator, $base = 10)

$numerator
The value of the numerator, using the same restrictions as Decimal
$denominator
The value of the denominator, using the same restrictions as Decimal
$base
The base of the instance created
return
An instance of Fraction created with the provided arguments as parameters

The constructor will take an integer, a float, any numeric string, or an instance of DecimalInterface as its input value. The base must be given as an integer, and if omitted it will take the default value of 10. This means that by default instances of Fraction will be in base-10.

Rounding

In the constructor, non-integer values for the numerator or denominator are automatically rounded to the nearest integer using the "half up" method.

Type Coercion

If an instance implementing DecimalInterface is provided, it will be coerced into an ImmutableDecimal. This will leave the original instance unaffected by operations performed on the Fraction, even if an instance of MutableDecimal was originally provided.

ImmutableFraction

A number which can be represented as a fraction. 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.

MutableFraction

A number which can be represented as a fraction. 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.

Values of ComplexNumber

Used to represent complex number values. Either part can be an instance of FractionInterface or DecimalInterface, however while Decimal values can be provided as an object, a string, an integer, or a float, you must explicitly provide an instance of Fraction if you wish for one of the components to be in that format.

Unexpected Class Inheritance Structure

While the name of this class is ComplexNumber, it does not extend the abstract Number class like Fraction and Decimal do. Instead, it extends PolarCoordinate, since this is an advantageous representation of complex numbers in many situations.

The arguments to the ComplexNumber class correspond directly with a set of CartesianCoordinates. These are then transformed into an instance of PolarCoordinate which is a more useful form for doing operations like pow() and sqrt().

Interfaces

ComplexNumberInterface

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

This interface is meant to be implemented by an object which extends PolarCoordinate, since all complex numbers can be represented in that way and there are advantages to doing so.

CoordinateInterface

namespace
Samsara\Fermat\Types\Base\Interfaces\Coordinates
extends
TwoDCoordinateInterface

This interface provides the base methods available to all coordinate systems. This includes the asCartesian() method, since any type of coordinate system in a Euclidean space can be represented by cartesian coordinates. Non-Euclidean spaces are unsupported in Fermat.

Traits

ArithmeticComplexTrait

namespace
Samsara\Fermat\Types\Traits
uses
  • ArithmeticScaleTrait
  • ArithmeticNativeTrait
  • ArithmeticSelectionTrat
satisfies
ComplexNumberInterface (partially)

The ArithmeticComplexTrait provides the implementations for all arithmetic functions that exist on values that implement the ComplexNumberInterface. 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 Simple Numbers as Arguments

While the ArithmeticComplexTrait can accept implementations of SimpleNumberInterface as arguments, it cannot be used in implementations of SimpleNumberInterface.

See Also

More detailed information on this trait is available on the Arithmetic > Complex Numbers page.

Constructor

__construct(mixed $realPart, mixed $imaginaryPart, ?int $scale = null, int $base = 10)

$realPart
The value of the real part; can be an instance of FractionInterface, and instance of DecimalInterface, or a scalar using the same restrictions as Decimal
$imaginaryPart
The value of the imaginary part; can be an instance of FractionInterface, and instance of DecimalInterface, or a scalar using the same restrictions as Decimal
$scale
The maximum number of digits after the decimal that the instance components can have
$base
The base of the instance created
return
An instance of ComplexNumber created with the provided arguments as parameters

ImmutableComplexNumber

A number which can be represented as a complex number. 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.

MutableComplexNumber

A number which can be represented as a complex number. 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.

Values of Matrix

Used to represent mathematical matrices and perform matrix math.

Interfaces

Traits

Constructor

__construct(array $data, string $mode = Matrix::MODE_ROWS_INPUT)

$data
An array of NumberCollections, defining either the rows or the columns of the matrix; see below for more detailed information
$mode
Accepts either the string 'rows' or 'columns', defining whether the number in $data are organized as an array of rows or an array of columns
return
An instance of Matrix created with the provided arguments as parameters

The input array has several restrictions and assumptions. The most obvious, given that it is meant to represent matrix data, is that each NumberCollection in the provided array must contain the same number of elements.

Further, while the data can represent either the array of rows or array of columns depending on the $mode provided, it will always fill the matrix starting from the upper left corner. This is also the same indexing used by getRow(), getColumn(), or any other function that references a row or column index.

ImmutableMatrix

MutableMatrix

Values of Coordinate

The specific interfaces, traits, and constructor for the different values of Coordinate depend on the value class used. This information is detailed in the Types & Values > Coordinates documenation.

Coordinates Are Mutable

Unlike many other values, all implementations of Coordinate are designed as mutable classes. This design decision was made mainly because of how coordinates are usually used in math.

Typically, when an operation of some kind is performed on a coordinate, the resulting coordinate is treated as the only existant value, and previous coordinate is removed from the data set. Mutable implementations mirror this behavior.

However, the underlying Decimal values that represent that coordinate components are instances of ImmutableDecimal. This means that while the coordinate instances will be mutable, and decimal instances used as input for the coordinates will remain unaffected.

CartesianCoordinate

A set of coordinates where each value represents the position along a single plane. These are the coordinates that are most commonly used in algebra and geometry, typically presented in format (x, y) for two-dimensional coordinates, and (x, y, z) for three-dimensional coordinates.

CylindricalCoordinate

A set of three-dimensional coordinates represented by (r, θ\theta, z), where (r, θ\theta) are the polar coordinates of the xy-plane, and (z) is the normal z-coordinate in a Cartesian coordinate representation.

Comparison of Cartesian and Cylindrical Coordinates

This image is licensed under CC-BY-NC-SA-4.0 and was created by Gilbert Strang & Edwin “Jed” Herman

PolarCoordinate

A set of two-dimensional coordinates represented by (r, θ\theta), where (r) is the distance to the origin, and (θ\theta) is the angle in radians from the positive x-axis.

SphericalCoordinate

A set of three-dimensional coordinates represented by (ρ\rho, θ\theta, φ\varphi), where (ρ\rho) is the distance to the origin, (θ\theta) is the angle in radians from the positive x-axis in the xy-plane, and (φ\varphi) is the angle in radians from the positive z-axis to the line formed by (ρ\rho).

Comparison of Cartesian and Spherical Coordinates

This image is licensed under CC-BY-NC-SA-4.0 and was created by Gilbert Strang & Edwin “Jed” Herman