#Numbers

Phuture\Coherence\Numbers

class Numbers extends StaticClass

Comprehensive number manipulation utility class with precise arithmetic and formatting.

This utility class provides a complete toolkit for working with numbers, combining float comparison with epsilon tolerance, precise arithmetic via BCMath, number formatting, and human-readable output into a single cohesive interface.

Key features:

• BCMath Comparison: Compare numbers with BCMath precision to avoid floating-point errors
• Precise Arithmetic: Add, subtract, multiply, divide, and compute modulus using BCMath strings
• State & Validation: Check if a number is zero, positive, negative, or an integer
• Clamping & Limits: Constrain numbers to a minimum, maximum, or both
• Formatting: Abbreviate numbers, format file sizes, percentages, ordinals, and more
• Human-Readable Output: Convert numbers into readable strings like "1.5K" or "2.5 MB"
• Unit Conversion: Convert between units of temperature, distance, mass, volume, time, area, speed, pressure, energy, power, force, electric potential, electric current, and luminosity
• Statistical Functions: Compute mean, median, mode, variance, standard deviation, and percentiles

#Constants

#DEFAULT_SCALE

const DEFAULT_SCALE = 10

Number of decimal places used by default in BCMath arithmetic operations.

#MAX_PRECISION

const MAX_PRECISION = 100

Highest number of decimal places accepted by the formatting methods.

Formatting with an arbitrarily large precision allocates a string of that length, which exhausts memory long before the result is useful. PHP 8.6 rejects out-of-range values outright, so the limit is enforced here to keep the behaviour identical across versions.

#Methods

#abbreviate()

public static function abbreviate(int|float|string $number, int $precision = 1): string

Abbreviates a number using suffix letters (K, M, B, T).

Converts large numbers into shorter human-readable strings by dividing the value and appending a suffix. For example, 1500 becomes "1.5K".

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::abbreviate(1500); // '1.5K'
4Numbers::abbreviate(1000000); // '1.0M'
5Numbers::abbreviate(123456789); // '123.5M'
6Numbers::abbreviate(1500, 2); // '1.50K'

Returns string — The abbreviated number string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $precision is negative or greater than MAX_PRECISION

See also

• \Phuture\Coherence\Numbers::forHumans()

#absolute()

public static function absolute(int|float|string $number): int|float|string

Returns the absolute (non-negative) value of a number.

Converts negative numbers to their positive equivalent. Positive numbers and zero are returned unchanged.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::absolute(-5); // 5
4Numbers::absolute(3.14); // 3.14
5Numbers::absolute(0); // 0

Returns int|float|string — The non-negative value of the number

See also

• \Phuture\Coherence\Numbers::opposite()

#add()

public static function add(int|float|string $left, int|float|string $right): string

Adds two numbers using BCMath for precision and returns the result as a string.

Both values are converted to strings and added using BCMath to avoid floating-point precision loss.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::add(0.1, 0.2); // '0.3000000000'
4Numbers::add(100, 200); // '300.0000000000'
5Numbers::add(1.5, 2.5); // '4.0000000000'

Returns string — The sum as a string

See also

• \Phuture\Coherence\Numbers::subtract()

#addPercentage()

public static function addPercentage(int|float|string $number, int|float|string $percentage): string

Increases a number by a given percentage and returns the result.

Computes the percentage of the number and adds it to the original value using BCMath to avoid floating-point precision loss.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::addPercentage(100, 20); // '120.0000000000'  (100 + 20%)
4Numbers::addPercentage(50, 10); // '55.0000000000'   (50 + 10%)
5Numbers::addPercentage(200, 5); // '210.0000000000'  (200 + 5%)

Returns string — The increased value as a BCMath string

See also

• \Phuture\Coherence\Numbers::subtractPercentage()
• \Phuture\Coherence\Numbers::percentage()
• \Phuture\Coherence\Numbers::add()

#areEqual()

public static function areEqual(int|float|string $left, int|float|string $right): bool

Determines whether two numbers are equal at BCMath precision.

Compares two numbers using BCMath at the default scale.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::areEqual(0.1 + 0.2, 0.3); // true
4Numbers::areEqual(10, 10.0); // true
5Numbers::areEqual(1.0, 2.0); // false

Returns bool — True when both values are equal at BCMath precision

Throws

• \Phuture\Coherence\Exception\LogicException — When either value is NAN

See also

• \Phuture\Coherence\Numbers::compare()
• \Phuture\Coherence\Numbers::isZero()

#ceil()

public static function ceil(int|float|string $number): string

Returns the smallest integer value greater than or equal to the given number.

Rounds up to the nearest integer using BCMath for precision. For example, 3.2 becomes "4" and -3.2 becomes "-3".

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::ceil(3.2); // '4'
4Numbers::ceil(-1.1); // '-1'
5Numbers::ceil(5.0); // '5'

Returns string — The smallest integer greater than or equal to the number as a BCMath string

