Added toBoolean

README.md

@@ -74,6 +74,7 @@ S::create('string')->toTitleCase()->ensureRight('y') == 'Stringy'
     * [tidy](#tidy)
     * [titleize](#titleize-array-ignore)
     * [toAscii](#toascii)
+    * [toBoolean](#toboolean)
     * [toLowerCase](#tolowercase)
     * [toSpaces](#tospaces-tablength--4-)
     * [toTabs](#totabs-tablength--4-)
@@ -733,6 +734,20 @@ unless instructed otherwise.
 S::create('fòô bàř')->toAscii(); // 'foo bar'
 ```
 
+##### toBoolean()
+
+Returns a boolean representation of the given logical string value.
+For example, 'true', '1', 'on' and 'yes' will return true. 'false', '0',
+'off', and 'no' will return false. In all instances, case is ignored.
+For other numeric strings, their sign will determine the return value.
+In addition, blank strings consisting of only whitespace will return
+false. For all other strings, the return value is a result of a
+boolean cast.
+
+```php
+S::create('OFF')->toBoolean(); // false
+```
+
 ##### toLowerCase()
 
 Converts all characters in the string to lowercase. An alias for PHP's

src/Stringy.php

@@ -753,6 +753,40 @@ class Stringy implements \Countable, \IteratorAggregate, \ArrayAccess
         return (string) $substring === $endOfStr;
     }
 
+    /**
+     * Returns a boolean representation of the given logical string value.
+     * For example, 'true', '1', 'on' and 'yes' will return true. 'false', '0',
+     * 'off', and 'no' will return false. In all instances, case is ignored.
+     * For other numeric strings, their sign will determine the return value.
+     * In addition, blank strings consisting of only whitespace will return
+     * false. For all other strings, the return value is a result of a
+     * boolean cast.
+     *
+     * @return bool A boolean value for the string
+     */
+    public function toBoolean()
+    {
+        $key = $this->toLowerCase()->str;
+        $map = array(
+            'true'  => true,
+            '1'     => true,
+            'on'    => true,
+            'yes'   => true,
+            'false' => false,
+            '0'     => false,
+            'off'   => false,
+            'no'    => false
+        );
+
+        if (array_key_exists($key, $map)) {
+            return $map[$key];
+        } elseif (is_numeric($this->str)) {
+           return (intval($this->str) > 0);
+        } else {
+            return (bool) $this->regexReplace('[[:space:]]', '')->str;
+        }
+    }
+
     /**
      * Converts each tab in the string to some number of spaces, as defined by
      * $tabLength. By default, each tab is converted to 4 consecutive spaces.

tests/StringyTest.php

@@ -820,6 +820,39 @@ class StringyTestCase extends PHPUnit_Framework_TestCase
         );
     }
 
+    /**
+     * @dataProvider toBooleanProvider()
+     */
+    public function testToBoolean($expected, $str, $encoding = null)
+    {
+        $stringy = S::create($str, $encoding);
+        $result = $stringy->toBoolean();
+        $this->assertInternalType('boolean', $result);
+        $this->assertEquals($expected, $result);
+        $this->assertEquals($str, $stringy);
+    }
+
+    public function toBooleanProvider()
+    {
+        return array(
+            array(true, 'true'),
+            array(true, '1'),
+            array(true, 'on'),
+            array(true, 'ON'),
+            array(true, 'yes'),
+            array(true, '999'),
+            array(false, 'false'),
+            array(false, '0'),
+            array(false, 'off'),
+            array(false, 'OFF'),
+            array(false, 'no'),
+            array(false, '-999'),
+            array(false, ''),
+            array(false, ' '),
+            array(false, '  ', 'UTF-8') // narrow no-break space (U+202F)
+        );
+    }
+
     /**
      * @dataProvider toSpacesProvider()
      */