From 7b4e060f85054c0974a7d960567f8f5baeabcf65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=AE=8B=E5=BF=B5?= <2081215119@qq.com>
Date: Wed, 14 Aug 2024 19:36:12 +0800
Subject: [PATCH] feat: add RandFromGivenSlice function (#235)

* feat: add RandFromGivenSlice function

* feat: add RandFromGivenSlice function
---
 docs/api/packages/random.md    | 28 ++++++++++++++++++++++++++++
 docs/en/api/packages/random.md | 27 +++++++++++++++++++++++++++
 random/random.go               |  9 +++++++++
 random/random_example_test.go  | 18 ++++++++++++++++++
 random/random_test.go          | 23 +++++++++++++++++++++++
 5 files changed, 105 insertions(+)

diff --git a/docs/api/packages/random.md b/docs/api/packages/random.md
index 1b39d5b7..c08ea148 100644
--- a/docs/api/packages/random.md
+++ b/docs/api/packages/random.md
@@ -25,6 +25,7 @@ import (
 -   [RandBytes](#RandBytes)
 -   [RandInt](#RandInt)
 -   [RandString](#RandString)
+-   [RandFromGivenSlice](#RandFromGivenSlice)
 -   [RandUpper](#RandUpper)
 -   [RandLower](#RandLower)
 -   [RandNumeral](#RandNumeral)
@@ -122,6 +123,33 @@ func main() {
 }
 ```
 
+### <span id="RandFromGivenSlice">RandFromGivenSlice</span>
+
+<p>从给定切片中随机生成元素</p>
+
+<b>函数签名:</b>
+
+```go
+func RandFromGivenSlice[T any](slice []T) T
+```
+
+<b>示例:<span style="float:right;display:inline-block;">[运行]()</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/random"
+)
+
+func main() {
+    nicknames := []string{"张三", "李四", "王五", "赵六", "钱七"}
+    randElm := random.RandFromGivenSlice(nicknames)
+    fmt.Println(randElm)
+}
+```
+
 ### <span id="RandUpper">RandUpper</span>
 
 <p>生成给定长度的随机大写字母字符串</p>
diff --git a/docs/en/api/packages/random.md b/docs/en/api/packages/random.md
index f6cdbe55..173ee49c 100644
--- a/docs/en/api/packages/random.md
+++ b/docs/en/api/packages/random.md
@@ -121,6 +121,33 @@ func main() {
 }
 ```
 
+### <span id="RandFromGivenSlice">RandFromGivenSlice</span>
+
+<p>Generate a random element from given slice.</p>
+
+<b>Signature:</b>
+
+```go
+func RandFromGivenSlice[T any](slice []T) T
+```
+
+<b>Example:<span style="float:right;display:inline-block;">[Run]()</span></b>
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/random"
+)
+
+func main() {
+    randomSet := []any{"a", 8, "hello", true, 1.1}
+    randElm := random.RandFromGivenSlice(randomSet)
+    fmt.Println(randElm)
+}
+```
+
 ### <span id="RandUpper">RandUpper</span>
 
 <p>Generate a random upper case string</p>
diff --git a/random/random.go b/random/random.go
index a87bb170..1a7b9707 100644
--- a/random/random.go
+++ b/random/random.go
@@ -185,6 +185,15 @@ func RandStringSlice(charset string, sliceLen, strLen int) []string {
 	return result
 }
 
+// RandFromGivenSlice generate a random element from given slice.
+func RandFromGivenSlice[T any](slice []T) T {
+	if len(slice) == 0 {
+		var zero T
+		return zero
+	}
+	return slice[rand.Intn(len(slice))]
+}
+
 // RandUpper generate a random upper case string of specified length.
 // Play: https://go.dev/play/p/29QfOh0DVuh
 func RandUpper(length int) string {
diff --git a/random/random_example_test.go b/random/random_example_test.go
index 26b40269..bd1a728e 100644
--- a/random/random_example_test.go
+++ b/random/random_example_test.go
@@ -43,6 +43,24 @@ func ExampleRandString() {
 	// 6
 }
 
+func ExampleRandFromGivenSlice() {
+	goods := []string{"apple", "banana", "cherry", "elderberry", "fig", "grape", "honeydew", "kiwi", "lemon",
+		"mango", "nectarine", "orange"}
+
+	isInGoods := false
+	result := RandFromGivenSlice(goods)
+	for _, good := range goods {
+		if good == result {
+			isInGoods = true
+			break
+		}
+	}
+	fmt.Println(isInGoods)
+
+	// Output:
+	// true
+}
+
 func ExampleRandUpper() {
 	pattern := `^[A-Z]+$`
 	reg := regexp.MustCompile(pattern)
diff --git a/random/random_test.go b/random/random_test.go
index 4da729e4..500b7eeb 100644
--- a/random/random_test.go
+++ b/random/random_test.go
@@ -269,6 +269,29 @@ func TestRandStringSlice(t *testing.T) {
 	// })
 }
 
+func TestRandFromGivenSlice(t *testing.T) {
+	t.Parallel()
+	assert := internal.NewAssert(t, "TestRandFromGivenSlice")
+
+	randomSet := []any{"a", 8, "王", true, 1.1}
+	result := RandFromGivenSlice(randomSet)
+	find := false
+	for _, v := range randomSet {
+		if v == result {
+			find = true
+		}
+	}
+	assert.Equal(true, find)
+
+	emptyAnyRandomSet := []any{}
+	emptyAnyResult := RandFromGivenSlice(emptyAnyRandomSet)
+	assert.IsNil(emptyAnyResult)
+
+	emptyIntRandomSet := []int{}
+	emtpyIntResult := RandFromGivenSlice(emptyIntRandomSet)
+	assert.Equal(0, emtpyIntResult)
+}
+
 func TestRandBool(t *testing.T) {
 	t.Parallel()
 	assert := internal.NewAssert(t, "TestRandBool")