From 699707a0db372bc44ca5619b6ca61c15f5dc1de6 Mon Sep 17 00:00:00 2001
From: Samuel Berthe <dev@samuel-berthe.fr>
Date: Sun, 26 Jan 2025 00:02:51 +0100
Subject: [PATCH] feat(mutable): shuffle

---
 README.md                     | 12 ++++++++----
 mutable/slice.go              | 10 ++++++++++
 mutable/slice_example_test.go |  8 ++++++++
 mutable/slice_test.go         | 13 +++++++++++++
 slice.go                      | 13 ++++++-------
 5 files changed, 45 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index b5739a78..30aeb269 100644
--- a/README.md
+++ b/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
 
diff --git a/mutable/slice.go b/mutable/slice.go
index 136cf421..6d61fa77 100644
--- a/mutable/slice.go
+++ b/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) {
diff --git a/mutable/slice_example_test.go b/mutable/slice_example_test.go
index 21b94567..689fd8bd 100644
--- a/mutable/slice_example_test.go
+++ b/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}
 
diff --git a/mutable/slice_test.go b/mutable/slice_test.go
index 67448fc6..7e10851b 100644
--- a/mutable/slice_test.go
+++ b/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)
diff --git a/slice.go b/slice.go
index 19f356c3..dd0c458a 100644
--- a/slice.go
+++ b/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)