From 49dd8bdbc2850b425f8a7196221da95ed62b3c63 Mon Sep 17 00:00:00 2001
From: "Daniel St. Jules" <danielst.jules@gmail.com>
Date: Tue, 23 Jul 2013 01:47:07 -0400
Subject: [PATCH] Add shuffle()

---
 README.md                     | 16 ++++++++++++----
 src/Stringy/Stringy.php       | 22 ++++++++++++++++++++++
 tests/Stringy/StringyTest.php | 19 +++++++++++++++++++
 3 files changed, 53 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 351ee3c..0ff24d4 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,7 @@ A PHP library with a variety of string manipulation functions with multibyte sup
     * [insert](#insert)
     * [truncate](#truncate)
     * [reverse](#reverse)
+    * [shuffle](#shuffle)
 * [Tests](#tests)
 * [License](#license)
 
@@ -362,12 +363,19 @@ Reverses a string. A multibyte version of strrev.
 S::reverse('fòô bàř', 'UTF-8'); // 'řàb ôòf'
 ```
 
+##### shuffle
+
+S::shuffle(string $str [, string $encoding ])
+
+A multibyte str_shuffle function. It randomizes the order of characters
+in a string.
+
+```php
+S::shuffle('fòô bàř', 'UTF-8') // 'àôřb òf'
+```
+
 ## TODO
 
-**shuffle** => str_shuffle
-
-**explode** => explode
-
 **longestCommonPrefix**
 
 **longestCommonSubstring**
diff --git a/src/Stringy/Stringy.php b/src/Stringy/Stringy.php
index 7025154..24dd49e 100644
--- a/src/Stringy/Stringy.php
+++ b/src/Stringy/Stringy.php
@@ -571,6 +571,28 @@ class Stringy {
         return $reversed;
     }
 
+    /**
+     * A multibyte str_shuffle function. It randomizes the order of characters
+     * in a string.
+     *
+     * @param   string  $str       String to shuffle
+     * @param   string  $encoding  The character encoding
+     * @return  string  The shuffled string
+     */
+    public static function shuffle($str, $encoding = null) {
+        $encoding = $encoding ?: mb_internal_encoding();
+
+        $indexes = range(0, mb_strlen($str, $encoding) - 1);
+        shuffle($indexes);
+
+        $shuffledStr = '';
+        foreach ($indexes as $i) {
+            $shuffledStr .= mb_substr($str, $i, 1, $encoding);
+        }
+
+        return $shuffledStr;
+    }
+
 }
 
 ?>
diff --git a/tests/Stringy/StringyTest.php b/tests/Stringy/StringyTest.php
index 6129bba..3f0ffcb 100644
--- a/tests/Stringy/StringyTest.php
+++ b/tests/Stringy/StringyTest.php
@@ -632,6 +632,25 @@ class StringyTestCase extends PHPUnit_Framework_TestCase {
         return $testData;
     }
 
+    /**
+     * @dataProvider stringsForShuffle
+     */
+    public function testShuffle($string, $encoding = null) {
+        // We'll just make sure that the chars are present before/after shuffle
+        $result = S::shuffle($string, $encoding);
+        $this->assertEquals(count_chars($string), count_chars($result));
+    }
+
+    public function stringsForShuffle() {
+        $testData = array(
+            array('foo bar'),
+            array('∂∆ ˚åß', 'UTF-8'),
+            array('å´¥©¨ˆßå˚ ∆∂˙©å∑¥øœ¬', 'UTF-8')
+        );
+
+        return $testData;
+    }
+
 }
 
 ?>