Add first() and last()

README.md

@@ -41,6 +41,8 @@ Note: The methods listed below are subject to change until we reach a 1.0.0 rele
     * [length](#length)
     * [substr](#substr)
     * [at](#at)
+    * [first](#first)
+    * [last](#last)
 * [Tests](#tests)
 * [License](#license)
 
@@ -602,6 +604,32 @@ S::create('fòô bàř', 'UTF-8')->at(6);
 S::at('fòô bàř', 6, 'UTF-8');  // 'ř'
 ```
 
+##### first
+
+$stringy->first(int $n)
+
+S::first(int $n [, string $encoding ])
+
+Gets the first $n characters of $str.
+
+```php
+S::create('fòô bàř', 'UTF-8')->first(3);
+S::first('fòô bàř', 3, 'UTF-8');  // 'fòô'
+```
+
+##### last
+
+$stringy->last(int $n)
+
+S::last(int $n [, string $encoding ])
+
+Gets the last $n characters of $str.
+
+```php
+S::create('fòô bàř', 'UTF-8')->last(3);
+S::last('fòô bàř', 3, 'UTF-8');  // 'bàř'
+```
+
 ## TODO
 
 **count** => substr_count
@@ -626,14 +654,6 @@ S::at('fòô bàř', 6, 'UTF-8');  // 'ř'
 
 **pluralize** ($count, $singular, $plural = null)
 
-**first**
-
-**last**
-
-**from**
-
-**to**
-
 **toBoolean**
 
 **ensureLeft**

src/Stringy/StaticStringy.php

@@ -484,4 +484,28 @@ class StaticStringy
     {
         return Stringy::create($str, $encoding)->at($index)->str;
     }
+
+    /**
+     * Gets the first $n characters of $str.
+     *
+     * @param   int      $n         Number of chars to retrieve from the start
+     * @param   string   $encoding  The character encoding
+     * @return  string   The first $n characters
+     */
+    public static function first($str, $n, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->first($n)->str;
+    }
+
+    /**
+     * Gets the last $n characters of $str.
+     *
+     * @param   int      $n         Number of chars to retrieve from the end
+     * @param   string   $encoding  The character encoding
+     * @return  string   The last $n characters
+     */
+    public static function last($str, $n, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->last($n)->str;
+    }
 }

src/Stringy/Stringy.php

@@ -766,4 +766,38 @@ class Stringy
 
         return $this;
     }
+
+    /**
+     * Gets the first $n characters of $str.
+     *
+     * @param   int  $n  Number of characters to retrieve from the start
+     * @return  Stringy  Object with its $str being the first $n chars
+     */
+    public function first($n)
+    {
+        if ($n < 0) {
+            $this->str = '';
+        } else {
+            $this->substr(0, $n);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Gets the last $n characters of $str.
+     *
+     * @param   int  $n  Number of characters to retrieve from the end
+     * @return  Stringy  Object with its $str being the last $n chars
+     */
+    public function last($n)
+    {
+        if ($n <= 0) {
+            $this->str = '';
+        } else {
+            $this->substr(-$n);
+        }
+
+        return $this;
+    }
 }

tests/Stringy/CommonTest.php

@@ -562,6 +562,46 @@ class CommonTest extends PHPUnit_Framework_TestCase
         return $testData;
     }
 
+    public function stringsForFirst()
+    {
+        $testData = array(
+            array('', 'foo bar', -5),
+            array('', 'foo bar', 0),
+            array('f', 'foo bar', 1),
+            array('foo', 'foo bar', 3),
+            array('foo bar', 'foo bar', 7),
+            array('foo bar', 'foo bar', 8),
+            array('', 'fòô bàř', -5, 'UTF-8'),
+            array('', 'fòô bàř', 0, 'UTF-8'),
+            array('f', 'fòô bàř', 1, 'UTF-8'),
+            array('fòô', 'fòô bàř', 3, 'UTF-8'),
+            array('fòô bàř', 'fòô bàř', 7, 'UTF-8'),
+            array('fòô bàř', 'fòô bàř', 8, 'UTF-8'),
+        );
+
+        return $testData;
+    }
+
+    public function stringsForLast()
+    {
+        $testData = array(
+            array('', 'foo bar', -5),
+            array('', 'foo bar', 0),
+            array('r', 'foo bar', 1),
+            array('bar', 'foo bar', 3),
+            array('foo bar', 'foo bar', 7),
+            array('foo bar', 'foo bar', 8),
+            array('', 'fòô bàř', -5, 'UTF-8'),
+            array('', 'fòô bàř', 0, 'UTF-8'),
+            array('ř', 'fòô bàř', 1, 'UTF-8'),
+            array('bàř', 'fòô bàř', 3, 'UTF-8'),
+            array('fòô bàř', 'fòô bàř', 7, 'UTF-8'),
+            array('fòô bàř', 'fòô bàř', 8, '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

@@ -326,4 +326,22 @@ class StaticStringyTestCase extends CommonTest
         $result = S::at($str, $index, $encoding);
         $this->assertEquals($expected, $result);
     }
+
+    /**
+     * @dataProvider stringsForFirst
+     */
+    public function testFirst($expected, $str, $n, $encoding = null)
+    {
+        $result = S::first($str, $n, $encoding);
+        $this->assertEquals($expected, $result);
+    }
+
+    /**
+     * @dataProvider stringsForLast
+     */
+    public function testLast($expected, $str, $n, $encoding = null)
+    {
+        $result = S::last($str, $n, $encoding);
+        $this->assertEquals($expected, $result);
+    }
 }

tests/Stringy/StringyTest.php

@@ -318,4 +318,22 @@ class StringyTestCase extends CommonTest
         $result = S::create($str, $encoding)->at($index);
         $this->assertEquals($expected, $result);
     }
+
+    /**
+     * @dataProvider stringsForFirst
+     */
+    public function testFirst($expected, $str, $n, $encoding = null)
+    {
+        $result = S::create($str, $encoding)->first($n);
+        $this->assertEquals($expected, $result);
+    }
+
+    /**
+     * @dataProvider stringsForLast
+     */
+    public function testLast($expected, $str, $n, $encoding = null)
+    {
+        $result = S::create($str, $encoding)->last($n);
+        $this->assertEquals($expected, $result);
+    }
 }