Add titleize, cleanup comments

README.md

@@ -1,15 +1,41 @@
-Stringy
+# Stringy
-=======
 
 A PHP library with a variety of multibyte string manipulation functions.
 
-Usage
+## Usage
------
+
+#### Requiring/Loading
+
+If you're using Composer to manage dependencies, you can include the following in your composer.json file:
+
+    "require": {
+        "danielstjules/Stringy": "dev-master"
+    }
+
+Then, after running `composer update` or `php composer.phar update`, you can load the class using Composer's autoloading:
+
+```php
+require 'vendor/autoload.php';
+```
+
+Otherwise, you can simply require the file directly:
+
+```php
+require_once 'path/to/Stringy/src/Stringy/Stringy.php';
+```
+
+And in either case, I'd suggest using an alias.
 
 ```php
 use Stringy\Stringy as S;
 ```
 
+#### Methods
+
+*Note: All methods will throw a InvalidArgumentException if $string is not of type
+string. Furthermore, if if $encoding is not given, it defaults to
+mb_internal_encoding().*
+
 **upperCaseFirst**
 
 S::upperCaseFirst($string [, $encoding])
@@ -86,16 +112,27 @@ S::underscored('TestUCase');  // 'test_u_case'
 
 S::swapCase($string [, $encoding])
 
-Returns a case swapped version of a string, with multibyte support.
+Returns a case swapped version of a string.
 
 ```php
 S::swapCase('Ντανιλ', 'UTF-8');  // 'νΤΑΝΙΛ'
 ```
 
-TODO
+**titleize**
-----
 
-**title**
+S::titleize($string [, $encoding [, $ignore]])
+
+Capitalizes the first letter of each word in a string, after trimming.
+Ignores the case of other letters, allowing for the use of acronyms.
+Also accepts an array, $ignore, allowing you to list words not to be
+capitalized.
+
+```php
+$ignore = array('at', 'by', 'for', 'in', 'of', 'on', 'out', 'to', 'the');
+S::titleize('i like to watch DVDs at home', 'UTF-8', $ignore); // 'I Like to Watch DVDs at Home'
+```
+
+## TODO
 
 **sentence**
 
@@ -133,14 +170,12 @@ TODO
 
 **toAnchor**
 