See also

• \Phuture\Coherence\Numbers::floor()
• \Phuture\Coherence\Numbers::round()

#celsiusToFahrenheit()

public static function celsiusToFahrenheit(string $value): string

Converts a Celsius temperature to Fahrenheit using BCMath for precision.

Applies the formula: Fahrenheit = (Celsius / 5) * 9 + 32

Example:

1use Phuture\Coherence\Numbers;
2
3$fahrenheit = Numbers::celsiusToFahrenheit('100');
4
5// Returns: '212.0000000000'

Returns string — The Fahrenheit temperature as a BCMath string

See also

• \Phuture\Coherence\Numbers::fahrenheitToCelsius()

#celsiusToRankine()

public static function celsiusToRankine(string $value): string

Converts a Celsius temperature to Rankine using BCMath for precision.

Applies the formula: Rankine = (Celsius / 5) * 9 + 491.67

Example:

1use Phuture\Coherence\Numbers;
2
3$rankine = Numbers::celsiusToRankine('100');
4
5// Returns: '671.6700000000'

Returns string — The Rankine temperature as a BCMath string

See also

• \Phuture\Coherence\Numbers::rankineToCelsius()

#clamp()

public static function clamp(int|float|string $number, int|float|string $min, int|float|string $max): int|float|string

Restricts a number to be within the given minimum and maximum bounds.

When the number is below $min, $min is returned. When the number is above $max, $max is returned. Otherwise, the number itself is returned.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::clamp(5, 1, 10); // 5
4Numbers::clamp(-3, 0, 100); // 0
5Numbers::clamp(150, 0, 100); // 100

Returns int|float|string — The clamped value

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When min is greater than max

See also

• \Phuture\Coherence\Numbers::max()
• \Phuture\Coherence\Numbers::min()

#compare()

public static function compare(int|float|string $left, int|float|string $right): int

Compares two numbers and returns their relative order.

Returns -1 when $a is less than $b, 0 when they are equal at BCMath precision, and 1 when $a is greater than $b. Suitable for use with sorting functions like usort().

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::compare(1.0, 2.0); // -1
4Numbers::compare(2.0, 1.0); // 1
5Numbers::compare(1.0, 1.0); // 0
6
7$arr = [3, 1, 2];
8usort($arr, [Numbers::class, 'compare']); // [1, 2, 3]

Returns int — -1 when $left < $right, 0 when equal, 1 when $left > $right

Throws

• \Phuture\Coherence\Exception\LogicException — When either value is NAN

See also

• \Phuture\Coherence\Numbers::areEqual()

#conversionUnits()

public static function conversionUnits(): array

Returns all supported units grouped by measurement category.

This method returns an associative array where each key is a measurement category name and the value is an array of Unit enum cases that belong to that category. This is useful for building user interfaces that let users pick units from a dropdown.

Example:

1use Phuture\Coherence\Numbers;
2
3$units = Numbers::conversionUnits();
4// Returns: [
5//     'temperature' => [Unit::Celsius, Unit::Fahrenheit, ...],
6//     'distance' => [Unit::Meter, Unit::Millimeter, ...],
7//     ...
8// ]

Returns array — An associative array mapping category names to arrays of Unit enum cases

See also

• \Phuture\Coherence\Enum\Unit
• \Phuture\Coherence\Numbers::convert()

#convert()

public static function convert(int|float|string $value, Unit $from, Unit $to): string

Converts a numeric value from one unit of measurement to another.

This method converts a value between units within the same measurement category. Both units must belong to the same category (for example, both must be temperature units or both must be distance units). The conversion uses BCMath for precise decimal arithmetic.

Use the Unit enum to specify the source and target units. See \Phuture\Coherence\Enum\Unit for the full list of supported units organized by category (temperature, distance, mass, volume, time, area, speed, pressure, energy, power, force, electric potential, electric current, and luminous intensity).

Example:

 1use Phuture\Coherence\Enum\Unit;
 2use Phuture\Coherence\Numbers;
 3
 4Numbers::convert(100, Unit::Celsius, Unit::Fahrenheit);
 5// Returns: '212.0000000000'
 6
 7Numbers::convert(1, Unit::Kilometer, Unit::Mile);
 8// Returns: '0.6213711922'
 9
10Numbers::convert(1, Unit::GallonUs, Unit::Liter);
11// Returns: '3.7854117840'

Returns string — The converted value as a BCMath string with up to 10 decimal places

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When units belong to different categories

See also

• \Phuture\Coherence\Enum\Unit — For all available unit cases
• \Phuture\Coherence\Type\Numbers::convert() — For the fluent equivalent

#divide()

public static function divide(int|float|string $dividend, int|float|string $divisor): string

Divides the first number by the second using BCMath for precision.

Both values are converted to strings and divided using BCMath to avoid floating-point precision loss. Throws when dividing by zero.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::divide(10, 3); // '3.3333333333'
4Numbers::divide(100, 4); // '25.0000000000'
5Numbers::divide(1, 3); // '0.3333333333'

