Merge pull request #68 from vlakoff/toAscii

[Proposal] Add $replaceUnsupported and $fallback parameters to toAscii()

README.md

@@ -881,10 +881,11 @@ S::titleize('i like to watch DVDs at home', $ignore, 'UTF-8');
 
 $stringy->toAscii()
 
-S::toAscii(string $str)
+S::toAscii(string $str [, boolean $removeUnsupported = true])
 
 Returns an ASCII version of the string. A set of non-ASCII characters are
-replaced with their closest ASCII counterparts, and the rest are removed.
+replaced with their closest ASCII counterparts, and the rest are removed
+unless instructed otherwise.
 
 ```php
 S::create('fòô bàř')->toAscii();

src/StaticStringy.php

@@ -166,14 +166,16 @@ class StaticStringy
 
     /**
      * Returns an ASCII version of the string. A set of non-ASCII characters are
-     * replaced with their closest ASCII counterparts, and the rest are removed.
+     * replaced with their closest ASCII counterparts, and the rest are removed
+     * unless instructed otherwise.
      *
      * @param  string $str A string with non-ASCII characters
+     * @param  bool   $removeUnsupported Whether to remove or not the unsupported characters
      * @return string A string containing only ASCII characters
      */
-    public static function toAscii($str)
+    public static function toAscii($str, $removeUnsupported = true)
     {
-        return (string) Stringy::create($str)->toAscii();
+        return (string) Stringy::create($str)->toAscii($removeUnsupported);
     }
 
     /**

src/Stringy.php

@@ -419,11 +419,13 @@ class Stringy implements \Countable, \IteratorAggregate, \ArrayAccess
 
     /**
      * Returns an ASCII version of the string. A set of non-ASCII characters are
-     * replaced with their closest ASCII counterparts, and the rest are removed.
+     * replaced with their closest ASCII counterparts, and the rest are removed
+     * unless instructed otherwise.
      *
+     * @param  bool    $removeUnsupported Whether to remove or not the unsupported characters
      * @return Stringy Object whose $str contains only ASCII characters
      */
-    public function toAscii()
+    public function toAscii($removeUnsupported = true)
     {
         $str = $this->str;
 
@@ -431,7 +433,9 @@ class Stringy implements \Countable, \IteratorAggregate, \ArrayAccess
             $str = str_replace($value, $key, $str);
         }
 
+        if ($removeUnsupported) {
             $str = preg_replace('/[^\x20-\x7E]/u', '', $str);
+        }
 
         return static::create($str, $this->encoding);
     }

tests/CommonTest.php

@@ -203,6 +203,8 @@ abstract class CommonTest extends PHPUnit_Framework_TestCase
             array(' ', ' '), // narrow no-break space (U+202F)
             array(' ', ' '), // medium mathematical space (U+205F)
             array(' ', '　'), // ideographic space (U+3000)
+            array('', '𐍉'), // some uncommon, unsupported character (U+10349)
+            array('𐍉', '𐍉', false),
         );
     }
 

tests/StaticStringyTest.php

@@ -133,9 +133,9 @@ class StaticStringyTestCase extends CommonTest
     /**
      * @dataProvider toAsciiProvider()
      */
-    public function testToAscii($expected, $str)
+    public function testToAscii($expected, $str, $removeUnsupported = true)
     {
-        $result = S::toAscii($str);
+        $result = S::toAscii($str, $removeUnsupported);
         $this->assertInternalType('string', $result);
         $this->assertEquals($expected, $result);
     }

tests/StringyTest.php

@@ -300,10 +300,10 @@ class StringyTestCase extends CommonTest
     /**
      * @dataProvider toAsciiProvider()
      */
-    public function testToAscii($expected, $str)
+    public function testToAscii($expected, $str, $removeUnsupported = true)
     {
         $stringy = S::create($str);
-        $result = $stringy->toAscii();
+        $result = $stringy->toAscii($removeUnsupported);
         $this->assertStringy($result);
         $this->assertEquals($expected, $result);
         $this->assertEquals($str, $stringy);