Added substr()

README.md

@@ -39,6 +39,7 @@ Note: The methods listed below are subject to change until we reach a 1.0.0 rele
     * [longestCommonSuffix](#longestcommonsuffix)
     * [longestCommonSubstring](#longestcommonsubstring)
     * [length](#length)
+    * [substr](#substr)
 * [Tests](#tests)
 * [License](#license)
 
@@ -572,6 +573,21 @@ S::create('fòô bàř', 'UTF-8')->length();
 S::length('fòô bàř', 'UTF-8');  // 7
 ```
 
+##### substr
+
+$stringy->substr(int $start [, int $length ])
+
+S::substr(string $str, int $start [, int $length [, string $encoding ]])
+
+Gets the substring of $str beginning at $start with the specified $length.
+It differs from the mb_substr() function in that providing a $length of
+null will return the rest of the string, rather than an empty string.
+
+```php
+S::create('fòô bàř', 'UTF-8')->substr(2, 3);
+S::substr('fòô bàř', 2, 3, 'UTF-8');  // 'ô b'
+```
+
 ## TODO
 
 **count** => substr_count

src/Stringy/StaticStringy.php

@@ -450,10 +450,25 @@ class StaticStringy
      *
      * @param   string  $str       The string to get the length of
      * @param   string  $encoding  The character encoding
-     * @return  int  The number of characters in $str given the encoding
+     * @return  int     The number of characters in $str given the encoding
      */
     public static function length($str, $encoding = null)
     {
         return Stringy::create($str, $encoding)->length();
     }
+
+    /**
+     * Gets the substring of $str beginning at $start with the specified $length.
+     * It differs from the mb_substr() function in that providing a $length of
+     * null will return the rest of the string, rather than an empty string.
+     *
+     * @param   string  $str     The string to get the length of
+     * @param   int     $start   Position of the first character to use from str
+     * @param   int     $length  Maximum number of characters used
+     * @return  string  The substring of $str
+     */
+    public static function substr($str, $start, $length = null, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->substr($start, $length);
+    }
 }

src/Stringy/Stringy.php

@@ -628,6 +628,7 @@ class Stringy
     /**
      * Finds the longest common prefix between $str and $otherStr.
      *
+     * @param   string   $otherStr  Second string for comparison
      * @return  Stringy  Object with its $str being the longest common prefix
      */
     public function longestCommonPrefix($otherStr)
@@ -653,6 +654,7 @@ class Stringy
     /**
      * Finds the longest common suffix between $str and $otherStr.
      *
+     * @param   string   $otherStr  Second string for comparison
      * @return  Stringy  Object with its $str being the longest common suffix
      */
     public function longestCommonSuffix($otherStr)
@@ -679,6 +681,7 @@ class Stringy
      * Finds the longest common substring between $str and $otherStr. In the
      * case of ties, returns that which occurs first.
      *
+     * @param   string   $otherStr  Second string for comparison
      * @return  Stringy  Object with its $str being the longest common substring
      */
     public function longestCommonSubstring($otherStr)
@@ -729,4 +732,25 @@ class Stringy
     {
         return mb_strlen($this->str, $this->encoding);
     }
+
+    /**
+     * Gets the substring of $str beginning at $start with the specified $length.
+     * It differs from the mb_substr() function in that providing a $length of
+     * null will return the rest of the string, rather than an empty string.
+     *
+     * @param   int  $start   Position of the first character to use from str
+     * @param   int  $length  Maximum number of characters used
+     * @return  Stringy  Object with its $str being the substring
+     */
+    public function substr($start, $length = null)
+    {
+        if ($length === null) {
+            $this->str = mb_substr($this->str, $start, $this->length() - $start,
+                $this->encoding);
+        } else {
+            $this->str = mb_substr($this->str, $start, $length, $this->encoding);
+        }
+
+        return $this;
+    }
 }

tests/Stringy/CommonTest.php

@@ -529,6 +529,23 @@ class CommonTest extends PHPUnit_Framework_TestCase
         return $testData;
     }
 
+    public function stringsForSubstr()
+    {
+        $testData = array(
+            array('foo bar', 'foo bar', 0),
+            array('bar', 'foo bar', 4),
+            array('bar', 'foo bar', 4, null),
+            array('o b', 'foo bar', 2, 3),
+            array('', 'foo bar', 4, 0),
+            array('fòô bàř', 'fòô bàř', 0, null, 'UTF-8'),
+            array('bàř', 'fòô bàř', 4, null, 'UTF-8'),
+            array('ô b', 'fòô bàř', 2, 3, 'UTF-8'),
+            array('', 'fòô bàř', 4, 0, 'UTF-8')
+        );
+
+        return $testData;
+    }
+
     // A test is required so as not to throw an error
     // This is a lot cleaner than using PHPUnit's mocks to spy
     public function test() {

tests/Stringy/StaticStringyTest.php

@@ -307,4 +307,14 @@ class StaticStringyTestCase extends CommonTest
         $result = S::length($str, $encoding);
         $this->assertEquals($expected, $result);
     }
+
+    /**
+     * @dataProvider stringsForSubstr
+     */
+    public function testSubstr($expected, $str, $start, $length = null,
+                               $encoding = null)
+    {
+        $result = S::substr($str, $start, $length, $encoding);
+        $this->assertEquals($expected, $result);
+    }
 }

tests/Stringy/StringyTest.php

@@ -299,4 +299,14 @@ class StringyTestCase extends CommonTest
         $result = S::create($str, $encoding)->length();
         $this->assertEquals($expected, $result);
     }
+
+    /**
+     * @dataProvider stringsForSubstr
+     */
+    public function testSubstr($expected, $str, $start, $length = null,
+                               $encoding = null)
+    {
+        $result = S::create($str, $encoding)->substr($start, $length);
+        $this->assertEquals($expected, $result);
+    }
 }