Returns string — The quotient as a string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the divisor is zero

See also

• \Phuture\Coherence\Numbers::multiply()

#fahrenheitToCelsius()

public static function fahrenheitToCelsius(string $value): string

Converts a Fahrenheit temperature to Celsius using BCMath for precision.

Applies the formula: Celsius = (Fahrenheit - 32) * 5 / 9

Example:

1use Phuture\Coherence\Numbers;
2
3$celsius = Numbers::fahrenheitToCelsius('212');
4
5// Returns: '100.0000000000'

Returns string — The Celsius temperature as a BCMath string

See also

• \Phuture\Coherence\Numbers::celsiusToFahrenheit()

#fileSize()

public static function fileSize(int|float|string $bytes, int $precision = 0, ByteBase $base = ByteBase::Binary): string

Converts a byte count into a human-readable file size string.

Expresses the byte count using the largest appropriate unit (B, KB, MB, GB, TB, PB). Uses base 1024 by default (binary prefixes). Use base 1000 for decimal prefixes.

Example:

1use Phuture\Coherence\Numbers;
2use Phuture\Coherence\Enum\ByteBase;
3
4Numbers::fileSize(500); // '500 B'
5Numbers::fileSize(1024); // '1 KB'
6Numbers::fileSize(1048576); // '1 MB'
7Numbers::fileSize(1073741824); // '1 GB'
8Numbers::fileSize(1500, 2); // '1.46 KB'
9Numbers::fileSize(1000, 0, ByteBase::Decimal); // '1 KB'

Returns string — The human-readable file size string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $precision is negative or greater than MAX_PRECISION

See also

• \Phuture\Coherence\Numbers::forHumans()
• \Phuture\Coherence\Enum\ByteBase

#floor()

public static function floor(int|float|string $number): string

Returns the largest integer value less than or equal to the given number.

Rounds down to the nearest integer using BCMath for precision. For example, 3.8 becomes "3" and -3.8 becomes "-4".

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::floor(3.8); // '3'
4Numbers::floor(-1.1); // '-2'
5Numbers::floor(5.0); // '5'

Returns string — The largest integer less than or equal to the number as a BCMath string

See also

• \Phuture\Coherence\Numbers::ceil()
• \Phuture\Coherence\Numbers::round()

#forHumans()

public static function forHumans(int|float|string $number, int $precision = 1): string

Converts a number into a human-readable string with unit suffixes.

Similar to abbreviate() but uses full unit names instead of suffix letters. For example, 1500 becomes "1.5 thousand".

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::forHumans(1500); // '1.5 thousand'
4Numbers::forHumans(1000000); // '1.0 million'
5Numbers::forHumans(1234, 2); // '1.23 thousand'

Returns string — The human-readable number string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $precision is negative or greater than MAX_PRECISION

See also

• \Phuture\Coherence\Numbers::abbreviate()

#format()

public static function format(int|float|string $number, ?int $precision = null): string

Formats a number with grouped thousands and a specified number of decimal places.

Wraps PHP's number_format() to produce locale-independent formatted strings. When $precision is null, the original precision of the number is preserved.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::format(1234567.8912, 2); // '1,234,567.89'
4Numbers::format(1234567, 0); // '1,234,567'
5Numbers::format(1234.5678, 4); // '1,234.5678'

Returns string — The formatted number string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $precision is explicitly given and is negative or greater than MAX_PRECISION

See also

• \Phuture\Coherence\Numbers::formatPercentage()
• \Phuture\Coherence\Numbers::abbreviate()

#formatPercentage()

public static function formatPercentage(int|float|string $number, int $precision = 1, int $multiplicand = 100): string

Converts a number into a human-readable percentage string.

Multiplies the number by the given multiplicand (default 100) and appends the percent sign. Useful for displaying ratios as percentages.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::formatPercentage(0.75); // '75.0%'
4Numbers::formatPercentage(0.75, 2); // '75.00%'
5Numbers::formatPercentage(1.5, 1); // '150.0%'

Returns string — The formatted percentage string with a percent sign

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $precision is negative or greater than MAX_PRECISION

See also

• \Phuture\Coherence\Numbers::format()
• \Phuture\Coherence\Numbers::percentage()
• \Phuture\Coherence\Numbers::addPercentage()
• \Phuture\Coherence\Numbers::subtractPercentage()

#isFloat()

public static function isFloat(int|float|string $value): bool

Determines whether a value is a floating-point number (has a fractional part).

Returns true when the value is a finite float that is not a whole number. Integer values, infinity, and NAN return false. This is the logical inverse of isInteger() for finite numeric values.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::isFloat(3.14); // true
4Numbers::isFloat(0.5); // true
5Numbers::isFloat(5); // false
6Numbers::isFloat(5.0); // false
7Numbers::isFloat(INF); // false

