src/Samsara/Fermat/Core/Numbers.php
<?php
namespace Samsara\Fermat\Core;
use Samsara\Exceptions\UsageError\IntegrityConstraint;
use Samsara\Fermat\Core\Enums\NumberBase;
use Samsara\Fermat\Core\Provider\ConstantProvider;
use Samsara\Fermat\Core\Types\Base\Number;
use Samsara\Fermat\Core\Types\Decimal;
use Samsara\Fermat\Core\Types\Fraction;
use Samsara\Fermat\Core\Values\ImmutableDecimal;
use Samsara\Fermat\Core\Values\ImmutableFraction;
use Samsara\Fermat\Core\Values\MutableDecimal;
use Samsara\Fermat\Core\Values\MutableFraction;
/**
* This class contains useful factory methods to create various numbers, verify the
* class of a given number, and generally handle all of the formatting necessary to
* satisfy the various constructors of valid value objects.
*
* @package Samsara\Fermat\Core
*/
class Numbers
{
public const MUTABLE = MutableDecimal::class;
public const IMMUTABLE = ImmutableDecimal::class;
public const MUTABLE_FRACTION = MutableFraction::class;
public const IMMUTABLE_FRACTION = ImmutableFraction::class;
/* 105 digits after decimal, which is going to be overkill in almost all places */
public const PI = '3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679';
/* Tau (2pi) to 100 digits */
public const TAU = '6.2831853071795864769252867665590057683943387987502116419498891846156328125724179972560696506842341359';
/* Euler's Number to 100 digits */
public const E = '2.718281828459045235360287471352662497757247093699959574966967627724076630353547594571382178525166427';
/* Golden Ratio to 100 digits */
public const GOLDEN_RATIO = '1.618033988749894848204586834365638117720309179805762862135448622705260462818902449707207204189391137';
/* Natural log of 10 to 100 digits */
public const LN_10 = '2.302585092994045684017991454684364207601101488628772976033327900967572609677352480235997205089598298';
/* Natural log of 2 to 100 digits */
public const LN_2 = '0.693147180559945309417232121458176568075500134360255254120680009493393621969694715605863326996418687';
/* The value of i^i */
public const I_POW_I = '0.2078795763507619085469556198349787700338778416317696080751358830554198772854821397886002778654260353';
/* Euler-Mascheroni Constant */
public const E_M = '0.5772156649015328606065120900824024310421593359399235988057672348848677267776646709369470632917467495';
/**
* This class will make and return an instance of a concrete value.
*
* The main reason for this class is that you can pass an unknown value instance as the
* $type parameter and it will behave as if you passed the FQCN.
*
* @param mixed $type An instance of FQCN for any Fermat value class.
* @param mixed $value Any value which is valid for the constructor which will be called.
* @param int|null $scale The scale setting the created instance should have.
* @param NumberBase $base The base to create the number in. Note, this is not the same as the base of $value, which is always base-10
*
* @return ImmutableDecimal|MutableDecimal|ImmutableFraction|MutableFraction|Fraction|Decimal
* @throws IntegrityConstraint
*/
public static function make(mixed $type, mixed $value, ?int $scale = null, NumberBase $base = NumberBase::Ten)
{
if (is_object($type)) {
$type = get_class($type);
}
if ($type === static::IMMUTABLE) {
return new ImmutableDecimal(trim($value), $scale, $base, true);
}
if ($type === static::MUTABLE) {
return new MutableDecimal(trim($value), $scale, $base, true);
}
if ($type === static::IMMUTABLE_FRACTION) {
return self::makeFractionFromString($type, $value, $base);
}
if ($type === static::MUTABLE_FRACTION) {
return self::makeFractionFromString($type, $value, $base);
}
throw new IntegrityConstraint(
'$type must be an implemented concrete class that is supported',
'Provide a type that Decimal',
'The $type argument was not an instance of Decimal'
);
}
/**
* @param int|null $scale
*
* @return ImmutableDecimal
* @throws IntegrityConstraint
*/
public static function make2Pi(int $scale = null): ImmutableDecimal
{
return self::makeTau($scale);
}
/**
* @param int|null $scale
*
* @return ImmutableDecimal
* @throws IntegrityConstraint
*/
public static function makeE(int $scale = null): ImmutableDecimal
{
return self::makeConstant(self::E, $scale);
}
public static function makeEulerMascheroni(?int $scale = null): ImmutableDecimal
{
return self::makeConstant(self::E_M, $scale);
}
/**
* @param string $type
* @param string $value
* @param NumberBase $base
*
* @return ImmutableFraction|MutableFraction|Fraction
* @throws IntegrityConstraint
*/
public static function makeFractionFromString(string $type, string $value, NumberBase $base = NumberBase::Ten): ImmutableFraction|MutableFraction|Fraction
{
$parts = explode('/', $value);
if (count($parts) > 2) {
throw new IntegrityConstraint(
'Only one division symbol (/) can be used',
'Change the calling code to not provide more than one division symbol',
'makeFractionFromString needs either one or zero division symbols in the $value argument; ' . $value . ' given'
);
}
/** @var ImmutableDecimal $numerator */
$numerator = self::make(self::IMMUTABLE, trim($parts[0]));
/** @var ImmutableDecimal $denominator */
$denominator = isset($parts[1]) ? self::make(self::IMMUTABLE, trim($parts[1])) : self::makeOne();
if ($type === self::IMMUTABLE_FRACTION) {
return new ImmutableFraction($numerator, $denominator, $base);
}
if ($type === self::MUTABLE_FRACTION) {
return new MutableFraction($numerator, $denominator, $base);
}
throw new IntegrityConstraint(
'Type must be an implementation of Fraction',
'Alter to calling code to use the correct type',
'makeFractionFromString can only make objects which implement the Fraction; ' . $type . ' given'
);
}
/**
* @param $type
* @param $value
* @param int|null $scale
* @param NumberBase $base
*
* @return Decimal
* @throws IntegrityConstraint
*/
public static function makeFromBase10($type, $value, ?int $scale = null, NumberBase $base = NumberBase::Ten): Decimal
{
/**
* @var ImmutableDecimal|MutableDecimal $number
*/
$number = self::make($type, $value, $scale);
return $number->setBase($base);
}
/**
* @param int|null $scale
*
* @return ImmutableDecimal
* @throws IntegrityConstraint
*/
public static function makeGoldenRatio(?int $scale = null): ImmutableDecimal
{
return self::makeConstant(self::GOLDEN_RATIO, $scale);
}
/**
* @param int|null $scale
*
* @return ImmutableDecimal
* @throws IntegrityConstraint
*/
public static function makeNaturalLog10(?int $scale = null): ImmutableDecimal
{
return self::makeConstant(self::LN_10, $scale);
}
/**
* @param int|null $scale
*
* @return ImmutableDecimal
* @throws IntegrityConstraint
*/
public static function makeNaturalLog2(?int $scale = null): ImmutableDecimal
{
return self::makeConstant(self::LN_2, $scale);
}
/**
* @param int|null $scale
*
* @return ImmutableDecimal
* @throws IntegrityConstraint
*/
public static function makeOne(?int $scale = null): ImmutableDecimal
{
return new ImmutableDecimal(1, $scale);
}
/**
* @param string|object $type
* @param int|float|string|array|Decimal|Fraction $value
* @param int|null $scale
* @param NumberBase $base
*
* @return ImmutableDecimal|MutableDecimal|Decimal|ImmutableDecimal[]|MutableDecimal[]|Decimal[]
* @throws IntegrityConstraint
*/
public static function makeOrDont(string|object $type, mixed $value, ?int $scale = null, NumberBase $base = NumberBase::Ten)
{
if (is_object($value)) {
if ($value instanceof $type) {
return $value;
}
if ($value instanceof Number) {
return static::make($type, $value->getValue(NumberBase::Ten), $scale, $base);
}
} elseif (is_array($value)) {
$newInput = [];
foreach ($value as $key => $item) {
$newInput[$key] = static::makeOrDont($type, $item, $scale, $base);
}
return $newInput;
} elseif (is_string($value) || is_int($value) || is_float($value)) {
$isImaginary = str_contains($value, 'i');
if (is_numeric($value) || $isImaginary) {
return static::make($type, $value, $scale, $base);
}
}
throw new IntegrityConstraint(
'$input must be an int, float, numeric string, or an implementation of Decimal',
'Provide any of the MANY valid inputs',
'The $input argument was not numeric or an implementation of Decimal. Given value: ' . $value
);
}
/**
* @param int|null $scale
*
* @return ImmutableDecimal
* @throws IntegrityConstraint
*/
public static function makePi(int $scale = null): ImmutableDecimal
{
return self::makeConstant(self::PI, $scale);
}
/**
* @param null $scale
*
* @return ImmutableDecimal
* @throws IntegrityConstraint
*/
public static function makeTau($scale = null): ImmutableDecimal
{
if (!is_null($scale)) {
if ($scale < 1) {
throw new IntegrityConstraint(
'$scale must be at least 1',
'Provide a scale within range',
'The E constant cannot have a scale less than 1'
);
}
if ($scale > 100) {
$pi = new ImmutableDecimal(ConstantProvider::makePi($scale + 2), $scale + 2);
/** @var ImmutableDecimal */
return $pi->multiply(2)->truncateToScale($scale);
}
return (new ImmutableDecimal(self::TAU, $scale + 1))->truncateToScale($scale);
}
return new ImmutableDecimal(self::TAU, 100);
}
/**
* @param int|null $scale
*
* @return ImmutableDecimal
* @throws IntegrityConstraint
*/
public static function makeZero(?int $scale = null): ImmutableDecimal
{
return new ImmutableDecimal(0, $scale);
}
private static function makeConstant(string $constant, ?int $scale): ImmutableDecimal
{
if (!is_null($scale)) {
if ($scale < 1) {
throw new IntegrityConstraint(
'Scale must be at least 1',
'Provide a scale within range',
'Cannot create a constant with a scale less than 1'
);
}
if ($scale > 100) {
return new ImmutableDecimal(
match ($constant) {
self::LN_2 => ConstantProvider::makeLn2($scale),
self::LN_10 => ConstantProvider::makeLn10($scale),
self::GOLDEN_RATIO => ConstantProvider::makeGoldenRatio($scale),
self::E => ConstantProvider::makeE($scale),
self::PI => ConstantProvider::makePi($scale),
self::E_M => self::E_M
},
$scale
);
}
return (new ImmutableDecimal(
$constant,
$scale + 1
))->truncateToScale($scale);
}
return new ImmutableDecimal(
$constant,
100
);
}
}