Merge pull request #2 from DarkGhostHunter/master

random_bool and minor fix.

README.md

@@ -25,13 +25,15 @@ This package includes helpful global helpers for your project, separated into di
 ### General purpose
 
 * `collect_lazy`: Creates a new Lazy Collection.
-* `collect_times`: Create a new collection by invoking the callback a given amount of times.
-* `data_transform`: Transform an item of an array or object using a callable.
-* `enclose`: Wraps a value into a Closure. It accepts another callable to handle the value.
+* `collect_times`: Create a new collection by invoking a callback a given amount of times.
+* `data_transform`: Transform an item of an array or object using a callback.
+* `enclose`: Wraps a value into a Closure. It accepts another callback to handle the value.
 * `fluent`: Creates a new Fluent instance.
 * `pipeline`: Sends an object through a pipeline.
+* `random_bool`: Returns a random boolean value.
 * `random_unique`: Returns a unique amount of results from a random generator executed a number of times.
-* `none_of`: Checks if none of the options compared or called returns true.
+* `list_from`: Skips the first values of an array, so these can be listed into variables.
+* `none_of`: Checks if none of the options compared or called to a subject returns true.
 * `throttle`: Throttles a given callback by a key.
 * `unless`: Returns a value when a condition is falsy.
 * `swap_vars`: Swap two variables values, and returns the second variable original value.
@@ -51,8 +53,8 @@ This package includes helpful global helpers for your project, separated into di
 
 * `base_path_of`: Return the path of a class from the project root path.
 * `class_defined_at`: Returns where the file path where the class was defined.
-* `dot_path`: Returns a relative path in dot notation.
-* `undot_path`:Returns a relative path from a dot notation string.
+* `dot_path`: Transform a relative path to dot notation.
+* `undot_path`: Transforms a path from dot notation to a relative path.
 
 ### HTTP
 
@@ -64,7 +66,7 @@ This package includes helpful global helpers for your project, separated into di
 
 ### Objects
 
-* `arguments_of`: Returns a collection of arguments received by the given callable.
+* `arguments_of`: Returns a collection of arguments received by the given callback.
 * `call_existing`: Calls a dynamic method or macro if it exists in the object instance.
 * `replicate`: Replicates an object.
 * `has_trait`: Checks recursively if the object is using a trait.

src/filesystem.php