Returns bool — True when the value is a float with a fractional part

See also

• \Phuture\Coherence\Numbers::isInteger()

#isGreaterThan()

public static function isGreaterThan(int|float|string $left, int|float|string $right): bool

Determines whether a number is greater than another at BCMath precision.

Returns true when $left is strictly greater than $right.

Throws a \Phuture\Coherence\Exception\LogicException when either value is NAN.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::isGreaterThan(10.0, 5.0); // true
4Numbers::isGreaterThan(5.0, 10.0); // false
5Numbers::isGreaterThan(10.0, 10.0); // false

Returns bool — True when $left is strictly greater than $right

Throws

• \Phuture\Coherence\Exception\LogicException — When either value is NAN

See also

• \Phuture\Coherence\Numbers::isGreaterThanOrEqualTo()
• \Phuture\Coherence\Numbers::isLessThan()

#isGreaterThanOrEqualTo()

public static function isGreaterThanOrEqualTo(int|float|string $left, int|float|string $right): bool

Determines whether a number is greater than or equal to another at BCMath precision.

Returns true when $left is greater than or equal to $right.

Throws a \Phuture\Coherence\Exception\LogicException when either value is NAN.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::isGreaterThanOrEqualTo(10.0, 5.0); // true
4Numbers::isGreaterThanOrEqualTo(10.0, 10.0); // true
5Numbers::isGreaterThanOrEqualTo(5.0, 10.0); // false

Returns bool — True when $left is greater than or equal to $right

Throws

• \Phuture\Coherence\Exception\LogicException — When either value is NAN

See also

• \Phuture\Coherence\Numbers::isGreaterThan()
• \Phuture\Coherence\Numbers::isLessThanOrEqualTo()

#isInteger()

public static function isInteger(int|float|string $value): bool

Determines whether a number is an integer (has no fractional part).

Returns true when the value is a whole number with no decimal component. Returns false for infinity and NAN.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::isInteger(5); // true
4Numbers::isInteger(5.0); // true
5Numbers::isInteger(-3.0); // true
6Numbers::isInteger(3.14); // false
7Numbers::isInteger(INF); // false

Returns bool — True when the value has no fractional part

See also

• \Phuture\Coherence\Numbers::isZero()

#isLessThan()

public static function isLessThan(int|float|string $left, int|float|string $right): bool

Determines whether a number is less than another at BCMath precision.

Returns true when $left is strictly less than $right.

Throws a \Phuture\Coherence\Exception\LogicException when either value is NAN.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::isLessThan(5.0, 10.0); // true
4Numbers::isLessThan(10.0, 5.0); // false
5Numbers::isLessThan(10.0, 10.0); // false

Returns bool — True when $left is strictly less than $right

Throws

• \Phuture\Coherence\Exception\LogicException — When either value is NAN

See also

• \Phuture\Coherence\Numbers::isLessThanOrEqualTo()
• \Phuture\Coherence\Numbers::isGreaterThan()

#isLessThanOrEqualTo()

public static function isLessThanOrEqualTo(int|float|string $left, int|float|string $right): bool

Determines whether a number is less than or equal to another at BCMath precision.

Returns true when $left is less than or equal to $right.

Throws a \Phuture\Coherence\Exception\LogicException when either value is NAN.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::isLessThanOrEqualTo(5.0, 10.0); // true
4Numbers::isLessThanOrEqualTo(10.0, 10.0); // true
5Numbers::isLessThanOrEqualTo(15.0, 10.0); // false

Returns bool — True when $left is less than or equal to $right

Throws

• \Phuture\Coherence\Exception\LogicException — When either value is NAN

See also

• \Phuture\Coherence\Numbers::isLessThan()
• \Phuture\Coherence\Numbers::isGreaterThanOrEqualTo()

#isNegative()

public static function isNegative(int|float|string $number): bool

Determines whether a number is negative (strictly less than zero).

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::isNegative(-5); // true
4Numbers::isNegative(-0.1); // true
5Numbers::isNegative(0); // false
6Numbers::isNegative(3); // false

Returns bool — True when the number is strictly less than zero

See also

• \Phuture\Coherence\Numbers::isPositive()
• \Phuture\Coherence\Numbers::isZero()

#isNumber()

public static function isNumber(mixed $value): bool

Determines whether a value is a valid numeric representation.

Accepts integers, floats, and numeric strings. Returns false for non-numeric strings, NAN, infinity, arrays, objects, and null.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::isNumber(42); // true
4Numbers::isNumber(3.14); // true
5Numbers::isNumber('100'); // true
6Numbers::isNumber('abc'); // false
7Numbers::isNumber(null); // false

Returns bool — True when the value is a valid number or numeric string

See also

• \Phuture\Coherence\Numbers::parseInt()
• \Phuture\Coherence\Numbers::parseFloat()

#isPositive()

public static function isPositive(int|float|string $number): bool

