Merge remote-tracking branch 'origin/master'

README.md

@@ -32,12 +32,125 @@
 </tbody>
 </table>
 
-This package contains an utility class casting safely mixed values to bool, float, int, or string.
+This package contains a strong typed utility class safely testing and casting mixed values to bool, float, int, or
+string values.
 
+# Rationale
 
-#  License
+What is the purpose of this package and why is it necessary?
+PHP is a great language, however is has some quirks. One of them is that PHP will convert any string to an integer even
+when strict type is set.
 
-This project is licensed under the MIT license.
+The following code will not cause any error or warning (tested with PHP 7.2.12):
+```php
+<?php
+declare(strict_types=1);
+
+ini_set('display_errors', '1');
+error_reporting(E_ALL);
+
+echo '1: ', (int)'3.14', PHP_EOL;
+echo '2: ', (int)'123abc', PHP_EOL;
+echo '3: ', (int)"Ceci n'est pas une pipe.", PHP_EOL;
+echo '4: ', (int)'', PHP_EOL;
+echo '5: ', (int)null, PHP_EOL;
+```
+but gives the following output:
+```text
+1: 3
+2: 123
+3: 0
+4: 0
+5: 0
+```
+
+This package provides a strong typed utility class for safely testing and casting mixed typed values to Boolean,
+float, integer, or string values.
+
+# Manual
+
+The class `SetBased\Abc\Helper\Cast` has the following methods for testing mixed values against primitive data types:
+
+| Method      | Null Value    | Return Type |
+| ----------- | ------------- | ----------- |
+| isManBool   | returns false | bool        |
+| isManFloat  | returns false | bool        |
+| isManInt    | returns false | bool        |
+| isManString | returns false | bool        |
+| isOptBool   | returns true  | bool        |
+| isOptFloat  | returns true  | bool        |
+| isOptInt    | returns true  | bool        |
+| isOptString | returns true  | bool        |
+
+The class `SetBased\Abc\Helper\Cast` has the methods shown int he table below for casting mixed values to a primitive
+data type. When a value can not casted safely to a type n exception will be thrown.
+
+| Method      | Null Value          | Return Type  |
+| ----------- | ------------------- | ------------ |
+| toManBool   | throws an exception | bool         |
+| toManFloat  | throws an exception | float        |
+| toManInt    | throws an exception | int          |
+| toManString | throws an exception | string       |
+| toOptBool   | returns null        | bool\|null   |
+| toOptFloat  | returns null        | float\|null  |
+| toOptInt    | returns null        | int\|null    |
+| toOptString | returns null        | string\|null |
+
+Remarks:
+ * 'opt' is short for optional:  `null` values are valid. Testing and casting against `null` yields `true` and `null`, respectively.
+ * 'man' is short for mandatory: `null` values are not allowed. Testing against `null` yields `false` and casting `null` will throw an exception.
+
+## Sample
+
+Code:
+```php
+<?php
+declare(strict_types=1);
 
+use SetBased\Abc\Helper\Cast;
 
+$value = "Ceci n'est pas une pipe.";
+if (Cast::isManInt($value))
+{
+  echo 'This is not an integer', PHP_EOL;
+}
+else
+{
+  echo Cast::toManInt($value), PHP_EOL;
+}
 
+echo Cast::toManFloat($value), PHP_EOL;
+```
+
+Output:
+```
+This is not an integer
+
+Exception
+```
+
+## Booleans
+
+Only and only the following values are valid representations of boolean values:
+* `false`
+ * int(0)
+ * string(1) "0"
+ * bool(false)
+* `true`
+ * int(1)
+ * string(1) "1"
+ * bool(true)
+
+Hence, only these values can be casted safely to booleans and vice versa.
+
+
+# Installing
+
+```
+composer require setbased/helper-cast
+```
+
+
+#  License
+
+This project is licensed under the MIT license.