From 0773dfd6a2f707522f1545f9f5086d14695a2ce9 Mon Sep 17 00:00:00 2001
From: Simon Podlipsky <simon@podlipsky.net>
Date: Sat, 6 Apr 2024 11:26:44 +0200
Subject: [PATCH] feat: narrow return type for `min()`, `max()`, `median()` and
 `mean()`

Consider whether the input is empty or not
---
 docs/component/math.md  | 4 ++--
 src/Psl/Math/max.php    | 2 +-
 src/Psl/Math/mean.php   | 2 ++
 src/Psl/Math/median.php | 2 ++
 src/Psl/Math/min.php    | 2 +-
 5 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/component/math.md b/docs/component/math.md
index 979bb33d..8f64ccff 100644
--- a/docs/component/math.md
+++ b/docs/component/math.md
@@ -46,8 +46,8 @@
 - [max](./../../src/Psl/Math/max.php#L19)
 - [max_by](./../../src/Psl/Math/max_by.php#L24)
 - [maxva](./../../src/Psl/Math/maxva.php#L20)
-- [mean](./../../src/Psl/Math/mean.php#L18)
-- [median](./../../src/Psl/Math/median.php#L19)
+- [mean](./../../src/Psl/Math/mean.php#L20)
+- [median](./../../src/Psl/Math/median.php#L21)
 - [min](./../../src/Psl/Math/min.php#L19)
 - [min_by](./../../src/Psl/Math/min_by.php#L24)
 - [minva](./../../src/Psl/Math/minva.php#L20)
diff --git a/src/Psl/Math/max.php b/src/Psl/Math/max.php
index 8596ea00..eaf90f50 100644
--- a/src/Psl/Math/max.php
+++ b/src/Psl/Math/max.php
@@ -12,7 +12,7 @@
  *
  * @param list<T> $numbers
  *
- * @return T|null
+ * @return ($numbers is non-empty-list<T> ? T : null)
  *
  * @pure
  */
diff --git a/src/Psl/Math/mean.php b/src/Psl/Math/mean.php
index fdeaba98..3ddc799b 100644
--- a/src/Psl/Math/mean.php
+++ b/src/Psl/Math/mean.php
@@ -13,6 +13,8 @@
  *
  * @param list<int|float> $numbers
  *
+ * @return ($numbers is non-empty-list ? float : null)
+ *
  * @pure
  */
 function mean(array $numbers): ?float
diff --git a/src/Psl/Math/median.php b/src/Psl/Math/median.php
index f6a7a6b4..bf104db5 100644
--- a/src/Psl/Math/median.php
+++ b/src/Psl/Math/median.php
@@ -14,6 +14,8 @@
  *
  * @param list<int|float> $numbers
  *
+ * @return ($numbers is non-empty-list ? float : null)
+ *
  * @pure
  */
 function median(array $numbers): ?float
diff --git a/src/Psl/Math/min.php b/src/Psl/Math/min.php
index 082d8a96..6e6a97b4 100644
--- a/src/Psl/Math/min.php
+++ b/src/Psl/Math/min.php
@@ -12,7 +12,7 @@
  *
  * @param list<T> $numbers
  *
- * @return T|null
+ * @return ($numbers is non-empty-list<T> ? T : null)
  *
  * @pure
  */