Determines whether a number is positive (strictly greater than zero).

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::isPositive(5); // true
4Numbers::isPositive(0.1); // true
5Numbers::isPositive(0); // false
6Numbers::isPositive(-3); // false

Returns bool — True when the number is strictly greater than zero

See also

• \Phuture\Coherence\Numbers::isNegative()
• \Phuture\Coherence\Numbers::isZero()

#isZero()

public static function isZero(int|float|string $number): bool

Determines whether a number is equal to zero at BCMath precision.

Compares the value against zero using BCMath at the default scale. Values smaller than the default scale are treated as zero.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::isZero(0); // true
4Numbers::isZero(0.0); // true
5Numbers::isZero(0.5); // false
6Numbers::isZero('0.0000000000'); // true

Returns bool — True when the number is zero at BCMath precision

See also

• \Phuture\Coherence\Numbers::isPositive()
• \Phuture\Coherence\Numbers::isNegative()

#max()

public static function max(int|float|string $first, int|float|string $second): int|float|string

Returns the higher of two numbers.

Compares two numbers and returns the one with the higher value.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::max(3, 7); // 7
4Numbers::max(-5, -2); // -2
5Numbers::max(3.14, 2.7); // 3.14

Returns int|float|string — The higher of the two numbers

See also

• \Phuture\Coherence\Numbers::min()
• \Phuture\Coherence\Numbers::clamp()

#mean()

public static function mean(array $values): string

Computes the arithmetic mean (average) of a list of numbers.

This method calculates the average by summing all values and dividing by the count. It uses BCMath for precision, returning a string result.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::mean([2, 4, 6, 8]);
4// Returns: '5.0000000000'
5
6Numbers::mean([1.5, 2.5, 3.5]);
7// Returns: '2.5000000000'

Returns string — The arithmetic mean as a BCMath string

Throws

• InvalidArgumentException — When the values array is empty

See also

• \Phuture\Coherence\Numbers::median()
• \Phuture\Coherence\Numbers::mode()

#median()

public static function median(array $values): string

Computes the median (middle value) of a list of numbers.

This method sorts the values and returns the middle value for odd-count arrays, or the average of the two middle values for even-count arrays. Returns a BCMath string for precision.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::median([1, 3, 5]);
4// Returns: '3.0000000000'
5
6Numbers::median([1, 3, 5, 7]);
7// Returns: '4.0000000000'

Returns string — The median as a BCMath string

Throws

• InvalidArgumentException — When the values array is empty

See also

• \Phuture\Coherence\Numbers::mean()
• \Phuture\Coherence\Numbers::percentile()

#min()

public static function min(int|float|string $first, int|float|string $second): int|float|string

Returns the lower of two numbers.

Compares two numbers and returns the one with the lower value.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::min(3, 7); // 3
4Numbers::min(-5, -2); // -5
5Numbers::min(3.14, 2.7); // 2.7

Returns int|float|string — The lower of the two numbers

See also

• \Phuture\Coherence\Numbers::max()
• \Phuture\Coherence\Numbers::clamp()

#mode()

public static function mode(array $values): array

Finds the mode (most frequently occurring value) of a list of numbers.

This method returns the value that appears most often. When multiple values share the highest frequency, all of them are returned. The result is an array of the mode values, preserving their original types.

Example:

 1use Phuture\Coherence\Numbers;
 2
 3Numbers::mode([1, 2, 2, 3, 3, 3]);
 4// Returns: [3]
 5
 6Numbers::mode([1, 1, 2, 2, 3]);
 7// Returns: [1, 2]
 8
 9Numbers::mode([5]);
10// Returns: [5]

Returns array — An array containing the most frequently occurring value(s)

Throws

• InvalidArgumentException — When the values array is empty

See also

• \Phuture\Coherence\Numbers::mean()
• \Phuture\Coherence\Numbers::median()

#modulus()

public static function modulus(int|float|string $dividend, int|float|string $divisor): string

Computes the modulus (remainder) of dividing the first number by the second using BCMath.

Returns the remainder of $a divided by $b. Throws when the divisor is zero.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::modulus(10, 3); // '1.0000000000'
4Numbers::modulus(10, 2); // '0.0000000000'
5Numbers::modulus(7.5, 2); // '1.5000000000'

Returns string — The remainder as a string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the divisor is zero

See also

• \Phuture\Coherence\Numbers::divide()

#multiply()

public static function multiply(int|float|string $left, int|float|string $right): string

Multiplies two numbers using BCMath for precision and returns the result as a string.

Both values are converted to strings and multiplied using BCMath to avoid floating-point precision loss.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::multiply(0.1, 0.2); // '0.0200000000'
4Numbers::multiply(3, 4); // '12.0000000000'
5Numbers::multiply(2.5, 4.0); // '10.0000000000'

Returns string — The product as a BCMath string at BCMath precision

See also

• \Phuture\Coherence\Numbers::divide()

#of()

public static function of(int|float|string $number): Type\Numbers

