Add trimLeft, trimRight, support unicode whitespace

README.md

@@ -74,6 +74,8 @@ PHP 5.3+ and HHVM. Inspired by underscore.string.js.
     * [toTitleCase](#totitlecase)
     * [toUpperCase](#touppercase)
     * [trim](#trim)
+    * [trimLeft](#trimLeft)
+    * [trimRight](#trimRight)
     * [truncate](#truncate)
     * [underscored](#underscored)
     * [upperCamelize](#uppercamelize)
@@ -1069,15 +1071,47 @@ S::toUpperCase('fòô bàř', 'UTF-8');  // 'FÒÔ BÀŘ'
 
 #### trim
 
-$stringy->trim()
+$stringy->trim([, string $chars])
 
-S::trim(string $str)
+S::trim(string $str [, string $chars [, string $encoding ]])
 
-Returns the trimmed string.
+Returns a string with whitespace removed from the start and end of the
+string. Supports the removal of unicode whitespace. Accepts an optional
+string of characters to strip instead of the defaults.
 
 ```php
-S::create('fòô bàř', 'UTF-8')->trim();
+S::create('  fòô bàř  ', 'UTF-8')->trim();
-S::trim(' fòô bàř ');  // 'fòô bàř'
+S::trim('  fòô bàř  ');  // 'fòô bàř'
+```
+
+#### trimLeft
+
+$stringy->trimLeft([, string $chars])
+
+S::trimLeft(string $str [, string $chars [, string $encoding ]])
+
+Returns a string with whitespace removed from the start of the string.
+Supports the removal of unicode whitespace. Accepts an optional
+string of characters to strip instead of the defaults.
+
+```php
+S::create('  fòô bàř  ', 'UTF-8')->trimLeft();
+S::trimLeft('  fòô bàř  ');  // 'fòô bàř  '
+```
+
+#### trimRight
+
+$stringy->trimRight([, string $chars])
+
+S::trimRight(string $str [, string $chars [, string $encoding ]])
+
+Returns a string with whitespace removed from the end of the string.
+Supports the removal of unicode whitespace. Accepts an optional
+string of characters to strip instead of the defaults.
+
+```php
+S::create('  fòô bàř  ', 'UTF-8')->trimRight();
+S::trimRight('  fòô bàř  ');  // '  fòô bàř'
 ```
 
 #### truncate

src/StaticStringy.php

@@ -561,14 +561,48 @@ class StaticStringy
     }
 
     /**
-     * Returns the trimmed string. An alias for PHP's trim() function.
+     * Returns a string with whitespace removed from the start and end of the
+     * string. Supports the removal of unicode whitespace. Accepts an optional
+     * string of characters to strip instead of the defaults.
      *
-     * @param  string $str String to trim
+     * @param  string $str      String to trim
+     * @param  string $chars    Optional string of characters to strip
+     * @param  string $encoding The character encoding
      * @return string Trimmed $str
      */
-    public static function trim($str)
+    public static function trim($str, $chars = null, $encoding = null)
     {
-        return trim($str);
+        return (string) Stringy::create($str, $encoding)->trim($chars);
+    }
+
+    /**
+     * Returns a string with whitespace removed from the start of the string.
+     * Supports the removal of unicode whitespace. Accepts an optional
+     * string of characters to strip instead of the defaults.
+     *
+     * @param  string $str      String to trim
+     * @param  string $chars    Optional string of characters to strip
+     * @param  string $encoding The character encoding
+     * @return string Trimmed $str
+     */
+    public static function trimLeft($str, $chars = null, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->trimLeft($chars);
+    }
+
+    /**
+     * Returns a string with whitespace removed from the end of the string.
+     * Supports the removal of unicode whitespace. Accepts an optional
+     * string of characters to strip instead of the defaults.
+     *
+     * @param  string $str      String to trim
+     * @param  string $chars    Optional string of characters to strip
+     * @param  string $encoding The character encoding
+     * @return string Trimmed $str
+     */
+    public static function trimRight($str, $chars = null, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->trimRight($chars);
     }
 
     /**

src/Stringy.php

@@ -4,13 +4,6 @@ namespace Stringy;
 
 class Stringy implements \Countable, \IteratorAggregate, \ArrayAccess
 {
-
-    const TRIM_BOTH = 'trim';
-
-    const TRIM_LEFT = 'ltrim';
-
-    const TRIM_RIGHT = 'rtrim';
-
     /**
      * An instance's string.
      *
@@ -1064,28 +1057,48 @@ class Stringy implements \Countable, \IteratorAggregate, \ArrayAccess
     }
 
     /**
-     * Returns the trimmed string.
+     * Returns a string with whitespace removed from the start and end of the
+     * string. Supports the removal of unicode whitespace. Accepts an optional
+     * string of characters to strip instead of the defaults.
      *
-     * @param  string  $charList Characters to be removed
+     * @param  string  $chars Optional string of characters to strip
-     * @param  int     $type     One of TRIM_BOTH, TRIM_LEFT or TRIM_RIGHT
      * @return Stringy Object with a trimmed $str
-     * @throws \InvalidArgumentException
      */
-    public function trim($charList = " \t\n\r\0\x0B", $type = self::TRIM_BOTH)
+    public function trim($chars = null)
     {
-        if (!is_string($charList)) {
+        $chars = ($chars) ? preg_quote($chars) : '[:space:]';
-            throw new \InvalidArgumentException(
-                'Charset list must be a string'
-            );
-        }
 
-        $validTypes = array(self::TRIM_BOTH, self::TRIM_LEFT, self::TRIM_RIGHT);
+        return $this->regexReplace("^[$chars]+|[$chars]+\$", '');
-        if (!in_array($type, $validTypes)) {
+    }
-            throw new \InvalidArgumentException('Type of trim function must ' .
-                'be trim (default), rtrim or ltrim, just as native php.');
-        }
 
-        return static::create($type($this->str, $charList), $this->encoding);
+    /**
+     * Returns a string with whitespace removed from the start of the string.
+     * Supports the removal of unicode whitespace. Accepts an optional
+     * string of characters to strip instead of the defaults.
+     *
+     * @param  string  $chars Optional string of characters to strip
+     * @return Stringy Object with a trimmed $str
+     */
+    public function trimLeft($chars = null)
+    {
+        $chars = ($chars) ? preg_quote($chars) : '[:space:]';
+
+        return $this->regexReplace("^[$chars]+", '');
+    }
+
+    /**
+     * Returns a string with whitespace removed from the end of the string.
+     * Supports the removal of unicode whitespace. Accepts an optional
+     * string of characters to strip instead of the defaults.
+     *
+     * @param  string  $chars Optional string of characters to strip
+     * @return Stringy Object with a trimmed $str
+     */
+    public function trimRight($chars = null)
+    {
+        $chars = ($chars) ? preg_quote($chars) : '[:space:]';
+
+        return $this->regexReplace("[$chars]+\$", '');
     }
 
     /**

tests/CommonTest.php

@@ -630,7 +630,7 @@ abstract class CommonTest extends PHPUnit_Framework_TestCase
         );
     }
 
-    public function trimProviderWithoutParams()
+    public function trimProvider()
     {
         return array(
             array('foo   bar', '  foo   bar  '),
@@ -640,24 +640,49 @@ abstract class CommonTest extends PHPUnit_Framework_TestCase
             array('fòô   bàř', '  fòô   bàř  '),
             array('fòô bàř', ' fòô bàř'),
             array('fòô bàř', 'fòô bàř '),
-            array('fòô bàř', "\n\t fòô bàř \n\t")
+            array(' foo bar ', "\n\t foo bar \n\t", "\n\t"),
+            array('fòô bàř', "\n\t fòô bàř \n\t", null, 'UTF-8'),
+            array('fòô', ' fòô ', null, 'UTF-8'), // narrow no-break space (U+202F)
+            array('fòô', '  fòô  ', null, 'UTF-8'), // medium mathematical space (U+205F)
+            array('fòô', '           fòô', null, 'UTF-8') // spaces U+2000 to U+200A
         );
     }
 
-    public function trimProviderWithParams()
+    public function trimLeftProvider()
     {
         return array(
-            array('foo   bar', '  foo   bar  ', " \t\n\r\0\x0B", 'trim'),
+            array('foo   bar  ', '  foo   bar  '),
-            array('foo bar', ' foo bar', " \t\n\r\0\x0B", 'trim'),
+            array('foo bar', ' foo bar'),
-            array('foo bar', 'foo bar ', " \t\n\r\0\x0B", 'trim'),
+            array('foo bar ', 'foo bar '),
-            array('foo bar', "\n\t foo bar \n\t", " \t\n\r\0\x0B", 'trim'),
+            array("foo bar \n\t", "\n\t foo bar \n\t"),
-            array('fòô   bàř', '  fòô   bàř  ', " \t\n\r\0\x0B", 'trim'),
+            array('fòô   bàř  ', '  fòô   bàř  '),
-            array('fòô bàř', ' fòô bàř', " \t\n\r\0\x0B", 'trim'),
+            array('fòô bàř', ' fòô bàř'),
-            array('fòô bàř', 'fòô bàř ', " \t\n\r\0\x0B", 'trim'),
+            array('fòô bàř ', 'fòô bàř '),
-            array('fòô bàř', "\n\t fòô bàř \n\t", " \t\n\r\0\x0B", 'trim'),
+            array('foo bar', '--foo bar', '-'),
-            array('  foo   bar', '  foo   bar  ', " \t\n\r\0\x0B", 'rtrim'),
+            array('fòô bàř', 'òòfòô bàř', 'ò', 'UTF-8'),
-            array('foo   bar  ', '  foo   bar  ', " \t\n\r\0\x0B", 'ltrim'),
+            array("fòô bàř \n\t", "\n\t fòô bàř \n\t", null, 'UTF-8'),
-            array('  foo   bar  ', '  foo   bar  ', "\t\n\r\0\x0B", 'ltrim')
+            array('fòô ', ' fòô ', null, 'UTF-8'), // narrow no-break space (U+202F)
+            array('fòô  ', '  fòô  ', null, 'UTF-8'), // medium mathematical space (U+205F)
+            array('fòô', '           fòô', null, 'UTF-8') // spaces U+2000 to U+200A
+        );
+    }
+
+    public function trimRightProvider()
+    {
+        return array(
+            array('  foo   bar', '  foo   bar  '),
+            array('foo bar', 'foo bar '),
+            array(' foo bar', ' foo bar'),
+            array("\n\t foo bar", "\n\t foo bar \n\t"),
+            array('  fòô   bàř', '  fòô   bàř  '),
+            array('fòô bàř', 'fòô bàř '),
+            array(' fòô bàř', ' fòô bàř'),
+            array('foo bar', 'foo bar--', '-'),
+            array('fòô bàř', 'fòô bàřòò', 'ò', 'UTF-8'),
+            array("\n\t fòô bàř", "\n\t fòô bàř \n\t", null, 'UTF-8'),
+            array(' fòô', ' fòô ', null, 'UTF-8'), // narrow no-break space (U+202F)
+            array('  fòô', '  fòô  ', null, 'UTF-8'), // medium mathematical space (U+205F)
+            array('fòô', 'fòô           ', null, 'UTF-8') // spaces U+2000 to U+200A
         );
     }
 

tests/StaticStringyTest.php

@@ -400,11 +400,33 @@ class StaticStringyTestCase extends CommonTest
     }
 
     /**
-     * @dataProvider trimProviderWithoutParams()
+     * @dataProvider trimProvider()
      */
-    public function testTrim($expected, $str)
+    public function testTrim($expected, $str, $chars = null, $encoding = null)
     {
-        $result = S::trim($str);
+        $result = S::trim($str, $chars, $encoding);
+        $this->assertInternalType('string', $result);
+        $this->assertEquals($expected, $result);
+    }
+
+    /**
+     * @dataProvider trimLeftProvider()
+     */
+    public function testTrimLeft($expected, $str, $chars = null,
+                                 $encoding = null)
+    {
+        $result = S::trimLeft($str, $chars, $encoding);
+        $this->assertInternalType('string', $result);
+        $this->assertEquals($expected, $result);
+    }
+
+    /**
+     * @dataProvider trimRightProvider()
+     */
+    public function testTrimRight($expected, $str, $chars = null,
+                                  $encoding = null)
+    {
+        $result = S::trimRight($str, $chars, $encoding);
         $this->assertInternalType('string', $result);
         $this->assertEquals($expected, $result);
     }

tests/StringyTest.php

@@ -624,49 +624,41 @@ class StringyTestCase extends CommonTest
     }
 
     /**
-     * @dataProvider trimProviderWithoutParams()
+     * @dataProvider trimProvider()
      */
-    public function testTrimWithoutParams($expected, $str)
+    public function testTrim($expected, $str, $chars = null, $encoding = null)
     {
-        $stringy = S::create($str);
+        $stringy = S::create($str, $encoding);
-        $result = $stringy->trim();
+        $result = $stringy->trim($chars);
         $this->assertStringy($result);
         $this->assertEquals($expected, $result);
         $this->assertEquals($str, $stringy);
     }
 
     /**
-     * @dataProvider trimProviderWithParams()
+     * @dataProvider trimLeftProvider()
      */
-    public function testTrimWithParams($expected, $str, $charList, $type)
+    public function testTrimLeft($expected, $str, $chars = null,
+                                 $encoding = null)
     {
-        $stringy = S::create($str);
+        $stringy = S::create($str, $encoding);
-        $result = $stringy->trim($charList, $type);
+        $result = $stringy->trimLeft($chars);
         $this->assertStringy($result);
         $this->assertEquals($expected, $result);
         $this->assertEquals($str, $stringy);
     }
 
     /**
-     * @expectedException InvalidArgumentException
+     * @dataProvider trimRightProvider()
      */
-    public function testTrimWithInvalidCharset()
+    public function testTrimRight($expected, $str, $chars = null,
+                                  $encoding = null)
     {
-        $stringy = S::create('test');
+        $stringy = S::create($str, $encoding);
-        $stringy->trim(array('test1', 'test2'), 'trim');
+        $result = $stringy->trimRight($chars);
-        $this->fail('Expecting exception when the first argument passed is not a string');
+        $this->assertStringy($result);
-    }
+        $this->assertEquals($expected, $result);
-
+        $this->assertEquals($str, $stringy);
-    /**
-     * @expectedException InvalidArgumentException
-     */
-    public function testTrimWithInvalidType()
-    {
-        $stringy = S::create('test');
-        $stringy->trim(' test ', 'aa');
-        $stringy->trim('btest ', 'Trim');
-        $stringy->trim(' btest', 'RTrim');
-        $this->fail('Expecting exception when the first argument passed is not a string');
     }
 
     /**