Added slice

README.md

@@ -70,6 +70,7 @@ s('string')->toTitleCase()->ensureRight('y') == 'Stringy'
     * [shuffle](#shuffle)
     * [slugify](#slugify-string-replacement----)
     * [startsWith](#startswithstring-substring--boolean-casesensitive--true-)
+    * [slice](#sliceint-start--int-end-)
     * [substr](#substrint-start--int-length-)
     * [surround](#surroundstring-substring)
     * [swapCase](#swapcase)
@@ -697,6 +698,17 @@ by setting $caseSensitive to false.
 S::create('FÒÔ bàřs')->startsWith('fòô bàř', false); // true
 ```
 
+##### slice(int $start [, int $end ])
+
+Returns the substring beginning at $start, and up to, but not including
+the index specified by $end. If $end is omitted, the function extracts
+the remaining string. If $end is negative, it is computed from the end
+of the string.
+
+```php
+S::create('fòôbàř')->slice(3, -1); // 'bà'
+```
+
 ##### substr(int $start [, int $length ])
 
 Returns the substring beginning at $start with the specified $length.

src/Stringy.php

@@ -1305,6 +1305,33 @@ class Stringy implements \Countable, \IteratorAggregate, \ArrayAccess
         return mb_strlen($this->str, $this->encoding);
     }
 
+    /**
+     * Returns the substring beginning at $start, and up to, but not including
+     * the index specified by $end. If $end is omitted, the function extracts
+     * the remaining string. If $end is negative, it is computed from the end
+     * of the string.
+     *
+     * @param  int     $start Initial index from which to begin extraction
+     * @param  int     $end   Optional index at which to end extraction
+     * @return Stringy Object with its $str being the extracted substring
+     */
+    public function slice($start, $end = null)
+    {
+        if ($end === null) {
+            $length = $this->length();
+        } elseif ($end >= 0 && $end <= $start) {
+            return static::create('', $this->encoding);
+        } elseif ($end < 0) {
+            $length = $this->length() + $end - $start;
+        } else {
+            $length = $end - $start;
+        }
+
+        $str = mb_substr($this->str, $start, $length, $this->encoding);
+
+        return static::create($str, $this->encoding);
+    }
+
     /**
      * 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

@@ -1593,6 +1593,41 @@ class StringyTestCase extends PHPUnit_Framework_TestCase
         );
     }
 
+    /**
+     * @dataProvider sliceProvider()
+     */
+    public function testSlice($expected, $str, $start, $end = null,
+                              $encoding = null)
+    {
+        $stringy = S::create($str, $encoding);
+        $result = $stringy->slice($start, $end);
+        $this->assertStringy($result);
+        $this->assertEquals($expected, $result);
+        $this->assertEquals($str, $stringy);
+    }
+
+    public function sliceProvider()
+    {
+        return array(
+            array('foobar', 'foobar', 0),
+            array('foobar', 'foobar', 0, null),
+            array('foobar', 'foobar', 0, 6),
+            array('fooba', 'foobar', 0, 5),
+            array('', 'foobar', 3, 0),
+            array('', 'foobar', 3, 2),
+            array('ba', 'foobar', 3, 5),
+            array('ba', 'foobar', 3, -1),
+            array('fòôbàř', 'fòôbàř', 0, null, 'UTF-8'),
+            array('fòôbàř', 'fòôbàř', 0, null),
+            array('fòôbàř', 'fòôbàř', 0, 6, 'UTF-8'),
+            array('fòôbà', 'fòôbàř', 0, 5, 'UTF-8'),
+            array('', 'fòôbàř', 3, 0, 'UTF-8'),
+            array('', 'fòôbàř', 3, 2, 'UTF-8'),
+            array('bà', 'fòôbàř', 3, 5, 'UTF-8'),
+            array('bà', 'fòôbàř', 3, -1, 'UTF-8')
+        );
+    }
+
     /**
      * @dataProvider substrProvider()
      */