Merge branch 'main' into v2

docs/api/packages/slice.md

@@ -2488,4 +2488,35 @@ func main() {
 	// [[2 4] [1 3 5]]
 	// [[1 2] [3 4] [5]]
 }
+```
+
+
+### <span id="Random">Random</span>
+
+<p>随机返回切片中元素以及下标, 当切片长度为0时返回下标-1</p>
+
+<b>函数签名:</b>
+
+```go
+func Random[T any](slice []T) (val T, idx int)
+```
+
+<b>示例:<span style="float:right;display:inline-block;">[运行](TODO)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/slice"
+)
+
+func main() {
+	nums := []int{1, 2, 3, 4, 5}
+
+	val, idx := slice.Random(nums)
+	if idx >= 0 && idx < len(nums) && slice.Contain(nums, val) {
+		fmt.Println("okk")
+	}
+	// Output:
+	// okk
+}
 ```

docs/en/api/packages/slice.md

@@ -2486,4 +2486,34 @@ func main() {
 	// [[2 4] [1 3 5]]
 	// [[1 2] [3 4] [5]]
 }
+```
+
+### <span id="Random">Random</span>
+
+<p>Random get a random item of slice, return idx=-1 when slice is empty. </p>
+
+<b>Signature:</b>
+
+```go
+func Random[T any](slice []T) (val T, idx int)
+```
+
+<b>Example:<span style="float:right;display:inline-block;">[Run](TODO)</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/slice"
+)
+
+func main() {
+	nums := []int{1, 2, 3, 4, 5}
+
+	val, idx := slice.Random(nums)
+	if idx >= 0 && idx < len(nums) && slice.Contain(nums, val) {
+		fmt.Println("okk")
+	}
+	// Output:
+	// okk
+}
 ```

slice/slice.go

@@ -12,6 +12,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/duke-git/lancet/v2/random"
 	"golang.org/x/exp/constraints"
 )
 
@@ -1229,3 +1230,14 @@ func Partition[T any](slice []T, predicates ...func(item T) bool) [][]T {
 
 	return result
 }
+
+// Random get a random item of slice, return idx=-1 when slice is empty
+// Play: todo
+func Random[T any](slice []T) (val T, idx int) {
+	if len(slice) == 0 {
+		return val, -1
+	}
+
+	idx = random.RandInt(0, len(slice))
+	return slice[idx], idx
+}

slice/slice_example_test.go

@@ -1063,3 +1063,14 @@ func ExamplePartition() {
 	// [[2 4] [1 3 5]]
 	// [[1 2] [3 4] [5]]
 }
+
+func ExampleRandom() {
+	nums := []int{1, 2, 3, 4, 5}
+
+	val, idx := Random(nums)
+	if idx >= 0 && idx < len(nums) && Contain(nums, val) {
+		fmt.Println("okk")
+	}
+	// Output:
+	// okk
+}

slice/slice_test.go

@@ -1185,3 +1185,28 @@ func TestPartition(t *testing.T) {
 	assert.Equal([][]int{{2, 4}, {1, 3, 5}}, Partition([]int{1, 2, 3, 4, 5}, func(n int) bool { return n%2 == 0 }))
 	assert.Equal([][]int{{1, 2}, {3, 4}, {5}}, Partition([]int{1, 2, 3, 4, 5}, func(n int) bool { return n == 1 || n == 2 }, func(n int) bool { return n == 2 || n == 3 || n == 4 }))
 }
+
+func TestRandom(t *testing.T) {
+	t.Parallel()
+	assert := internal.NewAssert(t, "TestRandom")
+
+	var arr []int
+	var val, idx int
+
+	_, idx = Random(arr)
+	assert.Equal(-1, idx)
+
+	arr = []int{}
+	_, idx = Random(arr)
+	assert.Equal(-1, idx)
+
+	arr = []int{1}
+	val, idx = Random(arr)
+	assert.Equal(0, idx)
+	assert.Equal(arr[idx], val)
+
+	arr = []int{1, 2, 3}
+	val, idx = Random(arr)
+	assert.Greater(len(arr), idx)
+	assert.Equal(arr[idx], val)
+}