Creates a fluent Numbers instance for chaining number operations.

This method provides a convenient entry point for building a sequence of number operations using method chaining. Instead of calling static methods one by one, you can chain operations together in a single readable expression.

Example:

1use Phuture\Coherence\Numbers;
2
3$result = Numbers::of(10)
4    ->add(5)
5    ->multiply(2)
6    ->get();
7
8// Returns: '30.0000000000'

Returns \Phuture\Coherence\Type\Numbers — Returns a fluent Numbers instance for chaining

See also

• \Phuture\Coherence\Type\Numbers

#opposite()

public static function opposite(int|float|string $number): int|float|string

Returns the arithmetic opposite (negation) of a number.

Flips the sign of the number: positive values become negative and negative values become positive. Zero remains zero.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::opposite(5); // -5
4Numbers::opposite(-3.2); // 3.2
5Numbers::opposite(0); // 0

Returns int|float|string — The negated value

See also

• \Phuture\Coherence\Numbers::absolute()

#ordinal()

public static function ordinal(int $number): string

Converts an integer to its ordinal string representation.

Appends the correct English ordinal suffix to the given integer. Handles the special cases for 11th, 12th, and 13th correctly.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::ordinal(1); // '1st'
4Numbers::ordinal(2); // '2nd'
5Numbers::ordinal(3); // '3rd'
6Numbers::ordinal(4); // '4th'
7Numbers::ordinal(11); // '11th'
8Numbers::ordinal(21); // '21st'

Returns string — The ordinal string with the appropriate suffix

See also

• \Phuture\Coherence\Numbers::spell()

#parseFloat()

public static function parseFloat(mixed $value): float

Parses a string to a float using PHP's floatval function.

Converts the given value to a floating-point number. Throws when the value is not a valid numeric representation (non-numeric strings, null, arrays, etc.).

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::parseFloat('3.14'); // 3.14
4Numbers::parseFloat('-2.5'); // -2.5
5Numbers::parseFloat('abc'); // throws InvalidArgumentException

Returns float — The parsed float value

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the value is not numeric

See also

• \Phuture\Coherence\Numbers::parseInt()
• \Phuture\Coherence\Numbers::isNumber()

#parseInt()

public static function parseInt(mixed $value): int

Parses a string to an integer using PHP's intval function.

Converts the given value to an integer. Throws when the value is not a valid numeric representation (non-numeric strings, null, arrays, etc.).

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::parseInt('42'); // 42
4Numbers::parseInt('-7'); // -7
5Numbers::parseInt('3.9'); // 3
6Numbers::parseInt('abc'); // throws InvalidArgumentException

Returns int — The parsed integer value

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the value is not numeric

See also

• \Phuture\Coherence\Numbers::parseFloat()
• \Phuture\Coherence\Numbers::isNumber()

#percentage()

public static function percentage(int|float|string $number, int|float|string $percentage): string

Calculates the given percentage of a number using BCMath for precision.

Returns the raw percentage amount without adding or subtracting it from the original value. Useful when you need the percentage value itself rather than an adjusted total.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::percentage(200, 20); // '40.0000000000' (20% of 200)
4Numbers::percentage(50, 10); // '5.0000000000' (10% of 50)
5Numbers::percentage(100, 5); // '5.0000000000' (5% of 100)

Returns string — The percentage amount as a BCMath string

See also

• \Phuture\Coherence\Numbers::addPercentage()
• \Phuture\Coherence\Numbers::subtractPercentage()

#percentile()

public static function percentile(array $values, int|float $percentile): string

Computes a specific percentile of a list of numbers.

This method uses linear interpolation to compute the value at a given percentile rank. The 50th percentile is equivalent to the median. Values are sorted internally, and the result uses BCMath for precision.

The percentile is computed using the "exclusive" method: the 0th percentile is the minimum value and the 100th percentile is the maximum.

Example:

 1use Phuture\Coherence\Numbers;
 2
 3Numbers::percentile([1, 2, 3, 4, 5], 50);
 4// Returns: '3.0000000000' (the median)
 5
 6Numbers::percentile([1, 2, 3, 4, 5, 6], 25);
 7// Returns: '2.5000000000'
 8
 9Numbers::percentile([1, 2, 3, 4, 5], 0);
10// Returns: '1.0000000000' (the minimum)

Returns string — The value at the given percentile as a BCMath string

Throws

• InvalidArgumentException — When the values array is empty or percentile is out of range

See also

• \Phuture\Coherence\Numbers::median()

#range()

public static function range(array $values): string

Computes the range (difference between maximum and minimum) of a list of numbers.

This method finds the difference between the largest and smallest values in the set, giving a simple measure of data spread.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::range([3, 7, 2, 9, 5]);
4// Returns: '7.0000000000'
5
6Numbers::range([1.5, 4.5]);
7// Returns: '3.0000000000'

Returns string — The range (max minus min) as a BCMath string

