feat(math): introduce additional math functions

Signed-off-by: azjezz <azjezz@protonmail.com>

CHANGELOG.md

@@ -31,3 +31,9 @@
 * introduced a new `Psl\Html\Encoding` enum.
 * **BC** - `$encoding` argument for `Psl\Html` functions now accepts `Psl\Html\Encoding` instead of `?string`.
 * **BC** - `Psl\Shell\escape_command` function has been removed, no replacement is available.
+* introduced a new `Psl\Math\acos` function.
+* introduced a new `Psl\Math\asin` function.
+* introduced a new `Psl\Math\atan` function.
+* introduced a new `Psl\Math\atan2` function.
+* **BC** - The type of the $numbers argument of `Psl\Math\mean` has changed to `list<int|float>` instead of `iterable<int|float>`.
+* **BC** - The type of the $numbers argument of `Psl\Math\median` has changed to `list<int|float>` instead of `iterable<int|float>`.

docs/component/math.md

@@ -29,30 +29,34 @@
 
 #### `Functions`
 
-- [abs](./../../src/Psl/Math/abs.php#L34)
-- [base_convert](./../../src/Psl/Math/base_convert.php#L41)
-- [ceil](./../../src/Psl/Math/ceil.php#L25)
+- [abs](./../../src/Psl/Math/abs.php#L23)
+- [acos](./../../src/Psl/Math/acos.php#L14)
+- [asin](./../../src/Psl/Math/asin.php#L14)
+- [atan](./../../src/Psl/Math/atan.php#L14)
+- [atan2](./../../src/Psl/Math/atan2.php#L14)
+- [base_convert](./../../src/Psl/Math/base_convert.php#L30)
+- [ceil](./../../src/Psl/Math/ceil.php#L14)
 - [clamp](./../../src/Psl/Math/clamp.php#L24)
-- [cos](./../../src/Psl/Math/cos.php#L22)
-- [div](./../../src/Psl/Math/div.php#L32)
-- [exp](./../../src/Psl/Math/exp.php#L22)
-- [floor](./../../src/Psl/Math/floor.php#L16)
-- [from_base](./../../src/Psl/Math/from_base.php#L29)
+- [cos](./../../src/Psl/Math/cos.php#L14)
+- [div](./../../src/Psl/Math/div.php#L21)
+- [exp](./../../src/Psl/Math/exp.php#L14)
+- [floor](./../../src/Psl/Math/floor.php#L14)
+- [from_base](./../../src/Psl/Math/from_base.php#L21)
 - [log](./../../src/Psl/Math/log.php#L18)
 - [max](./../../src/Psl/Math/max.php#L19)
-- [max_by](./../../src/Psl/Math/max_by.php#L21)
+- [max_by](./../../src/Psl/Math/max_by.php#L22)
 - [maxva](./../../src/Psl/Math/maxva.php#L20)
-- [mean](./../../src/Psl/Math/mean.php#L14)
-- [median](./../../src/Psl/Math/median.php#L15)
+- [mean](./../../src/Psl/Math/mean.php#L18)
+- [median](./../../src/Psl/Math/median.php#L19)
 - [min](./../../src/Psl/Math/min.php#L19)
-- [min_by](./../../src/Psl/Math/min_by.php#L29)
+- [min_by](./../../src/Psl/Math/min_by.php#L22)
 - [minva](./../../src/Psl/Math/minva.php#L20)
 - [round](./../../src/Psl/Math/round.php#L19)
 - [sin](./../../src/Psl/Math/sin.php#L14)
-- [sqrt](./../../src/Psl/Math/sqrt.php#L20)
+- [sqrt](./../../src/Psl/Math/sqrt.php#L18)
 - [sum](./../../src/Psl/Math/sum.php#L14)
 - [sum_floats](./../../src/Psl/Math/sum_floats.php#L14)
 - [tan](./../../src/Psl/Math/tan.php#L14)
-- [to_base](./../../src/Psl/Math/to_base.php#L18)
+- [to_base](./../../src/Psl/Math/to_base.php#L23)
 
 

src/Psl/Internal/Loader.php

@@ -157,6 +157,7 @@ final class Loader
         'Psl\Math\ceil',
         'Psl\Math\clamp',
         'Psl\Math\cos',
+        'Psl\Math\acos',
         'Psl\Math\div',
         'Psl\Math\exp',
         'Psl\Math\floor',
@@ -172,10 +173,13 @@ final class Loader
         'Psl\Math\minva',
         'Psl\Math\round',
         'Psl\Math\sin',
+        'Psl\Math\asin',
         'Psl\Math\sqrt',
         'Psl\Math\sum',
         'Psl\Math\sum_floats',
         'Psl\Math\tan',
+        'Psl\Math\atan',
+        'Psl\Math\atan2',
         'Psl\Math\to_base',
         'Psl\Result\wrap',
         'Psl\Regex\capture_groups',

src/Psl/Math/abs.php

@@ -5,18 +5,7 @@
 namespace Psl\Math;
 
 /**
- * Return the absolute value of the given number.
- *
- * Example:
- *
- *      Math\abs(5)
- *      => Int(5)
- *
- *      Math\abs(-10)
- *      => Int(10)
- *
- *      Math\abs(-5.5)
- *      => Float(5.5)
+ * Returns the absolute value of the given number.
  *
  * @template T of int|float
  *

src/Psl/Math/acos.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Math;
+
+use function acos as php_acos;
+
+/**
+ * Returns the arc cosine of the given number.
+ *
+ * @pure
+ */
+function acos(float $number): float
+{
+    return php_acos($number);
+}

src/Psl/Math/asin.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Math;
+
+use function asin as php_asin;
+
+/**
+ * Returns the arc sine of the given number.
+ *
+ * @pure
+ */
+function asin(float $number): float
+{
+    return php_asin($number);
+}

src/Psl/Math/atan.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Math;
+
+use function atan as php_atan;
+
+/**
+ * Returns the arc tangent of the given number.
+ *
+ * @pure
+ */
+function atan(float $number): float
+{
+    return php_atan($number);
+}

src/Psl/Math/atan2.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Math;
+
+use function atan2 as php_atan2;
+
+/**
+ * Returns the arc tangent of the given coordinates.
+ *
+ * @pure
+ */
+function atan2(float $y, float $x): float
+{
+    return php_atan2($y, $x);
+}

src/Psl/Math/base_convert.php

@@ -20,17 +20,6 @@
  * letters a-z are used for digits for bases greater than 10. The conversion is
  * done to arbitrary precision.
  *
- * Example:
- *
- *      Math\base_convert('10', 2, 10)
- *      => Str(2)
- *
- *      Math\base_convert('5497', 10, 2)
- *      => Str('1010101111001')
- *
- *      Math\base_convert('2014587925987', 10, 36)
- *      => Str('pphlmw9v')
- *
  * @param non-empty-string $value
  *
  * @pure

src/Psl/Math/ceil.php

@@ -9,20 +9,9 @@
 /**
  * Return the smallest integer value greater than or equal to the given number.
  *
- * Example:
- *
- *      Math\ceil(5.5)
- *      => Float(6.0)
- *
- *      Math\ceil(-10.0)
- *      => Float(-10.0)
- *
- *      Math\ceil(-5.5)
- *      => Float(-5.0)
- *
  * @pure
  */
-function ceil(float $float): float
+function ceil(float $number): float
 {
-    return php_ceil($float);
+    return php_ceil($number);
 }

src/Psl/Math/clamp.php

@@ -7,7 +7,7 @@
 use Psl;
 
 /**
- * Returns a number whose value is limited to the given range.
+ * Returns the given number clamped to the given range.
  *
  * @template T of float|int
  *

src/Psl/Math/constants.php

@@ -7,38 +7,100 @@
 use const INF;
 use const NAN as PHP_NAN;
 
+/**
+ * The value of `INFINITY` is `1 / 0` (positive infinity).
+ *
+ * @var int
+ */
+const INFINITY = INF;
+
+/**
+ * The value of `NAN` is `0 / 0` (not a number).
+ *
+ * @var float
+ */
+const NAN = PHP_NAN;
+
+/**
+ * The base of the natural system of logarithms, or approximately 2.7182818284590452353602875.
+ *
+ * @var float
+ */
+const E = 2.7182818284590452353602875;
+
+/**
+ * The ratio of the circumference of a circle to its diameter, or approximately 3.141592653589793238462643.
+ *
+ * @var float
+ */
+const PI = 3.141592653589793238462643;
+
+/**
+ * The maximum integer value representable in a 64-bit binary-coded decimal.
+ *
+ * @var int
+ */
 const INT64_MAX = 9223372036854775807;
+
+/**
+ * The minimum integer value representable in a 64-bit binary-coded decimal.
+ *
+ * @var int
+ */
 const INT64_MIN = -1 << 63;
 
+/**
+ * The maximum integer value representable in a 53-bit binary-coded decimal.
+ *
+ * @var int
+ */
 const INT53_MAX = 9007199254740992;
+
+/**
+ * The minimum integer value representable in a 53-bit binary-coded decimal.
+ *
+ * @var int
+ */
 const INT53_MIN = -9007199254740993;
 
+/**
+ * The maximum integer value representable in a 32-bit binary-coded decimal.
+ *
+ * @var int
+ */
 const INT32_MAX = 2147483647;
+
+/**
+ * The minimum integer value representable in a 32-bit binary-coded decimal.
+ *
+ * @var int
+ */
 const INT32_MIN = -2147483648;
 
+/**
+ * The maximum integer value representable in a 16-bit binary-coded decimal.
+ *
+ * @var int
+ */
 const INT16_MAX = 32767;
-const INT16_MIN = -32768;
-
-const UINT32_MAX = 4294967295;
-const UINT16_MAX = 65535;
-
-const PI = 3.141592653589793238462643;
 
 /**
- * The base of the natural system of logarithms, or approximately 2.7182818284590452353602875.
+ * The minimum integer value representable in a 16-bit binary-coded decimal.
+ *
+ * @var int
  */
-const E = 2.7182818284590452353602875;
+const INT16_MIN = -32768;
 
 /**
- * The infinite.
+ * The maximum unsigned integer value representable in a 32-bit binary-coded decimal.
  *
  * @var int
  */
-const INFINITY = INF;
+const UINT32_MAX = 4294967295;
 
 /**
- * Not A Number.
+ * The maximum unsigned integer value representable in a 16-bit binary-coded decimal.
  *
- * @var float
+ * @var int
  */
-const NAN = PHP_NAN;
+const UINT16_MAX = 65535;

src/Psl/Math/cos.php

@@ -9,17 +9,9 @@
 /**
  * Return the cosine of the given number.
  *
- * Example:
- *
- *      Math\cos(0.0)
- *      => Float(1.0)
- *
- *      Math\ceil(1.0)
- *      => Float(0.5403023058681398)
- *
  * @pure
  */
-function cos(float $num): float
+function cos(float $number): float
 {
-    return php_cos($num);
+    return php_cos($number);
 }

src/Psl/Math/div.php

@@ -13,17 +13,6 @@
 /**
  * Returns the result of integer division of the given numerator by the given denominator.
  *
- * Example:
- *
- *      Math\div(10, 2)
- *      => Int(5)
- *
- *      Math\div(5, 2)
- *      => Int(2)
- *
- *      Math\div(15, 20)
- *      => Int(0)
- *
  * @pure
  *
  * @throws Exception\ArithmeticException If the $numerator is Math\INT64_MIN and the $denominator is -1.

src/Psl/Math/exp.php

@@ -7,19 +7,11 @@
 use function exp as php_exp;
 
 /**
- * Returns Math\E to the power of the given number.
- *
- *  Example:
- *
- *      Math\exp(12)
- *      => Float(162754.79141900392)
- *
- *      Math\exp(5.7)
- *      => Float(298.8674009670603)
+ * Returns the exponential of the given number.
  *
  * @pure
  */
-function exp(float $num): float
+function exp(float $number): float
 {
-    return php_exp($num);
+    return php_exp($number);
 }