Implemented IteratorAggregate, added chars()

README.md

@@ -1,14 +1,18 @@
 ![Stringy](http://danielstjules.com/stringy/logo.png)
 
-A PHP library with a variety of string manipulation functions with multibyte support. Offers both OO method chaining and a procedural-style static wrapper. Compatible with PHP 5.3+. Inspired by underscore.string.js.
+A PHP library with a variety of string manipulation functions with multibyte
+support. Offers both OO method chaining and a procedural-style static wrapper.
+Compatible with PHP 5.3+. Inspired by underscore.string.js.
 
 [![Build Status](https://travis-ci.org/danielstjules/Stringy.png)](https://travis-ci.org/danielstjules/Stringy)
 
 * [Requiring/Loading](#requiringloading)
 * [OO and Procedural](#oo-and-procedural)
+* [Implemented Interfaces](#implemented-interfaces)
 * [Methods](#methods)
     * [at](#at)
     * [camelize](#camelize)
+    * [chars](#chars)
     * [collapseWhitespace](#collapsewhitespace)
     * [contains](#contains)
     * [count](#count)
@@ -120,6 +124,26 @@ $string = S::collapseWhitespace('Fòô     Bàř', 'UTF-8');
 echo S::swapCase($string, 'UTF-8');  // 'fÒÔ bÀŘ'
 ```
 
+## Implemented Interfaces
+
+`Stringy\Stringy` implements the IteratorAggregate interface. This allows you
+to use `foreach` with an instance of the class:
+
+``` php
+$stringy = S::create('Fòô Bàř', 'UTF-8');
+
+foreach ($stringy as $char) {
+    echo $char;
+}
+// 'Fòô Bàř'
+
+$array = array();
+foreach ($stringy as $pos => $char) {
+    $array[$pos] = $char;
+}
+// array('F', 'ò', 'ô', ' ', 'B', 'à', 'ř')
+```
+
 ## Methods
 
 In the list below, any static method other than S::create refers to a method in
@@ -157,6 +181,19 @@ S::create('Camel-Case')->camelize();
 S::camelize('Camel-Case');  // 'camelCase'
 ```
 
+#### chars
+
+$stringy->chars();
+
+S::chars(string $str [, string $encoding ])
+
+Returns an array consisting of the characters in the string.
+
+```php
+S::create('Fòô Bàř', 'UTF-8')->chars();
+S::chars('Fòô Bàř', 'UTF-8');  // array(F', 'ò', 'ô', ' ', 'B', 'à', 'ř')
+```
+
 #### collapseWhitespace
 
 $stringy->collapseWhitespace()

src/Stringy/StaticStringy.php

@@ -4,6 +4,18 @@ namespace Stringy;
 
 class StaticStringy
 {
+    /**
+     * Returns an array consisting of the characters in the string.
+     *
+     * @param   string  $str       String for which to return the chars
+     * @param   string  $encoding  The character encoding
+     * @return  array   An array of string chars
+     */
+    public static function chars($str, $encoding = null)
+    {
+        return Stringy::create($str, $encoding)->chars();
+    }
+
     /**
      * Converts the first character of the supplied string to upper case.
      *

src/Stringy/Stringy.php

@@ -2,7 +2,7 @@
 
 namespace Stringy;
 
-class Stringy
+class Stringy implements \IteratorAggregate
 {
     private $str;
 
@@ -64,6 +64,34 @@ class Stringy
         return $this->str;
     }
 
+    /**
+     * Returns a new ArrayIterator, thus implementing the IteratorAggregate
+     * interface. The ArrayIterator's constructor is passed an array of chars
+     * in the multibyte string. This allows the use of foreach with instances
+     * of Stringy\Stringy.
+     *
+     * @return \ArrayIterator An iterator for the characters in the string
+     */
+    public function getIterator()
+    {
+        return new \ArrayIterator($this->chars());
+    }
+
+    /**
+     * Returns an array consisting of the characters in the string.
+     *
+     * @return array An array of string chars
+     */
+    public function chars()
+    {
+        $chars = array();
+        for ($i = 0; $i < $this->length(); $i++) {
+            $chars[] = $this->at($i)->str;
+        }
+
+        return $chars;
+    }
+
     /**
      * Converts the first character of the supplied string to upper case.
      *

tests/Stringy/CommonTest.php

@@ -2,6 +2,15 @@
 
 abstract class CommonTest extends PHPUnit_Framework_TestCase
 {
+    public function charsProvider()
+    {
+        return array(
+            array(array(), ''),
+            array(array('T', 'e', 's', 't'), 'Test'),
+            array(array('F', 'ò', 'ô', ' ', 'B', 'à', 'ř'), 'Fòô Bàř', 'UTF-8')
+        );
+    }
+
     public function upperCaseFirstProvider()
     {
         return array(

tests/Stringy/StaticStringyTest.php

@@ -7,6 +7,19 @@ use Stringy\StaticStringy as S;
 
 class StaticStringyTestCase extends CommonTest
 {
+    /**
+     * @dataProvider charsProvider()
+     */
+    public function testChars($expected, $str, $encoding = null)
+    {
+        $result = S::chars($str, $encoding);
+        $this->assertInternalType('array', $result);
+        foreach ($result as $char) {
+            $this->assertInternalType('string', $char);
+        }
+        $this->assertEquals($expected, $result);
+    }
+
     /**
      * @dataProvider upperCaseFirstProvider()
      */

tests/Stringy/StringyTest.php

@@ -70,6 +70,37 @@ class StringyTestCase extends CommonTest
         $this->assertEquals('FÒÔ bÀŘ', $result);
     }
 
+    public function testGetIterator()
+    {
+        $stringy = S::create('Fòô Bàř', 'UTF-8');
+
+        $valResult = [];
+        foreach ($stringy as $char) {
+            $valResult[] = $char;
+        }
+
+        $keyValResult = [];
+        foreach ($stringy as $pos => $char) {
+            $keyValResult[$pos] = $char;
+        }
+
+        $this->assertEquals(array('F', 'ò', 'ô', ' ', 'B', 'à', 'ř'), $valResult);
+        $this->assertEquals(array('F', 'ò', 'ô', ' ', 'B', 'à', 'ř'), $keyValResult);
+    }
+
+    /**
+     * @dataProvider charsProvider()
+     */
+    public function testChars($expected, $str, $encoding = null)
+    {
+        $result = S::create($str, $encoding)->chars();
+        $this->assertInternalType('array', $result);
+        foreach ($result as $char) {
+            $this->assertInternalType('string', $char);
+        }
+        $this->assertEquals($expected, $result);
+    }
+
     /**
      * @dataProvider upperCaseFirstProvider()
      */