From bded15d683caf9fa6c847a5f5134362ea6a17917 Mon Sep 17 00:00:00 2001
From: "Daniel St. Jules" <danielst.jules@gmail.com>
Date: Thu, 23 Jul 2015 23:40:21 -0700
Subject: [PATCH] Added toBoolean

---
 README.md             | 15 +++++++++++++++
 src/Stringy.php       | 34 ++++++++++++++++++++++++++++++++++
 tests/StringyTest.php | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+)

diff --git a/README.md b/README.md
index 74f0f70..a638c04 100644
--- a/README.md
+++ b/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
diff --git a/src/Stringy.php b/src/Stringy.php
index cd02936..b36d650 100644
--- a/src/Stringy.php
+++ b/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.
diff --git a/tests/StringyTest.php b/tests/StringyTest.php
index dad7331..d51d73a 100644
--- a/tests/StringyTest.php
+++ b/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()
      */