feat(mutable): shuffle

Author: samber

README.md

@@ -640,18 +640,22 @@ interleaved := lo.Interleave([]int{1}, []int{2, 5, 8}, []int{3, 6}, []int{4, 7,
 
 Returns an array of shuffled values. Uses the Fisher-Yates shuffle algorithm.
 
+⚠️ This helper is **mutable**.
+
 ```go
-randomOrder := lo.Shuffle([]int{0, 1, 2, 3, 4, 5})
+import lom "github.com/samber/lo/mutable"
+
+randomOrder := lom.Shuffle([]int{0, 1, 2, 3, 4, 5})
 // []int{1, 4, 0, 3, 5, 2}
 ```
 
-[[play](https://go.dev/play/p/Qp73bnTDnc7)]
+[[play](https://go.dev/play/p/ZTGG7OUCdnp)]
 
 ### Reverse
 
 Reverses array so that the first element becomes the last, the second element becomes the second to last, and so on.
 
-⚠️ This helper is **mutable**. This behavior might change in `v2.0.0`. See [#160](https://github.com/samber/lo/issues/160).
+⚠️ This helper is **mutable**.
 
 ```go
 import lom "github.com/samber/lo/mutable"
@@ -663,7 +667,7 @@ list
 // []int{5, 4, 3, 2, 1, 0}
 ```
 
-[[play](https://go.dev/play/p/fhUMLvZ7vS6)]
+[[play](https://go.dev/play/p/iv2e9jslfBM)]
 
 ### Fill
 

mutable/slice.go

@@ -1,5 +1,15 @@
 package mutable
 
+import "github.com/samber/lo/internal/rand"
+
+// Shuffle returns an array of shuffled values. Uses the Fisher-Yates shuffle algorithm.
+// Play: https://go.dev/play/p/ZTGG7OUCdnp
+func Shuffle[T any, Slice ~[]T](collection Slice) {
+	rand.Shuffle(len(collection), func(i, j int) {
+		collection[i], collection[j] = collection[j], collection[i]
+	})
+}
+
 // Reverse reverses array so that the first element becomes the last, the second element becomes the second to last, and so on.
 // Play: https://go.dev/play/p/iv2e9jslfBM
 func Reverse[T any, Slice ~[]T](collection Slice) {

mutable/slice_example_test.go

@@ -2,6 +2,14 @@ package mutable
 
 import "fmt"
 
+func ExampleShuffle() {
+	list := []int{0, 1, 2, 3, 4, 5}
+
+	Shuffle(list)
+
+	fmt.Printf("%v", list)
+}
+
 func ExampleReverse() {
 	list := []int{0, 1, 2, 3, 4, 5}
 

mutable/slice_test.go

@@ -6,6 +6,19 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
+func TestShuffle(t *testing.T) {
+	t.Parallel()
+	is := assert.New(t)
+
+	list := []int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
+	Shuffle(list)
+	is.NotEqual(list, []int{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10})
+
+	list = []int{}
+	Shuffle(list)
+	is.Equal(list, []int{})
+}
+
 func TestReverse(t *testing.T) {
 	t.Parallel()
 	is := assert.New(t)

slice.go

@@ -4,7 +4,6 @@ import (
 	"sort"
 
 	"github.com/samber/lo/internal/constraints"
-	"github.com/samber/lo/internal/rand"
 	"github.com/samber/lo/mutable"
 )
 
@@ -298,17 +297,17 @@ func Interleave[T any, Slice ~[]T](collections ...Slice) Slice {
 }
 
 // Shuffle returns an array of shuffled values. Uses the Fisher-Yates shuffle algorithm.
-// Play: https://go.dev/play/p/Qp73bnTDnc7
+// Play: https://go.dev/play/p/ZTGG7OUCdnp
+//
+// Deprecated: use mutable.Shuffle() instead.
 func Shuffle[T any, Slice ~[]T](collection Slice) Slice {
-	rand.Shuffle(len(collection), func(i, j int) {
-		collection[i], collection[j] = collection[j], collection[i]
-	})
-
+	mutable.Shuffle(collection)
 	return collection
 }
 
 // Reverse reverses array so that the first element becomes the last, the second element becomes the second to last, and so on.
-// Play: https://go.dev/play/p/fhUMLvZ7vS6
+// Play: https://go.dev/play/p/iv2e9jslfBM
+//
 // Deprecated: use mutable.Reverse() instead.
 func Reverse[T any, Slice ~[]T](collection Slice) Slice {
 	mutable.Reverse(collection)