diff --git a/README.md b/README.md index dcbf745..a0ee119 100644 --- a/README.md +++ b/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' ``` diff --git a/src/Stringy.php b/src/Stringy.php index c3a2364..14c66ec 100644 --- a/src/Stringy.php +++ b/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 diff --git a/tests/StringyTest.php b/tests/StringyTest.php index 1e57005..884f551 100644 --- a/tests/StringyTest.php +++ b/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() */