-Tests
+## Tests
------
 
 [![Build Status](https://travis-ci.org/danielstjules/Stringy.png)](https://travis-ci.org/danielstjules/Stringy)
 
 From the project directory, tests can be ran using `phpunit`
 
-License
+## License
--------
 
 Released under the MIT License - see `LICENSE.txt` for details.

src/Stringy/Stringy.php

@@ -35,15 +35,14 @@ class Stringy {
         // Set character encoding for multibyte regex
         mb_regex_encoding($args[1]);
 
-        return forward_static_call(array(__CLASS__, $method), $args[0], $args[1]);
+        return forward_static_call_array(array(__CLASS__, $method), $args);
     }
 
     /**
-     * Converts the first character of the supplied string to upper case, with
+     * Converts the first character of the supplied string to upper case.
-     * support for multibyte strings.
      *
      * @param   string  $string    String to modify
-     * @param   string  $encoding  The character encodng
+     * @param   string  $encoding  The character encoding
      * @return  string  String with the first character being upper case
      */
     private static function upperCaseFirst($string, $encoding) {
@@ -54,11 +53,10 @@ class Stringy {
     }
 
     /**
-     * Converts the first character of the supplied string to lower case, with
+     * Converts the first character of the supplied string to lower case.
-     * support for multibyte strings.
      *
      * @param   string  $string    String to modify
-     * @param   string  $encoding  The character encodng
+     * @param   string  $encoding  The character encoding
      * @return  string  String with the first character being lower case
      */
     private static function lowerCaseFirst($string, $encoding) {
@@ -69,11 +67,12 @@ class Stringy {
     }
 
     /**
-     * Returns a camelCase version of a supplied string, with multibyte support.
+     * Returns a camelCase version of a supplied string. Trims surrounding
-     * Trims surrounding spaces, capitalizes letters following digits, spaces,
+     * spaces, capitalizes letters following digits, spaces, dashes and
-     * dashes and underscores, and removes spaces, dashes, underscores.
+     * underscores, and removes spaces, dashes, underscores.
      *
-     * @param   string  $string  String to convert to camelCase
+     * @param   string  $string    String to convert to camelCase
+     * @param   string  $encoding  The character encoding
      * @return  string  String in camelCase
      */
     private static function camelize($string, $encoding) {
@@ -97,11 +96,12 @@ class Stringy {
     }
 
     /**
-     * Returns an UpperCamelCase version of a supplied string, with multibyte
+     * Returns an UpperCamelCase version of a supplied string. Trims surrounding
-     * support. Trims surrounding spaces, capitalizes letters following digits,
+     * spaces, capitalizes letters following digits, spaces, dashes and
-     * spaces, dashes and underscores, and removes spaces, dashes, underscores.
+     * underscores, and removes spaces, dashes, underscores.
      *
      * @param   string  $string  String to convert to UpperCamelCase
+     * @param   string  $encoding  The character encoding
      * @return  string  String in UpperCamelCase
      */
     private static function upperCamelize($string, $encoding) {
@@ -111,12 +111,12 @@ class Stringy {
     }
 
     /**
-     * Returns a lowercase and trimmed string seperated by dashes, with
+     * Returns a lowercase and trimmed string seperated by dashes. Dashes are
-     * multibyte support. Dashes are inserted before uppercase characters
+     * inserted before uppercase characters (with the exception of the first
-     * (with the exception of the first character of the string), and in place
+     * character of the string), and in place of spaces as well as underscores.
-     * of spaces as well as underscores.
      *
-     * @param   string  $string  String to convert
+     * @param   string  $string    String to convert
+     * @param   string  $encoding  The character encoding
      * @return  string  Dasherized string
      */
     private static function dasherize($string, $encoding) {
@@ -127,12 +127,13 @@ class Stringy {
     }
 
     /**
-     * Returns a lowercase and trimmed string seperated by underscores, with
+     * Returns a lowercase and trimmed string seperated by underscores.
-     * multibyte support. Underscores are inserted before uppercase characters
+     * Underscores are inserted before uppercase characters (with the exception
-     * (with the exception of the first character of the string), and in place
+     * of the first character of the string), and in place of spaces as well as
-     * of spaces as well as dashes.
+     * dashes.
      *
-     * @param   string  $string  String to convert
+     * @param   string  $string    String to convert
+     * @param   string  $encoding  The character encoding
      * @return  string  Underscored string
      */
     private static function underscored($string, $encoding) {
@@ -143,9 +144,10 @@ class Stringy {
     }
 
     /**
-     * Returns a case swapped version of a string, with multibyte support.
+     * Returns a case swapped version of a string.
      *
-     * @param   string  $string  String to swap case
+     * @param   string  $string    String to swap case
+     * @param   string  $encoding  The character encoding
      * @return  string  String with each character's case swapped
      */
     private static function swapCase($string, $encoding) {
@@ -162,6 +164,31 @@ class Stringy {
 
         return $swapped;
     }
+
+    /**
+     * Capitalizes the first letter of each word in a string, after trimming.
+     * Ignores the case of other letters, allowing for the use of acronyms.
+     * Also accepts an array, $ignore, allowing you to list words not to be
+     * capitalized.
+     *
+     * @param   string  $string    String to titleize
+     * @param   string  $encoding  The character encoding
+     * @param   array   $ignore    An array of words not to capitalize
+     * @return  string  Titleized string
+     */
+    private static function titleize($string, $encoding, $ignore = null) {
+        $titleized = preg_replace_callback(
+            '/([\S]+)/u',
+            function ($match) use (&$encoding, &$ignore) {
+                if ($ignore && in_array($match[0], $ignore))
+                    return $match[0];
+                return Stringy::upperCaseFirst($match[0], $encoding);
+            },
+            trim($string)
+        );
+
+        return $titleized;
+    }
 }
 
 ?>

tests/Stringy/StringyTest.php

@@ -188,6 +188,28 @@ class StringyTestCase extends PHPUnit_Framework_TestCase {
         return $testData;
     }
 
+    /**
+     * @dataProvider stringsForTitleize
+     */
+    public function testTitleize($string, $expected, $encoding = null, $ignore = null) {
+        $result = S::titleize($string, $encoding, $ignore);
+        $this->assertEquals($expected, $result);
+    }
+
+    public function stringsForTitleize() {
+        $ignore = array('at', 'by', 'for', 'in', 'of', 'on', 'out', 'to', 'the');
+
+        $testData = array(
+            array('testing the method', 'Testing The Method'),
+            array('testing the method', 'Testing the Method', 'UTF-8', $ignore),
+            array('i like to watch DVDs at home', 'I Like to Watch DVDs at Home',
+                'UTF-8', $ignore),
+            array('  Θα ήθελα να φύγει  ', 'Θα Ήθελα Να Φύγει', 'UTF-8')
+        );
+
+        return $testData;
+    }
+
 }
 
 ?>