Throws

• InvalidArgumentException — When the values array is empty

See also

• \Phuture\Coherence\Numbers::standardDeviation()

#rankineToCelsius()

public static function rankineToCelsius(string $value): string

Converts a Rankine temperature to Celsius using BCMath for precision.

Applies the formula: Celsius = (Rankine - 491.67) * 5 / 9

Example:

1use Phuture\Coherence\Numbers;
2
3$celsius = Numbers::rankineToCelsius('671.67');
4
5// Returns: '100.0000000000'

Returns string — The Celsius temperature as a BCMath string

See also

• \Phuture\Coherence\Numbers::celsiusToRankine()

#round()

public static function round(int|float|string $number, int $precision = 0, RoundingMode $mode = RoundingMode::HalfAwayFromZero): string

Rounds a number to the specified precision using the given rounding mode.

Delegates to the polyfilled/native bcround() for full BCMath precision. The result has exactly $precision decimal places.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::round(3.456, 2); // '3.46'
4Numbers::round(3.456, 0); // '3'
5Numbers::round(3.5, 0, RoundingMode::HalfTowardsZero); // '3'

Returns string — The rounded value as a BCMath string with exactly $precision decimal places

See also

• \Phuture\Coherence\Numbers::ceil()
• \Phuture\Coherence\Numbers::floor()

#sampleStandardDeviation()

public static function sampleStandardDeviation(array $values): string

Computes the sample standard deviation of a list of numbers.

Sample standard deviation uses sample variance (N-1 denominator) as its base. Use this when your data is a sample from a larger population.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::sampleStandardDeviation([2, 4, 4, 4, 5, 5, 7, 9]);
4// Returns: '2.1380899353'
5
6Numbers::sampleStandardDeviation([1, 2, 3, 4, 5]);
7// Returns: '1.5811388301'

Returns string — The sample standard deviation as a BCMath string

Throws

• InvalidArgumentException — When the values array has fewer than 2 elements

See also

• \Phuture\Coherence\Numbers::sampleVariance()
• \Phuture\Coherence\Numbers::standardDeviation()

#sampleVariance()

public static function sampleVariance(array $values): string

Computes the sample variance of a list of numbers.

