Oihana PHP

maths

Table of Contents

Classes

Dimension
Defines the canonical keys of a two-dimensional size pair.

Functions

aspectFit()  : array{width: int, height: int}
Scales a dimension pair to a target width or height while preserving the original aspect ratio (the locked-ratio behaviour of an aspect-ratio box).
bearing()  : float
Calculates the initial bearing (sometimes referred to as forward azimuth) which if followed in a straight line along a great-circle arc will take you from the start point to the end point (in degrees).
cartesianToPolar()  : array{angle: float, radius: float}
Converts a cartesian vector to polar coordinates.
ceilValue()  : int|float
Rounds and returns the ceiling of the specified number or expression.
factorial()  : int
Computes the factorial `n!` of a non-negative integer.
fixAngle()  : float
Normalize an angle in degrees to the range [0, 360).
floorValue()  : int|float
Rounds and returns a number by a count of floating points, using floor.
gcd()  : int
Calculate the Greatest Common Divisor (GCD) of two integers using the Euclidean algorithm.
haversine()  : float
Calculate the great-circle distance between two points on a sphere using the Haversine formula.
isPrime()  : bool
Tells whether an integer is a prime number.
mean()  : float
Computes the arithmetic mean (average) of a list of numbers.
median()  : float
Computes the median (middle value) of a list of numbers.
polarToCartesian()  : array{x: float, y: float}
Converts a polar coordinate to a cartesian vector.
roundValue()  : int|float
Rounds and returns the rounded value of the specified number or expression.
stddev()  : float
Computes the standard deviation of a list of numbers.
variance()  : float
Computes the variance of a list of numbers.

Functions

aspectFit()

Scales a dimension pair to a target width or height while preserving the original aspect ratio (the locked-ratio behaviour of an aspect-ratio box).

aspectFit(int $width, int $height[, int|null $targetWidth = null ][, int|null $targetHeight = null ]) : array{width: int, height: int}

Provide $targetWidth to derive the matching height, or $targetHeight to derive the matching width. If both are given, $targetWidth takes precedence and $targetHeight is ignored. If both are null, the original pair is returned. A non-positive original $width/$height yields an undefined ratio: the provided targets (or the originals) are returned unchanged.

Parameters
$width : int

The original (reference) width.

$height : int

The original (reference) height.

$targetWidth : int|null = null

The desired width, or null.

$targetHeight : int|null = null

The desired height, or null.

Tags
example 
use function oihana\core\maths\aspectFit ;

aspectFit( 1920 , 1080 , targetWidth: 1280 ) ; // [ 'width' => 1280 , 'height' => 720 ]
aspectFit( 1920 , 1080 , targetHeight: 540 ) ; // [ 'width' => 960  , 'height' => 540 ]
author

Marc Alcaraz (ekameleon)

since
1.2.0
Return values
array{width: int, height: int} —

The scaled dimensions preserving the ratio.

bearing()

Calculates the initial bearing (sometimes referred to as forward azimuth) which if followed in a straight line along a great-circle arc will take you from the start point to the end point (in degrees).

bearing(float $latitude1, float $longitude1, float $latitude2, float $longitude2) : float
Parameters
$latitude1 : float

The first latitude coordinate in degrees.

$longitude1 : float

The first longitude coordinate in degrees.

$latitude2 : float

The second latitude coordinate in degrees.

$longitude2 : float

The second longitude coordinate in degrees.

Tags
example 
$position1 = [ 'x' => 37.422045 , 'y' => -122.084347 ]; // Google HQ
$position2 = [ 'x' => 37.77493  , 'y' => -122.419416 ]; // San Francisco, CA

echo bearing($position1['x'], $position1['y'], $position2['x'], $position2['y']);
// 323.1477743368166
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
float —

The bearing in degrees from North.

cartesianToPolar()

Converts a cartesian vector to polar coordinates.

cartesianToPolar(array{x?: float|int, y?: float|int} $vector[, bool $degrees = true ][, bool $throwable = false ]) : array{angle: float, radius: float}
Parameters
$vector : array{x?: float|int, y?: float|int}

Cartesian coordinates with keys 'x' and 'y'.

$degrees : bool = true

Whether the returned angle should be in degrees (default: true).

$throwable : bool = false

Whether to throw an exception if keys are missing (default: false).

Tags
throws
InvalidArgumentException

if $throwable is true and required keys are missing.

example 
$polar = cartesianToPolar(['x' => 0, 'y' => 5]);
// Returns: ['angle' => 90, 'radius' => 5]

$polar = cartesianToPolar(['x' => 1, 'y' => 1], false);
// Returns angle in radians
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
array{angle: float, radius: float} —

Polar coordinates with keys 'angle' and 'radius'.

ceilValue()

Rounds and returns the ceiling of the specified number or expression.