@@ -54,7 +54,7 @@ function dot_path($path)
 
 if (! function_exists('undot_path')) {
     /**
-     * Returns a relative path from a dot notation string.
+     * Transforms a path from dot notation to a relative path.
      *
      * @param  string  $path
      * @return string

src/helpers.php

@@ -32,7 +32,7 @@ function collect_lazy($source, $callback = null)
 
 if (! function_exists('collect_times')) {
     /**
-     * Create a new collection by invoking the callback a given amount of times.
+     * Create a new collection by invoking a callback a given amount of times.
      *
      * @param  callable  $callback
      * @param  int|null  $times
@@ -46,7 +46,7 @@ function collect_times($times, callable $callback = null)
 
 if (! function_exists('data_transform')) {
     /**
-     * Transform an item of an array or object using a callable.
+     * Transform an item of an array or object using a callback.
      *
      * @param  mixed  $target
      * @param  string|array  $key
@@ -60,7 +60,7 @@ function data_transform(&$target, $key, callable $callable)
 
 if (! function_exists('enclose')) {
     /**
-     * Wraps a value into a Closure. It accepts another callable to handle the value.
+     * Wraps a value into a Closure. It accepts another callback to handle the value.
      *
      * @param  mixed  $value
      * @return \Closure
@@ -169,7 +169,7 @@ function when($condition, $value, $default = null)
 
 if (! function_exists('none_of')) {
     /**
-     * Checks if none of the options compared or called returns true.
+     * Checks if none of the options compared or called to a subject returns true.
      *
      * @param  mixed  $subject
      * @param  array|iterable  $options
@@ -182,12 +182,34 @@ function none_of($subject, $options, $callback = null)
     }
 }
 
+if (! function_exists('random_bool')) {
+    /**
+     * Returns a random boolean value.
+     *
+     * If the seed is zero, it will always return `false`.
+     *
+     * If the seed is negative, odds will favor `false`.
+     *
+     * @param  int  $seed
+     * @return bool
+     */
+    function random_bool($seed = 1)
+    {
+        if ($seed < 0) {
+            return (bool)random_int($seed, 1);
+        }
+
+        return (bool)random_int(0, $seed);
+    }
+}
+
 if (! function_exists('random_unique')) {
     /**
      * Returns a unique amount of results from a random generator executed a number of times.
      *
-     * If $overflow is true, the loop will end only when the results match the number of executions.
-     * This can make endless loops, so use with caution around callbacks without enough entropy.
+     * If `$overflow` is true, the loop will end only when the results match the number of
+     * executions, which may create endless loops. Use with caution around callbacks that
+     * don't have enough entropy to return unique results, like 10 times on `rand(1,2)`.
      *
      * @param  int  $times
      * @param  callable  $callback
@@ -235,10 +257,26 @@ function swap_vars(&$swap, &$swapped)
     }
 }
 
+if (! function_exists('list_from')) {
+    /**
+     * Skips the first values of an array, so these can be listed into variables.
+     *
+     * @param  array  $items
+     * @param  int  $offset
+     * @return array
+     */
+    function list_from($items, $offset = 1)
+    {
+        return array_slice(array_values($items), $offset);
+    }
+}
+
 if (! function_exists('which_of')) {
     /**
      * Returns the first option which comparison or callback returns true.
      *
+     * If no results returns truthy, `false` will be returned.
+     *
      * @param  mixed  $subject
      * @param  array|iterable  $options
      * @param  callable|null  $callback
@@ -262,21 +300,25 @@ function which_of($subject, $options, $callback = null)
 
 if (! function_exists('while_sleep')) {
     /**
-     * Executes an operation while sleeping between multiple executions.
+     * Runs a callback while sleeping between multiple executions.
+     *
+     * It returns a collection of each callback result.
      *
      * @param  int  $times
-     * @param  int  $sleep
+     * @param  int  $sleep  Milliseconds to sleep. 1000 equals to 1 second.
      * @param  callable  $callback
      * @return \Illuminate\Support\Collection
      */
     function while_sleep($times, $sleep, $callback)
     {
         $sleep *= 1000;
 
-        return collect_times($times, static function ($iteration) use ($callback, $sleep) {
+        return collect_times($times, static function ($iteration) use ($callback, $sleep, $times) {
             $result = $callback($iteration);
 
-            usleep($sleep);
+            if ($iteration < $times) {
+                usleep($sleep);
+            }
 
             return $result;
         });

tests/HelpersTest.php

@@ -262,6 +262,33 @@ public function test_none_of()
         }));
     }
 
+    public function test_random_bool()
+    {
+        $this->assertFalse(random_bool(0));
+
+        $results = collect_times(10, function () {
+            return random_bool(1);
+        });
+
+        $results->each(function ($item) {
+            $this->assertIsBool($item);
+        });
+
+        $this->assertLessThan(10, $results->filter()->count());
+        $this->assertGreaterThan(0, $results->reject()->count());
+
+        $results = collect_times(10, function () {
+            return random_bool(-1);
+        });
+
+        $results->each(function ($item) {
+            $this->assertIsBool($item);
+        });
+
+        $this->assertLessThan(10, $results->filter()->count());
+        $this->assertGreaterThan(0, $results->reject()->count());
+    }
+
     public function test_random_unique()
     {
         $random_unique = random_unique(10, function () {
@@ -311,19 +338,6 @@ public function test_while_sleep()
 
         $this->assertInstanceOf(Collection::class, $collection);
         $this->assertCount(4, $collection);
-        $this->assertSame(4, $end - $start);
-    }
-
-    public function test_while_sleep_retry()
-    {
-        $start = time();
-        $collection = while_sleep(4, 1000, function () {
-            return microtime(false);
-        });
-        $end = time();
-
-        $this->assertInstanceOf(Collection::class, $collection);
-        $this->assertCount(4, $collection);
-        $this->assertSame(4, $end - $start);
+        $this->assertSame(3, $end - $start);
     }
 }