Sample variance is similar to population variance but divides by N-1 instead of N (Bessel's correction). Use this when your data is a sample from a larger population to get an unbiased estimate.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::sampleVariance([2, 4, 4, 4, 5, 5, 7, 9]);
4// Returns: '4.5714285714'
5
6Numbers::sampleVariance([1, 2, 3, 4, 5]);
7// Returns: '2.5000000000'

Returns string — The sample variance as a BCMath string

Throws

• InvalidArgumentException — When the values array has fewer than 2 elements

See also

• \Phuture\Coherence\Numbers::variance()
• \Phuture\Coherence\Numbers::sampleStandardDeviation()

#spell()

public static function spell(int $number): string

Spells out a number in English words.

Converts an integer to its English word representation. Handles negative numbers by prefixing "negative". Returns the numeric string for numbers outside the supported range.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::spell(0); // 'zero'
4Numbers::spell(7); // 'seven'
5Numbers::spell(42); // 'forty-two'
6Numbers::spell(-5); // 'negative five'
7Numbers::spell(100); // 'one hundred'
8Numbers::spell(1000); // 'one thousand'

Returns string — The English word representation of the number

See also

• \Phuture\Coherence\Numbers::ordinal()

#squareRoot()

public static function squareRoot(int|float|string $number, int $scale = self::DEFAULT_SCALE): string

Computes the square root of a number using BCMath for precision.

Returns the square root as a string with the specified number of decimal places. Throws when the number is negative.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::squareRoot(9); // '3.0000000000'
4Numbers::squareRoot(2, 4); // '1.4142'
5Numbers::squareRoot(0); // '0.0000000000'

Returns string — The square root as a string

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the number is negative

See also

• \Phuture\Coherence\Numbers::multiply()
• \Phuture\Coherence\Numbers::round()

#standardDeviation()

public static function standardDeviation(array $values): string

Computes the population standard deviation of a list of numbers.

Standard deviation is the square root of the variance. It measures how spread out the numbers are from the mean in the same units as the data. Use this when your data represents an entire population.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::standardDeviation([2, 4, 4, 4, 5, 5, 7, 9]);
4// Returns: '2.0000000000'
5
6Numbers::standardDeviation([1, 2, 3, 4, 5]);
7// Returns: '1.4142135624'

Returns string — The population standard deviation as a BCMath string

Throws

• InvalidArgumentException — When the values array is empty

See also

• \Phuture\Coherence\Numbers::variance()
• \Phuture\Coherence\Numbers::sampleStandardDeviation()

#subtract()

public static function subtract(int|float|string $left, int|float|string $right): string

Subtracts the second number from the first using BCMath for precision.

Both values are converted to strings and subtracted using BCMath to avoid floating-point precision loss.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::subtract(10, 3); // '7.0000000000'
4Numbers::subtract(5.5, 2.5); // '3.0000000000'
5Numbers::subtract(1, 1); // '0.0000000000'

Returns string — The difference as a string

See also

• \Phuture\Coherence\Numbers::add()

#subtractPercentage()

public static function subtractPercentage(int|float|string $number, int|float|string $percentage): string

Decreases a number by a given percentage and returns the result.

Computes the percentage of the number and subtracts it from the original value using BCMath to avoid floating-point precision loss.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::subtractPercentage(100, 20); // '80.0000000000'  (100 - 20%)
4Numbers::subtractPercentage(50, 10); // '45.0000000000'  (50 - 10%)
5Numbers::subtractPercentage(200, 5); // '190.0000000000' (200 - 5%)

Returns string — The decreased value as a BCMath string

See also

• \Phuture\Coherence\Numbers::addPercentage()
• \Phuture\Coherence\Numbers::percentage()
• \Phuture\Coherence\Numbers::subtract()

#toNumber()

public static function toNumber(int|float|string|bool|array $number): string

Normalizes any value into a BCMath-compatible numeric string.

Each input type is handled differently:

• array: returns the element count as a BCMath string (e.g. [1,2,3] → '3.0000000000')
• bool: returns '1.0000000000' for true, '0.0000000000' for false
• string: passed directly into BCMath without a float round-trip, preserving all digits up to the scale
• int / float: converted to a BCMath string (e.g. 42 → '42.0000000000')

The result is safe to pass directly into any other BCMath method without precision loss.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::toNumber(true); // '1.0000000000'
4Numbers::toNumber('3.14'); // '3.1400000000'
5Numbers::toNumber([1, 2, 3]); // '3.0000000000'
6Numbers::toNumber(42); // '42.0000000000'
7Numbers::toNumber('0.3333333333'); // '0.3333333333'

Returns string — The BCMath string representation

See also

• \Phuture\Coherence\Numbers::parseInt()
• \Phuture\Coherence\Numbers::parseFloat()
• \Phuture\Coherence\Numbers::isNumber()

#trimTrailingZeros()

public static function trimTrailingZeros(int|float|string $number): string

Removes trailing zeros from a numeric string representation.

Converts the number to a string and strips any trailing zeros after the decimal point. If all decimal digits are zeros, the decimal point itself is also removed.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::trimTrailingZeros('3.14000'); // '3.14'
4Numbers::trimTrailingZeros('5.00'); // '5'
5Numbers::trimTrailingZeros('100.000'); // '100'
6Numbers::trimTrailingZeros(7.500); // '7.5'

Returns string — The trimmed number string

See also

• \Phuture\Coherence\Numbers::format()
• \Phuture\Coherence\Numbers::abbreviate()

#variance()

public static function variance(array $values): string

Computes the population variance of a list of numbers.

Population variance measures how far each number in the set is from the mean squared, averaged across all values. Use this when your data represents an entire population, not a sample.

Example:

1use Phuture\Coherence\Numbers;
2
3Numbers::variance([2, 4, 4, 4, 5, 5, 7, 9]);
4// Returns: '4.0000000000'
5
6Numbers::variance([1, 2, 3, 4, 5]);
7// Returns: '2.0000000000'

Returns string — The population variance as a BCMath string

Throws

• InvalidArgumentException — When the values array is empty

See also

• \Phuture\Coherence\Numbers::sampleVariance()
• \Phuture\Coherence\Numbers::standardDeviation()

#assertNotNan()

private static function assertNotNan(int|float|string $value, string $label): void

Asserts that the given value is not NAN.

NAN cannot be meaningfully compared with any value, including itself. This method throws a clear exception when a NAN value is detected.

Throws

• \Phuture\Coherence\Exception\LogicException — When the value is NAN

#assertPrecision()

private static function assertPrecision(int $precision): void

Asserts that the given precision is within the supported range.

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the precision is negative or greater than MAX_PRECISION

#convertNumberToWords()

private static function convertNumberToWords(int $number): string

Converts an integer between 0 and 999,999,999 into English words.

Breaks the number into groups of three digits and converts each group separately, combining them with the appropriate scale words (thousand, million).

Returns string — The English word representation

#convertTemperature()

private static function convertTemperature(int|float|string $value, Unit $from, Unit $to): string

Converts a temperature value from one scale to another via Celsius as the intermediate step.

Uses a two-step conversion: first to Celsius, then from Celsius to the target scale. This avoids needing a conversion formula for every possible pair of temperature units. All arithmetic uses BCMath for precision.

Returns string — The converted temperature as a BCMath string

See also

• \Phuture\Coherence\Numbers::convert()

#detectPrecision()

private static function detectPrecision(int|float|string $number): int

Detects the number of decimal places in a numeric value.

Examines the string representation of the number to determine how many digits follow the decimal point.

Returns int — The number of decimal places found