Oihana PHP

numbers

Table of Contents

Functions

clamp()  : int|float
Bounds a number value between two numbers.
clip()  : int|float
Bounds a number value between two numbers.
isEven()  : bool
Tells whether an integer is even.
isOdd()  : bool
Tells whether an integer is odd.
lerp()  : float
Linearly interpolates between two values.
mapRange()  : float
Re-maps a value from one range to another.
modf()  : array{0: float, 1: float}
Splits a number into its integral and fractional parts, like the C `modf()` function.
percentage()  : float
Computes which percentage a part represents of a total.
sign()  : int
Returns the sign of a number.

Functions

clamp()

Bounds a number value between two numbers.

clamp(int|float $value, int|float $min, int|float $max) : int|float

This is a clarified alias of clip() ; both names are kept for convenience.

Parameters
$value : int|float

The value to clamp.

$min : int|float

The minimum value of the range.

$max : int|float

The maximum value of the range.

Tags
example 
use function oihana\core\numbers\clamp;

clamp( 4  , 5 , 10 ) ; // Returns 5
clamp( 12 , 5 , 10 ) ; // Returns 10
clamp( 6  , 5 , 10 ) ; // Returns 6
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
int|float —

A value bounded between $min and $max.

clip()

Bounds a number value between two numbers.

clip(int|float $value, int|float $min, int|float $max) : int|float
Parameters
$value : int|float

The value to clamp.

$min : int|float

The minimum value of the range.

$max : int|float

The maximum value of the range.

Tags
example 
clip( 4  , 5 , 10 ) ;  // Returns 5
clip( 12 , 5 , 10 ) ; // Returns 10
clip( 6  , 5 , 10 ) ;  // Returns 6
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
int|float —

A value bounded between $min and $max.

isEven()

Tells whether an integer is even.

isEven(int $value) : bool
Parameters
$value : int

The integer to test.

Tags
example 
use function oihana\core\numbers\isEven;

isEven( 4 )  ; // true
isEven( 7 )  ; // false
isEven( 0 )  ; // true
isEven( -2 ) ; // true
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
bool —

true if $value is even, false otherwise.

isOdd()

Tells whether an integer is odd.

isOdd(int $value) : bool
Parameters
$value : int

The integer to test.

Tags
example 
use function oihana\core\numbers\isOdd;

isOdd( 7 )  ; // true
isOdd( 4 )  ; // false
isOdd( 0 )  ; // false
isOdd( -3 ) ; // true
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
bool —

true if $value is odd, false otherwise.

lerp()

Linearly interpolates between two values.

lerp(float $a, float $b, float $t) : float

Computes $a + ( $b - $a ) * $t. The factor $t is not bounded: values outside the [0, 1] range extrapolate beyond the [$a, $b] segment.

Parameters
$a : float

The start value (returned when $t === 0.0).

$b : float

The end value (returned when $t === 1.0).

$t : float

The interpolation factor, typically in [0, 1].

Tags
example 
use function oihana\core\numbers\lerp;

lerp( 0.0 , 10.0 , 0.0 ) ;  // 0.0
lerp( 0.0 , 10.0 , 0.5 ) ;  // 5.0
lerp( 0.0 , 10.0 , 1.0 ) ;  // 10.0
lerp( 0.0 , 10.0 , 2.0 ) ;  // 20.0 (extrapolation)
lerp( 10.0 , 0.0 , 0.25 ) ; // 7.5
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
float —

The interpolated value.

mapRange()

Re-maps a value from one range to another.

mapRange(float $value, float $inMin, float $inMax, float $outMin, float $outMax) : float

Linearly transforms $value from the input range [$inMin, $inMax] to the output range [$outMin, $outMax] using $outMin + ( $value - $inMin ) * ( $outMax - $outMin ) / ( $inMax - $inMin ).

The result is not clamped: values outside the input range map outside the output range.

Parameters
$value : float

The value to re-map.

$inMin : float

The lower bound of the input range.

$inMax : float

The upper bound of the input range.

$outMin : float

The lower bound of the output range.

$outMax : float

The upper bound of the output range.

Tags
throws
InvalidArgumentException

If the input range is degenerate ($inMin === $inMax).

example 
use function oihana\core\numbers\mapRange;

mapRange( 5.0  , 0.0 , 10.0 , 0.0 , 100.0 ) ; // 50.0
mapRange( 0.0  , 0.0 , 10.0 , 0.0 , 100.0 ) ; // 0.0
mapRange( 10.0 , 0.0 , 10.0 , 0.0 , 100.0 ) ; // 100.0
mapRange( 0.0  , -1.0 , 1.0 , 0.0 , 255.0 ) ; // 127.5
mapRange( 15.0 , 0.0 , 10.0 , 0.0 , 100.0 ) ; // 150.0 (outside output range)
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
float —

The value re-mapped into the output range.

modf()

Splits a number into its integral and fractional parts, like the C `modf()` function.

modf(float $number) : array{0: float, 1: float}

The number is truncated toward zero, so the sign is preserved on both parts : modf( -1.5 ) returns [ -1.0 , -0.5 ] (and not [ -2.0 , 0.5 ] as a floor() based split would). Both parts are always returned as float.

Special values follow the C behavior :

  • modf( INF ) returns [ INF , 0.0 ] (idem with -INF).
  • modf( NAN ) returns [ NAN , NAN ].

Note: unlike C's and Python's modf, the integral part comes first (natural reading order : 1.5 is 1 + 0.5), the fractional part second.

Parameters
$number : float

The number to split.

Tags
example 
use function oihana\core\numbers\modf;

modf( 1.5 )   ; // [ 1.0 , 0.5 ]
modf( -1.5 )  ; // [ -1.0 , -0.5 ]
modf( 3.0 )   ; // [ 3.0 , 0.0 ]
modf( -0.25 ) ; // [ -0.0 , -0.25 ]
modf( INF )   ; // [ INF , 0.0 ]
author

Marc Alcaraz (ekameleon)

since
1.0.11
Return values
array{0: float, 1: float} —

A two-element array : [ integral part , fractional part ].

percentage()

Computes which percentage a part represents of a total.

percentage(int|float $part, int|float $total) : float

Returns ( $part / $total ) * 100. As a guard against division by zero, a $total of 0 yields 0.0 rather than raising an error.

Parameters
$part : int|float

The partial amount.

$total : int|float

The total amount.

Tags
example 
use function oihana\core\numbers\percentage;

percentage( 25 , 200 ) ; // 12.5
percentage( 1 , 3 )    ; // 33.333333333333
percentage( 5 , 0 )    ; // 0.0 (division-by-zero guard)
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
float —

The percentage in the [0, 100] range for in-bounds inputs, 0.0 when $total is 0.

sign()

Returns the sign of a number.

sign(int|float $value) : int
Parameters
$value : int|float

The value to evaluate.

Tags
example 
use function oihana\core\numbers\sign;

sign( -42 )  ; // -1
sign( 0 )    ; //  0
sign( 3.14 ) ; //  1
author

Marc Alcaraz (ekameleon)

since
1.0.9
Return values
int —

-1 if the value is negative, 1 if it is positive, 0 if it is zero.

On this page

Search results