Added split

README.md

@@ -71,6 +71,7 @@ s('string')->toTitleCase()->ensureRight('y') == 'Stringy'
     * [slugify](#slugify-string-replacement----)
     * [startsWith](#startswithstring-substring--boolean-casesensitive--true-)
     * [slice](#sliceint-start--int-end-)
+    * [split](#splitstring-pattern--int-limit-)
     * [substr](#substrint-start--int-length-)
     * [surround](#surroundstring-substring)
     * [swapCase](#swapcase)
@@ -257,7 +258,7 @@ Returns an array consisting of the characters in the string.
 
 ```php
 S::create('Fòô Bàř')->chars();
-// array(F', 'ò', 'ô', ' ', 'B', 'à', 'ř')
+// [F', 'ò', 'ô', ' ', 'B', 'à', 'ř']
 ```
 
 ##### collapseWhitespace()
@@ -287,7 +288,7 @@ default the comparison is case-sensitive, but can be made insensitive by
 setting $caseSensitive to false.
 
 ```php
-S::create('Str contains foo and bar')->containsAll(array('foo', 'bar')); // true
+S::create('Str contains foo and bar')->containsAll(['foo', 'bar']); // true
 ```
 
 ##### containsAny(array $needles [, boolean $caseSensitive = true ])
@@ -297,7 +298,7 @@ default the comparison is case-sensitive, but can be made insensitive by
 setting $caseSensitive to false.
 
 ```php
-S::create('Str contains foo')->containsAny(array('foo', 'bar')); // true
+S::create('Str contains foo')->containsAny(['foo', 'bar']); // true
 ```
 
 ##### countSubstr(string $substring [, boolean $caseSensitive = true ])
@@ -709,6 +710,16 @@ of the string.
 S::create('fòôbàř')->slice(3, -1); // 'bà'
 ```
 
+##### split(string $pattern [, int $limit ])
+
+Splits the string with the provided regular expression, returning an
+array of Stringy objects. An optional integer $limit will truncate the
+numbers of results returned.
+
+```php
+S::create('foo,bar,baz')->split(',', 2); // ['foo', 'bar']
+```
+
 ##### substr(int $start [, int $length ])
 
 Returns the substring beginning at $start with the specified $length.
@@ -751,7 +762,7 @@ Ignores the case of other letters, preserving any acronyms. Also accepts
 an array, $ignore, allowing you to list words not to be capitalized.
 
 ```php
-$ignore = array('at', 'by', 'for', 'in', 'of', 'on', 'out', 'to', 'the');
+$ignore = ['at', 'by', 'for', 'in', 'of', 'on', 'out', 'to', 'the'];
 S::create('i like to watch DVDs at home')->titleize($ignore);
 // 'I Like to Watch DVDs at Home'
 ```

src/Stringy.php

@@ -1332,6 +1332,41 @@ class Stringy implements \Countable, \IteratorAggregate, \ArrayAccess
         return static::create($str, $this->encoding);
     }
 
+    /**
+     * Splits the string with the provided regular expression, returning an
+     * array of Stringy objects. An optional integer $limit will truncate the
+     * numbers of results returned.
+     *
+     * @param  string    $pattern The regex with which to split the string
+     * @param  int       $limit   Optional maximum number of results to return
+     * @return Stringy[] An array of Stringy objects
+     */
+    public function split($pattern, $limit = null)
+    {
+        if ($limit === 0) {
+            return array();
+        }
+
+        $regexEncoding = mb_regex_encoding();
+        mb_regex_encoding($this->encoding);
+
+        // mb_split returns the remaining unsplit string in the last index when
+        // supplying a limit
+        $limit = ($limit > 0) ? $limit += 1 : -1;
+        $array = mb_split($pattern, $this->str, $limit);
+        mb_regex_encoding($regexEncoding);
+
+        if ($limit > 0 && count($array) === $limit) {
+            array_pop($array);
+        }
+
+        for ($i = 0; $i < count($array); $i++) {
+            $array[$i] = static::create($array[$i], $this->encoding);
+        }
+
+        return $array;
+    }
+
     /**
      * Returns the substring beginning at $start with the specified $length.
      * It differs from the mb_substr() function in that providing a $length of

tests/StringyTest.php

@@ -1628,6 +1628,50 @@ class StringyTestCase extends PHPUnit_Framework_TestCase
         );
     }
 
+    /**
+     * @dataProvider splitProvider()
+     */
+    public function testSplit($expected, $str, $pattern, $limit = null,
+                              $encoding = null)
+    {
+        $stringy = S::create($str, $encoding);
+        $result = $stringy->split($pattern, $limit);
+
+        $this->assertInternalType('array', $result);
+        foreach ($result as $string) {
+            $this->assertStringy($string);
+        }
+
+        for ($i = 0; $i < count($expected); $i++) {
+            $this->assertEquals($expected[$i], $result[$i]);
+        }
+    }
+
+    public function splitProvider()
+    {
+        return array(
+            array(array('foo,bar,baz'), 'foo,bar,baz', ''),
+            array(array('foo,bar,baz'), 'foo,bar,baz', '-'),
+            array(array('foo', 'bar', 'baz'), 'foo,bar,baz', ','),
+            array(array('foo', 'bar', 'baz'), 'foo,bar,baz', ',', null),
+            array(array('foo', 'bar', 'baz'), 'foo,bar,baz', ',', -1),
+            array(array(), 'foo,bar,baz', ',', 0),
+            array(array('foo'), 'foo,bar,baz', ',', 1),
+            array(array('foo', 'bar'), 'foo,bar,baz', ',', 2),
+            array(array('foo', 'bar', 'baz'), 'foo,bar,baz', ',', 3),
+            array(array('foo', 'bar', 'baz'), 'foo,bar,baz', ',', 10),
+            array(array('fòô,bàř,baz'), 'fòô,bàř,baz', '-', null, 'UTF-8'),
+            array(array('fòô', 'bàř', 'baz'), 'fòô,bàř,baz', ',', null, 'UTF-8'),
+            array(array('fòô', 'bàř', 'baz'), 'fòô,bàř,baz', ',', null, 'UTF-8'),
+            array(array('fòô', 'bàř', 'baz'), 'fòô,bàř,baz', ',', -1, 'UTF-8'),
+            array(array(), 'fòô,bàř,baz', ',', 0, 'UTF-8'),
+            array(array('fòô'), 'fòô,bàř,baz', ',', 1, 'UTF-8'),
+            array(array('fòô', 'bàř'), 'fòô,bàř,baz', ',', 2, 'UTF-8'),
+            array(array('fòô', 'bàř', 'baz'), 'fòô,bàř,baz', ',', 3, 'UTF-8'),
+            array(array('fòô', 'bàř', 'baz'), 'fòô,bàř,baz', ',', 10, 'UTF-8')
+        );
+    }
+
     /**
      * @dataProvider substrProvider()
      */