ceilValue(int|float $value[, int $floatCount = 0 ]) : int|float

The ceiling of a number is the closest integer that is greater than or equal to the number.

Parameters
$value : int|float

The number to round.

$floatCount : int = 0

The number of decimal places to round up to.

Tags
example 
echo ceilValue(4.1234);       // Outputs: 5
echo ceilValue(4.1234, 2);    // Outputs: 4.13
echo ceilValue(4.9999, 3);    // Outputs: 5.000
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
int|float —

The rounded number.

factorial()

Computes the factorial `n!` of a non-negative integer.

factorial(int $n) : int

factorial(0) is 1. The argument is capped at 20 because 21! exceeds PHP_INT_MAX and could no longer be represented exactly as an int.

Parameters
$n : int

A non-negative integer in the range [0, 20].

Tags
throws
InvalidArgumentException

If $n is negative or greater than 20.

example 
use function oihana\core\maths\factorial;

echo factorial( 0 ) ; // 1
echo factorial( 5 ) ; // 120
echo factorial( 10 ) ; // 3628800
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
int —

The factorial of $n.

fixAngle()

Normalize an angle in degrees to the range [0, 360).

fixAngle(float|int $angle) : float

If the input is not numeric (NaN, null, etc.), the function will return 0.

Parameters
$angle : float|int

The angle in degrees.

Tags
example 
echo fixAngle(370);   // 10
echo fixAngle(-90);   // 270
echo fixAngle(720.5); // 0.5
echo fixAngle(NAN);   // 0
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
float —

The normalized angle between 0 (inclusive) and 360 (exclusive).

floorValue()

Rounds and returns a number by a count of floating points, using floor.

floorValue(int|float $value[, int $floatCount = 0 ]) : int|float

The floor of a number is the closest integer less than or equal to the number.

Parameters
$value : int|float

The number to round.

$floatCount : int = 0

The number of decimal places to round down to.

Tags
example 
echo floorValue(4.9876);       // Outputs: 4
echo floorValue(4.9876, 2);    // Outputs: 4.98
echo floorValue(4.1234, 3);    // Outputs: 4.123
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
int|float —

The rounded number.

gcd()

Calculate the Greatest Common Divisor (GCD) of two integers using the Euclidean algorithm.

gcd(int $a, int $b[, bool $throwable = false ]) : int

This function returns the absolute value of the GCD. If both numbers are zero, it either returns 0 or throws an exception depending on the $throwable parameter.

Parameters
$a : int

The first integer.

$b : int

The second integer.

$throwable : bool = false

If true, throws an exception when both numbers are zero.

Tags
throws
InvalidArgumentException

If both $a and $b are zero and $throwable is true.

example 
echo gcd(48, 18); // Outputs: 6
echo gcd(-48, 18); // Outputs: 6
echo gcd(0, 5);    // Outputs: 5
echo gcd(0, 0);    // Outputs: 0
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
int —

The greatest common divisor of $a and $b.

haversine()

Calculate the great-circle distance between two points on a sphere using the Haversine formula.

haversine(float $latitude1, float $longitude1, float $latitude2, float $longitude2[, float $radius = 6371000 ][, int|null $precision = null ]) : float

This is commonly used for distances on Earth. It's faster than the Vincenty formula but less precise.

Parameters
$latitude1 : float

The latitude of the first point in degrees.

$longitude1 : float

The longitude of the first point in degrees.

$latitude2 : float

The latitude of the second point in degrees.

$longitude2 : float

The longitude of the second point in degrees.

$radius : float = 6371000

