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
NumberInterface
BaseConversionInterface
SimpleNumberInterface
DecimalInterface
Traits
ArithmeticSimpleTrait
ArithmeticSelectionTrait
ArithmeticScaleTrait
ArithmeticNativeTrait
ComparisonTrait
IntegerMathTrait
TrigonometryTrait
InverseTrigonometryTrait
LogTrait
ScaleTrait
__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
NumberInterface
BaseConversionInterface
SimpleNumberInterface
FractionInterface
Traits
ArithmeticSimpleTrait
ArithmeticSelectionTrait
ArithmeticScaleTrait
ArithmeticNativeTrait
ComparisonTrait
__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.
__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
__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