Add public delimit() function

README.md

@@ -21,6 +21,7 @@ PHP 5.3+ and HHVM. Inspired by underscore.string.js.
     * [countSubstr](#countsubstr)
     * [create](#create)
     * [dasherize](#dasherize)
+    * [delimit](#delimit)
     * [endsWith](#endswith)
     * [ensureLeft](#ensureleft)
     * [ensureRight](#ensureright)
@@ -347,6 +348,22 @@ S::create('TestDCase')->dasherize();
 S::dasherize('TestDCase');  // 'test-d-case'
 ```
 
+#### delimit
+
+$stringy->delimit($delimiter);
+
+S::delimit(string $str [, string $delimiter, string $encoding ])
+
+Returns a lowercase and trimmed string separated by the given delimiter.
+Delimiters are inserted before uppercase characters (with the exception
+of the first character of the string), and in place of spaces, dashes,
+and underscores. Alpha delimiters are not converted to lowercase.
+
+```php
+S::create('TestDCase')->delimit('>>');
+S::delimit('TestCase', '>>');  // 'test>>case'
+```
+
 #### endsWith
 
 $stringy->endsWith(string $substring [, boolean $caseSensitive = true ])

src/StaticStringy.php

@@ -97,6 +97,22 @@ class StaticStringy
         return (string) Stringy::create($str, $encoding)->underscored();
     }
 
+    /**
+     * Returns a lowercase and trimmed string separated by the given delimiter.
+     * Delimiters are inserted before uppercase characters (with the exception
+     * of the first character of the string), and in place of spaces, dashes,
+     * and underscores. Alpha delimiters are not converted to lowercase.
+     *
+     * @param  string  $str       String to convert
+     * @param  string  $delimiter Sequence used to separate parts of the string
+     * @param  string  $encoding  The character encoding
+     * @return string  String with delimiter
+     */
+    public static function delimit($str, $delimiter, $encoding = null)
+    {
+        return (string) Stringy::create($str, $encoding)->delimit($delimiter);
+    }
+
     /**
      * Returns a case swapped version of the string.
      *

src/Stringy.php

@@ -284,7 +284,7 @@ class Stringy implements \Countable, \IteratorAggregate, \ArrayAccess
      */
     public function dasherize()
     {
-        return $this->applyDelimiter('-');
+        return $this->delimit('-');
     }
 
     /**
@@ -297,24 +297,27 @@ class Stringy implements \Countable, \IteratorAggregate, \ArrayAccess
      */
     public function underscored()
     {
-        return $this->applyDelimiter('_');
+        return $this->delimit('_');
     }
 
     /**
      * Returns a lowercase and trimmed string separated by the given delimiter.
+     * Delimiters are inserted before uppercase characters (with the exception
+     * of the first character of the string), and in place of spaces, dashes,
+     * and underscores. Alpha delimiters are not converted to lowercase.
      *
      * @param  string  $delimiter Sequence used to separate parts of the string
      * @return Stringy Object with a delimited $str
      */
-    protected function applyDelimiter($delimiter)
+    public function delimit($delimiter)
     {
         // Save current regex encoding so we can reset it after
         $regexEncoding = mb_regex_encoding();
         mb_regex_encoding($this->encoding);
 
-        $str = mb_ereg_replace('\B([A-Z])', $delimiter .'\1', $this->trim());
-        $str = mb_ereg_replace('[-_\s]+', $delimiter, $str);
+        $str = mb_ereg_replace('\B([A-Z])', '-\1', $this->trim());
         $str = mb_strtolower($str, $this->encoding);
+        $str = mb_ereg_replace('[-_\s]+', $delimiter, $str);
 
         mb_regex_encoding($regexEncoding);
 
@@ -822,7 +825,7 @@ class Stringy implements \Countable, \IteratorAggregate, \ArrayAccess
         $pattern = "/[^a-zA-Z\d\s-_$quotedReplacement]/u";
         $stringy->str = preg_replace($pattern, '', $stringy);
 
-        return $stringy->toLowerCase()->applyDelimiter($replacement)
+        return $stringy->toLowerCase()->delimit($replacement)
                        ->removeLeft($replacement)->removeRight($replacement);
     }
 

tests/CommonTest.php

@@ -145,6 +145,26 @@ abstract class CommonTest extends PHPUnit_Framework_TestCase
         );
     }
 
+    public function delimitProvider()
+    {
+        return array(
+            array('test*case', 'testCase', '*'),
+            array('test&case', 'Test-Case', '&'),
+            array('test#case', 'test case', '#'),
+            array('test**case', 'test -case', '**'),
+            array('~!~test~!~case', '-test - case', '~!~'),
+            array('test*case', 'test_case', '*'),
+            array('test%c%test', '  test c test', '%'),
+            array('test+u+case', 'TestUCase', '+'),
+            array('test=c=c=test', 'TestCCTest', '='),
+            array('string#>with1number', 'string_with1number', '#>'),
+            array('1test2case', '1test2case', '*'),
+            array('test ύα σase', 'test Σase', ' ύα ', 'UTF-8',),
+            array('στανιλαcase', 'Στανιλ case', 'α', 'UTF-8',),
+            array('σashΘcase', 'Σash  Case', 'Θ', 'UTF-8')
+        );
+    }
+
     public function swapCaseProvider()
     {
         return array(

tests/StringyTest.php

@@ -254,6 +254,18 @@ class StringyTestCase extends CommonTest
         $this->assertEquals($str, $stringy);
     }
 
+    /**
+     * @dataProvider delimitProvider()
+     */
+    public function testDelimit($expected, $str, $delimiter, $encoding = null)
+    {
+        $stringy = S::create($str, $encoding);
+        $result = $stringy->delimit($delimiter);
+        $this->assertStringy($result);
+        $this->assertEquals($expected, $result);
+        $this->assertEquals($str, $stringy);
+    }
+
     /**
      * @dataProvider swapCaseProvider()
      */