From f3ac2bf1f3f9aad34f831cd6d14a53fd342b737a Mon Sep 17 00:00:00 2001
From: "Daniel St. Jules" <danielst.jules@gmail.com>
Date: Sat, 27 Jul 2013 13:57:30 -0400
Subject: [PATCH] Added at()

---
 README.md                           | 16 ++++++++++++++--
 src/Stringy/StaticStringy.php       | 15 ++++++++++++++-
 src/Stringy/Stringy.php             | 13 +++++++++++++
 tests/Stringy/CommonTest.php        | 16 ++++++++++++++++
 tests/Stringy/StaticStringyTest.php |  9 +++++++++
 tests/Stringy/StringyTest.php       |  9 +++++++++
 6 files changed, 75 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index d7701e1..5485a92 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,7 @@ Note: The methods listed below are subject to change until we reach a 1.0.0 rele
     * [longestCommonSubstring](#longestcommonsubstring)
     * [length](#length)
     * [substr](#substr)
+    * [at](#at)
 * [Tests](#tests)
 * [License](#license)
 
@@ -588,6 +589,19 @@ S::create('fòô bàř', 'UTF-8')->substr(2, 3);
 S::substr('fòô bàř', 2, 3, 'UTF-8');  // 'ô b'
 ```
 
+##### at
+
+$stringy->at(int $index)
+
+S::substr(int $index [, string $encoding ])
+
+Gets the character of $str at $index, with indexes starting at 0.
+
+```php
+S::create('fòô bàř', 'UTF-8')->at(6);
+S::at('fòô bàř', 6, 'UTF-8');  // 'ř'
+```
+
 ## TODO
 
 **count** => substr_count
@@ -612,8 +626,6 @@ S::substr('fòô bàř', 2, 3, 'UTF-8');  // 'ô b'
 
 **pluralize** ($count, $singular, $plural = null)
 
-**at** $position
-
 **first**
 
 **last**
diff --git a/src/Stringy/StaticStringy.php b/src/Stringy/StaticStringy.php
index bbc83a0..48fa972 100644
--- a/src/Stringy/StaticStringy.php
+++ b/src/Stringy/StaticStringy.php
@@ -465,10 +465,23 @@ class StaticStringy
      * @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
+     * @param   string  $encoding  The character encoding
      * @return  string  The substring of $str
      */
     public static function substr($str, $start, $length = null, $encoding = null)
     {
-        return Stringy::create($str, $encoding)->substr($start, $length);
+        return Stringy::create($str, $encoding)->substr($start, $length)->str;
+    }
+
+    /**
+     * Gets the character of $str at $index, with indexes starting at 0.
+     *
+     * @param   int      $index  Position of the character
+     * @param   string   $encoding  The character encoding
+     * @return  string   The character at $index
+     */
+    public static function at($str, $index, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->at($index)->str;
     }
 }
diff --git a/src/Stringy/Stringy.php b/src/Stringy/Stringy.php
index b230a3c..cc9248a 100644
--- a/src/Stringy/Stringy.php
+++ b/src/Stringy/Stringy.php
@@ -753,4 +753,17 @@ class Stringy
 
         return $this;
     }
+
+    /**
+     * Gets the character of $str at $index, with indexes starting at 0.
+     *
+     * @param   int  $index  Position of the character
+     * @return  Stringy  Object with its $str being the selected character
+     */
+    public function at($index)
+    {
+        $this->substr($index, 1);
+
+        return $this;
+    }
 }
diff --git a/tests/Stringy/CommonTest.php b/tests/Stringy/CommonTest.php
index 430245a..4cb5507 100644
--- a/tests/Stringy/CommonTest.php
+++ b/tests/Stringy/CommonTest.php
@@ -546,6 +546,22 @@ class CommonTest extends PHPUnit_Framework_TestCase
         return $testData;
     }
 
+    public function stringsForAt()
+    {
+        $testData = array(
+            array('f', 'foo bar', 0),
+            array('o', 'foo bar', 1),
+            array('r', 'foo bar', 6),
+            array('', 'foo bar', 7),
+            array('f', 'fòô bàř', 0, 'UTF-8'),
+            array('ò', 'fòô bàř', 1, 'UTF-8'),
+            array('ř', 'fòô bàř', 6, 'UTF-8'),
+            array('', 'fòô bàř', 7, '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() {
diff --git a/tests/Stringy/StaticStringyTest.php b/tests/Stringy/StaticStringyTest.php
index 548578f..1934a60 100644
--- a/tests/Stringy/StaticStringyTest.php
+++ b/tests/Stringy/StaticStringyTest.php
@@ -317,4 +317,13 @@ class StaticStringyTestCase extends CommonTest
         $result = S::substr($str, $start, $length, $encoding);
         $this->assertEquals($expected, $result);
     }
+
+    /**
+     * @dataProvider stringsForAt
+     */
+    public function testAt($expected, $str, $index, $encoding = null)
+    {
+        $result = S::at($str, $index, $encoding);
+        $this->assertEquals($expected, $result);
+    }
 }
diff --git a/tests/Stringy/StringyTest.php b/tests/Stringy/StringyTest.php
index 76ccf46..050d0f7 100644
--- a/tests/Stringy/StringyTest.php
+++ b/tests/Stringy/StringyTest.php
@@ -309,4 +309,13 @@ class StringyTestCase extends CommonTest
         $result = S::create($str, $encoding)->substr($start, $length);
         $this->assertEquals($expected, $result);
     }
+
+    /**
+     * @dataProvider stringsForAt
+     */
+    public function testAt($expected, $str, $index, $encoding = null)
+    {
+        $result = S::create($str, $encoding)->at($index);
+        $this->assertEquals($expected, $result);
+    }
 }