Merge pull request #5 from adhocore/develop

Develop

Author: adhocore

src/Underscore.php

@@ -2,77 +2,75 @@
 
 namespace Ahc\Underscore;
 
-final class Underscore extends UnderscoreArray
+final class Underscore extends UnderscoreFunction
 {
     /**
-     * Returns a callable which when invoked caches the result for given arguments
-     * and reuses that result in subsequent calls.
+     * Generates a function that always returns a constant value.
      *
-     * @param callable $fn The main callback.
+     * @param mixed $value
      *
-     * @return mixed
+     * @return callable
      */
-    public function memoize(callable $fn)
+    public function constant($value)
     {
-        static $memo = [];
-
-        return function () use (&$memo, $fn) {
-            $hash = \md5(\json_encode($args = \func_get_args()));
-
-            if (isset($memo[$hash])) {
-                return $memo[$hash];
-            }
-
-            return $memo[$hash] = \call_user_func_array($fn, $args);
+        return function () use ($value) {
+            return $value;
         };
     }
 
     /**
-     * Cache the result of callback for given arguments and reuse that in subsequent call.
+     * No operation!
      *
-     * @param callable $fn   The main callback.
-     * @param int      $wait The time to wait in millisec.
-     *
-     * @return mixed
+     * @return void
      */
-    public function delay(callable $fn, $wait)
+    public function noop()
     {
-        return function () use ($fn, $wait) {
-            \usleep(1000 * $wait);
-
-            return \call_user_func_array($fn, \func_get_args());
-        };
+        // ;)
     }
 
     /**
-     * Returns a callable that wraps given callable which can be only invoked
-     * at most once per given $wait threshold.
+     * Run callable n times and create new collection.
      *
-     * @param callable $fn   The main callback.
-     * @param int      $wait The callback will only be triggered at most once within this period.
+     * @param int      $n
+     * @param callable $fn
      *
-     * @return mixed The return set of callback if runnable else the previous cache.
+     * @return self
      */
-    public function throttle(callable $fn, $wait)
+    public function times($n, callable $fn)
     {
-        static $previous = 0;
-        static $result   = null;
+        $data = [];
 
-        return function () use ($fn, &$previous, &$result, &$wait) {
-            $now = $this->now();
+        for ($i = 0; $i < $n; $i++) {
+            $data[$i] = $fn($i);
+        }
 
-            if (!$previous) {
-                $previous = $now;
-            }
+        return new static($data);
+    }
 
-            $remaining = $wait - ($now - $previous);
+    /**
+     * Return a random integer between min and max (inclusive).
+     *
+     * @param int $min
+     * @param int $max
+     *
+     * @return int
+     */
+    public function random($min, $max)
+    {
+        return \mt_rand($min, $max);
+    }
 
-            if ($remaining <= 0 || $remaining > $wait) {
-                $previous = $now;
-                $result   = \call_user_func_array($fn, \func_get_args());
-            }
+    /**
+     * Generate unique ID (unique for current go/session).
+     *
+     * @param string $prefix
+     *
+     * @return string
+     */
+    public function uniqueId($prefix = '')
+    {
+        static $id = 0;
 
-            return $result;
-        };
+        return $prefix . (++$id);
     }
 }

src/UnderscoreArray.php

@@ -18,6 +18,10 @@ public function first($n = 1)
 
     /**
      * Alias of first().
+     *
+     * @param int $n
+     *
+     * @return array
      */
     public function head($n = 1)
     {
@@ -26,6 +30,10 @@ public function head($n = 1)
 
     /**
      * Alias of first().
+     *
+     * @param int $n
+     *
+     * @return array
      */
     public function take($n = 1)
     {
@@ -46,6 +54,10 @@ public function last($n = 1)
 
     /**
      * Alias of last().
+     *
+     * @param int $n
+     *
+     * @return array
      */
     public function tail($n = 1)
     {
@@ -54,6 +66,10 @@ public function tail($n = 1)
 
     /**
      * Alias of last().
+     *
+     * @param int $n
+     *
+     * @return array
      */
     public function drop($n = 1)
     {
@@ -106,7 +122,7 @@ public function flatten()
     /**
      * Gets the unique items using the id resulted from callback.
      *
-     * @param callback|string $fn The callback. String is resolved to value of that index.
+     * @param callable|string $fn The callback. String is resolved to value of that index.
      *
      * @return self
      */
@@ -126,6 +142,10 @@ public function unique($fn = null)
 
     /**
      * Alias of unique().
+     *
+     * @param callable|string $fn The callback. String is resolved to value of that index.
+     *
+     * @return self
      */
     public function uniq($fn = null)
     {
@@ -149,7 +169,11 @@ public function difference($data)
     }
 
     /**
-     * Alias of without().
+     * Alias of difference().
+     *
+     * @param array|mixed $data Array or array like or array convertible.
+     *
+     * @return self
      */
     public function without($data)
     {
@@ -203,7 +227,7 @@ public function zip($data)
     /**
      * Hydrate the items into given class or stdClass.
      *
-     * @param string $className FQCN of the class whose constructor accepts two parameters: value and index.
+     * @param string|null $className FQCN of the class whose constructor accepts two parameters: value and index.
      *
      * @return self
      */
@@ -221,19 +245,19 @@ public function object($className = null)
      *
      * @return mixed|null
      */
-    public function firstIndex($fn = null)
+    public function findIndex($fn = null)
     {
         return $this->find($this->valueFn($fn), false);
     }
 
     /**
-     * Find the larst index that passes given truth test.
+     * Find the last index that passes given truth test.
      *
      * @param callable $fn The truth test callback.
      *
      * @return mixed|null
      */
-    public function lastIndex($fn = null)
+    public function findLastIndex($fn = null)
     {
         return (new static(\array_reverse($this->data, true)))->find($this->valueFn($fn), false);
     }
@@ -262,6 +286,37 @@ public function lastIndexOf($value)
         return (false === $index = \array_search($value, \array_reverse($this->data, true))) ? null : $index;
     }
 
+    /**
+     * Gets the smallest index at which an object should be inserted so as to maintain order.
+     *
+     * Note that the initial stack must be sorted already.
+     *
+     * @param $object             The new object which needs to be adjusted in stack.
+     * @param callable|string $fn The comparator callback.
+     *
+     * @return string|int|null
+     */
+    public function sortedIndex($object, $fn)
+    {
+        $low   = 0;
+        $high  = $this->count();
+        $data  = $this->values();
+        $fn    = $this->valueFn($fn);
+        $value = $fn($object);
+        $keys  = $this->keys();
+
+        while ($low < $high) {
+            $mid = \intval(($low + $high) / 2);
+            if ($fn($data[$mid]) < $value) {
+                $low = $mid + 1;
+            } else {
+                $high = $mid;
+            }
+        }
+
+        return isset($keys[$low]) ? $keys[$low] : null;
+    }
+
     /**
      * Creates a new range from start to stop with given step.
      *

src/UnderscoreBase.php

@@ -4,11 +4,14 @@
 
 class UnderscoreBase implements \ArrayAccess, \Countable, \IteratorAggregate, \JsonSerializable
 {
-    const VERSION = '0.0.1';
+    const VERSION = '0.0.2';
 
     /** @var array The array manipulated by this Underscore instance */
     protected $data;
 
+    /** @var array Custom userland functionality through named callbacks */
+    protected static $mixins = [];
+
     /**
      * Constructor.
      *
@@ -205,6 +208,8 @@ public function count()
 
     /**
      * Alias of count().
+     *
+     * @return int
      */
     public function size()
     {
@@ -328,10 +333,76 @@ public function omit($index)
         return $this->pick($indices);
     }
 
+    /**
+     * Creates a shallow copy.
+     *
+     * @return self
+     */
+    public function clon()
+    {
+        return clone $this;
+    }
+
+    /**
+     * Invokes callback fn with clone and returns original self.
+     *
+     * @param callable $fn
+     *
+     * @return self
+     */
+    public function tap(callable $fn)
+    {
+        $fn($this->clon());
+
+        return $this;
+    }
+
+    /**
+     * Adds a custom handler/method to instance. The handler is bound to this instance.
+     *
+     * @param string   $name
+     * @param \Closure $fn
+     *
+     * @return self
+     */
+    public static function mixin($name, \Closure $fn)
+    {
+        static::$mixins[$name] = $fn;
+    }
+
+    /**
+     * Calls the registered mixin by its name.
+     *
+     * @param string $name
+     * @param array  $args
+     *
+     * @return self
+     */
+    public function __call($method, $args)
+    {
+        if (isset(static::$mixins[$method])) {
+            $method = \Closure::bind(static::$mixins[$method], $this);
+
+            return $method($args);
+        }
+
+        throw new UnderscoreException("The mixin with name '$method' is not defined");
+    }
+
+    /**
+     * Get string value (JSON representation) of this instance.
+     *
+     * @return string
+     */
+    public function valueOf()
+    {
+        return (string) $this;
+    }
+
     /**
      * A static shortcut to constructor.
      *
-     * @param mixed $data
+     * @param array|mixed $data Array or array like or array convertible.
      *
      * @return self
      */