From 63216d9b1cc38128989504fe1df89dfbf056ed0c Mon Sep 17 00:00:00 2001
From: dudaodong <lanliddd.2007@163.com>
Date: Tue, 3 Sep 2024 15:54:05 +0800
Subject: [PATCH] feat: add Shuffle for string

---
 docs/api/packages/strutil.md    | 27 ++++++++++++++++++++++++++-
 docs/en/api/packages/strutil.md | 25 +++++++++++++++++++++++++
 strutil/string.go               | 18 ++++++++++++++++++
 strutil/string_test.go          | 13 +++++++++++++
 4 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/docs/api/packages/strutil.md b/docs/api/packages/strutil.md
index 57b05bf..db068a4 100644
--- a/docs/api/packages/strutil.md
+++ b/docs/api/packages/strutil.md
@@ -64,6 +64,7 @@ import (
 -   [HammingDistance](#HammingDistance)
 -   [Concat](#Concat)
 -   [Ellipsis](#Ellipsis)
+-   [Shuffle](#Shuffle)
 
 <div STYLE="page-break-after: always;"></div>
 
@@ -1576,7 +1577,7 @@ func main() {
 func Ellipsis(str string, length int) string
 ```
 
-<b>示例:<span style="float:right;display:inline-block;">[Run]()</span></b>
+<b>示例:<span style="float:right;display:inline-block;">[运行]()</span></b>
 
 ```go
 import (
@@ -1598,4 +1599,28 @@ func main() {
     // 你好...
     // 😀😃😄...
 }
+```
+
+### <span id="Shuffle">Shuffle</span>
+
+<p>打乱给定字符串中的字符顺序。</p>
+
+<b>函数签名:</b>
+
+```go
+func Shuffle(str string) string
+```
+
+<b>示例:<span style="float:right;display:inline-block;">[运行]()</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/strutil"
+)
+
+func main() {
+    result := strutil.Shuffle("hello")
+    fmt.Println(result)  //olelh (random order)
+}
 ```
\ No newline at end of file
diff --git a/docs/en/api/packages/strutil.md b/docs/en/api/packages/strutil.md
index 8adf874..3dfaad1 100644
--- a/docs/en/api/packages/strutil.md
+++ b/docs/en/api/packages/strutil.md
@@ -64,6 +64,7 @@ import (
 -   [HammingDistance](#HammingDistance)
 -   [Concat](#Concat)
 -   [Ellipsis](#Ellipsis)
+-   [Shuffle](#Shuffle)
 
 <div STYLE="page-break-after: always;"></div>
 
@@ -1600,4 +1601,28 @@ func main() {
     // 你好...
     // 😀😃😄...
 }
+```
+
+### <span id="Shuffle">Shuffle</span>
+
+<p>Shuffle the order of characters of given string.</p>
+
+<b>Signature:</b>
+
+```go
+func Shuffle(str string) string
+```
+
+<b>Example:<span style="float:right;display:inline-block;">[Run]()</span></b>
+
+```go
+import (
+    "fmt"
+    "github.com/duke-git/lancet/v2/strutil"
+)
+
+func main() {
+    result := strutil.Shuffle("hello")
+    fmt.Println(result)  //olelh (random order)
+}
 ```
\ No newline at end of file
diff --git a/strutil/string.go b/strutil/string.go
index f5473eb..4142767 100644
--- a/strutil/string.go
+++ b/strutil/string.go
@@ -5,13 +5,18 @@ package strutil
 
 import (
 	"errors"
+	"math/rand"
 	"regexp"
 	"strings"
+	"time"
 	"unicode"
 	"unicode/utf8"
 	"unsafe"
 )
 
+// used in `Shuffle` function
+var rng = rand.New(rand.NewSource(int64(time.Now().UnixNano())))
+
 // CamelCase coverts string to camelCase string. Non letters and numbers will be ignored.
 // Play: https://go.dev/play/p/9eXP3tn2tUy
 func CamelCase(s string) string {
@@ -658,3 +663,16 @@ func Ellipsis(str string, length int) string {
 
 	return string(runes[:length]) + "..."
 }
+
+// Shuffle the order of characters of given string.
+// Play: todo
+func Shuffle(str string) string {
+	runes := []rune(str)
+
+	for i := len(runes) - 1; i > 0; i-- {
+		j := rng.Intn(i + 1)
+		runes[i], runes[j] = runes[j], runes[i]
+	}
+
+	return string(runes)
+}
diff --git a/strutil/string_test.go b/strutil/string_test.go
index 430a6f2..f06dcd6 100644
--- a/strutil/string_test.go
+++ b/strutil/string_test.go
@@ -728,3 +728,16 @@ func TestEllipsis(t *testing.T) {
 		assert.Equal(tt.want, Ellipsis(tt.input, tt.length))
 	}
 }
+
+func TestShuffle(t *testing.T) {
+	t.Parallel()
+
+	assert := internal.NewAssert(t, "TestShuffle")
+
+	assert.Equal("", Shuffle(""))
+	assert.Equal("a", Shuffle("a"))
+
+	str := "hello"
+	shuffledStr := Shuffle(str)
+	assert.Equal(5, len(shuffledStr))
+}