feat: add Variance for math package

docs/api/packages/mathutil.md

@@ -1163,3 +1163,36 @@ func main() {
     // 0
 }
 ```
+
+### <span id="Variance">Variance</span>
+
+<p>计算方差</p>
+
+<b>函数签名:</b>
+
+```go
+func Variance[T constraints.Float | constraints.Integer](numbers []T) float64
+```
+
+<b>示例:<span style="float:right;display:inline-block;">[示例](todo)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/mathutil"
+)
+
+func main() {
+    result1 := mathutil.Variance([]int{1, 2, 3, 4, 5})
+    result2 := mathutil.Variance([]float64{1.1, 2.2, 3.3, 4.4, 5.5})
+
+    fmt.Println(result1)
+    fmt.Println(result2)
+
+    // Output:
+    // 2
+    // 2.42
+}
+```

docs/en/api/packages/mathutil.md

@@ -52,6 +52,7 @@ import (
 -   [Sum](#Sum)
 -   [Abs](#Abs)
 -   [Div](#Div)
+-   [Variance](#Variance)
 
 <div STYLE="page-break-after: always;"></div>
 
@@ -1162,3 +1163,36 @@ func main() {
     // 0
 }
 ```
+
+### <span id="Variance">Variance</span>
+
+<p>Returns the variance of numbers.</p>
+
+<b>Signature:</b>
+
+```go
+func Variance[T constraints.Float | constraints.Integer](numbers []T) float64
+```
+
+<b>Example:<span style="float:right;display:inline-block;">[Run](todo)</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/mathutil"
+)
+
+func main() {
+    result1 := mathutil.Variance([]int{1, 2, 3, 4, 5})
+	result2 := mathutil.Variance([]float64{1.1, 2.2, 3.3, 4.4, 5.5})
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+
+	// Output:
+	// 2
+	// 2.42
+}
+```

mathutil/mathutil.go

@@ -395,3 +395,21 @@ func Abs[T constraints.Integer | constraints.Float](x T) T {
 func Div[T constraints.Float | constraints.Integer](x T, y T) float64 {
 	return float64(x) / float64(y)
 }
+
+// Variance returns the variance of numbers.
+// Play: todo
+func Variance[T constraints.Float | constraints.Integer](numbers []T) float64 {
+	n := len(numbers)
+	if n == 0 {
+		return 0
+	}
+
+	avg := Average(numbers...)
+	var sum T
+
+	for _, v := range numbers {
+		sum += (v - avg) * (v - avg)
+	}
+
+	return float64(sum) / float64(n)
+}

mathutil/mathutil_exmaple_test.go

@@ -478,3 +478,15 @@ func ExampleDiv() {
 	// 0.5
 	// 0
 }
+
+func ExampleVariance() {
+	result1 := Variance([]int{1, 2, 3, 4, 5})
+	result2 := Variance([]float64{1.1, 2.2, 3.3, 4.4, 5.5})
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+
+	// Output:
+	// 2
+	// 2.42
+}

mathutil/mathutil_test.go

@@ -413,3 +413,36 @@ func TestDiv(t *testing.T) {
 	assert.Equal(math.Inf(-1), Div(-8, 0))
 	assert.Equal(true, math.IsNaN(Div(0, 0)))
 }
+
+func TestVariance(t *testing.T) {
+	t.Parallel()
+
+	assert := internal.NewAssert(t, "TestVariance")
+
+	testIntNumbers := []struct {
+		numbers  []int
+		expected float64
+	}{
+		{[]int{0}, 0},
+		{[]int{1, 1, 1}, 0},
+		{[]int{1, 2, 3, 4}, 1.5},
+		{[]int{1, 2, 3, 4, 5}, 2.0},
+	}
+
+	for _, tt := range testIntNumbers {
+		assert.Equal(tt.expected, TruncRound(Variance(tt.numbers), 2))
+	}
+
+	testFloatNumbers := []struct {
+		numbers  []float64
+		expected float64
+	}{
+		{[]float64{0}, 0},
+		{[]float64{1, 1, 1}, 0},
+		{[]float64{1.1, 2.2, 3.3, 4.4}, 1.51},
+	}
+
+	for _, tt := range testFloatNumbers {
+		assert.Equal(tt.expected, TruncRound(Variance(tt.numbers), 2))
+	}
+}