The radius of the sphere (default is Earth's mean radius: 6,371,000 meters).

$precision : int|null = null

Number of decimal places to round to. If null, returns full precision.

Tags
throws
InvalidArgumentException

If $precision is not null and is negative.

example 
use function oihana\core\maths\haversine;

$pos1 = [ 37.422045, -122.084347 ] ; // Google HQ
$pos2 = [ 37.77493,  -122.419416 ] ; // San Francisco, CA

echo haversine( $pos1[0] , $pos1[1], $pos2[0] , $pos2[1] ) ;       // Full precision
echo haversine( $pos1[0] , $pos1[1], $pos2[0] , $pos2[1] , 6371000, 3 ); // Rounded to 3 decimals
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
float —

The distance between the two points in meters.

isPrime()

Tells whether an integer is a prime number.

isPrime(int $n) : bool

Any integer lower than 2 is not prime. The test uses 6k ± 1 trial division up to √n.

Parameters
$n : int

The integer to test.

Tags
example 
use function oihana\core\maths\isPrime;

isPrime( 2 )  ; // true
isPrime( 17 ) ; // true
isPrime( 25 ) ; // false
isPrime( 1 )  ; // false
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
bool —

true if $n is prime, false otherwise.

mean()

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

mean(array<int, int|float> $values) : float
Parameters
$values : array<int, int|float>

A non-empty list of numeric values.

Tags
throws
InvalidArgumentException

If the array is empty.

example 
use function oihana\core\maths\mean;

echo mean( [ 1 , 2 , 3 , 4 ] ) ; // 2.5
echo mean( [ 2 , 4 , 6 ] )      ; // 4.0
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
float —

The arithmetic mean of the values.

median()

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

median(array<int, int|float> $values) : float

The values are sorted numerically. For an odd number of values the middle one is returned ; for an even number, the average of the two central values is returned.

Parameters
$values : array<int, int|float>

A non-empty list of numeric values.

Tags
throws
InvalidArgumentException

If the array is empty.

example 
use function oihana\core\maths\median;

echo median( [ 3 , 1 , 2 ] )     ; // 2.0
echo median( [ 4 , 1 , 3 , 2 ] ) ; // 2.5
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
float —

The median of the values.

polarToCartesian()

Converts a polar coordinate to a cartesian vector.

polarToCartesian(array{angle: float, radius: float} $vector[, bool $degrees = true ][, bool $throwable = false ]) : array{x: float, y: float}
Parameters
$vector : array{angle: float, radius: float}

Polar coordinates with keys 'angle' and 'radius'.

$degrees : bool = true

Whether the angle is in degrees (default: true).

$throwable : bool = false

Whether to throw when the 'angle'/'radius' keys are missing (default: false).

Tags
throws
InvalidArgumentException

If $throwable is true and keys are missing.

example 
use function oihana\core\maths\polarToCartesian;

// Example 1: normal usage
$polar = ['angle' => 45, 'radius' => 10];
$cartesian = polarToCartesian($polar) ;
print_r($cartesian);
// Output: ['x' => 7.0710678118655, 'y' => 7.0710678118655]

// Example 2: missing angle, throwable = false (default)
$polar2 = ['radius' => 5];
$cartesian2 = polarToCartesian($polar2) ;
print_r($cartesian2);
// Output: ['x' => 0, 'y' => 0]

// Example 3: missing angle, throwable = true
$polar3 = ['radius' => 5];
try
{
    $cartesian3 = polarToCartesian($polar3, true, true);
}
catch ( InvalidArgumentException $e )
{
    echo $e->getMessage();
}
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
array{x: float, y: float} —

Cartesian representation with keys 'x' and 'y'.

roundValue()

Rounds and returns the rounded value of the specified number or expression.

roundValue(int|float $value[, int $floatCount = 0 ]) : int|float
Parameters
$value : int|float

The number to round.

$floatCount : int = 0

The number of decimal places to round to.

Tags
example 
echo roundValue(4.9876);       // Outputs: 5
echo roundValue(4.9876, 2);    // Outputs: 4.99
echo roundValue(4.1234, 3);    // Outputs: 4.123
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
int|float —

The rounded number.

stddev()

Computes the standard deviation of a list of numbers.

stddev(array<int, int|float> $values[, bool $sample = false ]) : float

The standard deviation is the square root of the variance(). By default the population standard deviation is returned ; when $sample is true, the sample standard deviation is returned (Bessel's correction, N - 1).

Parameters
$values : array<int, int|float>

A list of numeric values (at least one for population, two for sample).

$sample : bool = false

Whether to compute the sample standard deviation (N - 1) instead of the population one (N).

Tags
throws
InvalidArgumentException

If the array is empty, or has fewer than two values when $sample is true.

example 
use function oihana\core\maths\stddev;

echo stddev( [ 2 , 4 , 4 , 4 , 5 , 5 , 7 , 9 ] )        ; // 2.0   (population)
echo stddev( [ 2 , 4 , 4 , 4 , 5 , 5 , 7 , 9 ] , true ) ; // ~2.138 (sample)
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
float —

The standard deviation of the values.

variance()

Computes the variance of a list of numbers.

variance(array<int, int|float> $values[, bool $sample = false ]) : float

By default the population variance is returned (sum of squared deviations divided by N). When $sample is true, the sample variance is returned instead (divided by N - 1, Bessel's correction).

Parameters
$values : array<int, int|float>

A list of numeric values (at least one for population, two for sample).

$sample : bool = false

Whether to compute the sample variance (N - 1) instead of the population one (N).

Tags
throws
InvalidArgumentException

If the array is empty, or has fewer than two values when $sample is true.

example 
use function oihana\core\maths\variance;

echo variance( [ 2 , 4 , 4 , 4 , 5 , 5 , 7 , 9 ] )        ; // 4.0  (population)
echo variance( [ 2 , 4 , 4 , 4 , 5 , 5 , 7 , 9 ] , true ) ; // ~4.571 (sample)
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
float —

The variance of the values.

On this page

Search results