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 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 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 CartesianCoordinate
s. 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, , z), where (r, ) are the polar coordinates of the xy-plane, and (z) is the normal z-coordinate in a Cartesian coordinate representation.
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, ), where (r) is the distance to the origin, and () is the angle in radians from the positive x-axis.
SphericalCoordinate
A set of three-dimensional coordinates represented by (, , ), where () is the distance to the origin, () is the angle in radians from the positive x-axis in the xy-plane, and () is the angle in radians from the positive z-axis to the line formed by ().
This image is licensed under CC-BY-NC-SA-4.0 and was created by Gilbert Strang & Edwin “Jed” Herman