fix+doc: fix array methods as per test, add docs

Author: adhocore

src/UnderscoreArray.php

@@ -4,36 +4,72 @@
 
 class UnderscoreArray extends UnderscoreCollection
 {
+    /**
+     * Get the first n items.
+     *
+     * @param integer $n
+     *
+     * @return array
+     */
     public function first($n = 1)
     {
         return $this->slice($n, true);
     }
 
+    /**
+     * Alias of first().
+     */
     public function head($n = 1)
     {
         return $this->first($n);
     }
 
+    /**
+     * Alias of first().
+     */
     public function take($n = 1)
     {
         return $this->first($n);
     }
 
+    /**
+     * Get the last n items.
+     *
+     * @param integer $n
+     *
+     * @return array
+     */
     public function last($n = 1)
     {
         return $this->slice($n, false);
     }
 
+    /**
+     * Alias of last().
+     */
     public function tail($n = 1)
     {
         return $this->last($n);
     }
 
+    /**
+     * Alias of last().
+     */
     public function drop($n = 1)
     {
         return $this->last($n);
     }
 
+    /**
+     * Extracts n items from first or last.
+     *
+     * @internal
+     *
+     * @param integer $n
+     * @param boolean $isFirst From first if true, else last.
+     *
+     * @return array
+     */
     protected function slice($n, $isFirst = true)
     {
         if ($n < 2) {
@@ -47,16 +83,33 @@ protected function slice($n, $isFirst = true)
         return \array_slice($this->data, $isFirst ? 0 : $c - $n, $isFirst ? $n : null, true);
     }
 
+    /**
+     * Get only the truthy items.
+     *
+     * @return self
+     */
     public function compact()
     {
-        return new static(\array_filter($this->data));
+        return $this->filter(null);
     }
 
+    /**
+     * Gets the flattened version of multidimensional items.
+     *
+     * @return self
+     */
     public function flatten()
     {
         return new static($this->flat($this->data));
     }
 
+    /**
+     * Gets the unique items using the id resulted from callback.
+     *
+     * @param callback|string $fn The callback. String is resolved to value of that index.
+     *
+     * @return self
+     */
     public function unique($fn = null)
     {
         if (null === $fn) {
@@ -71,28 +124,57 @@ public function unique($fn = null)
         });
     }
 
+    /**
+     * Alias of unique().
+     */
     public function uniq($fn = null)
     {
         return $this->unique($fn);
     }
 
+    /**
+     * Get the items whose value is not in given data.
+     *
+     * @param array|mixed $data Array or array like or array convertible.
+     *
+     * @return self
+     */
     public function difference($data)
     {
-        return new static(\array_diff($this->data, $this->asArray($data)));
+        $data = $this->asArray($data);
+
+        return $this->filter(function ($value) use ($data) {
+            return !\in_array($value, $data);
+        });
     }
 
+    /**
+     * Alias of without().
+     */
     public function without($data)
     {
         return $this->difference($data);
     }
 
+    /**
+     * Get the union/merger of items with given data.
+     *
+     * @param array|mixed $data Array or array like or array convertible.
+     *
+     * @return self
+     */
     public function union($data)
     {
-        return new static(\array_unique(
-            \array_merge($this->data, $this->asArray($data))
-        ));
+        return new static(\array_merge($this->data, $this->asArray($data)));
     }
 
+    /**
+     * Gets the items whose value is common with given data.
+     *
+     * @param array|mixed $data Array or array like or array convertible.
+     *
+     * @return self
+     */
     public function intersection($data)
     {
         $data = $this->asArray($data);
@@ -102,6 +184,13 @@ public function intersection($data)
         });
     }
 
+    /**
+     * Group the values from data and items having same indexes together.
+     *
+     * @param array|mixed $data Array or array like or array convertible.
+     *
+     * @return self
+     */
     public function zip($data)
     {
         $data = $this->asArray($data);
@@ -111,38 +200,77 @@ public function zip($data)
         });
     }
 
-    public function unzip()
-    {
-        //
-    }
-
+    /**
+     * Hydrate the items into given class or stdClass.
+     *
+     * @param string $className FQCN of the class whose constructor accepts two parameters: value and index.
+     *
+     * @return self
+     */
     public function object($className = null)
     {
-        return $this->map(function ($value, $index) {
+        return $this->map(function ($value, $index) use ($className) {
             return $className ? new $className($value, $index) : (object) \compact('value', 'index');
         });
     }
 
-    public function firstIndex($fn)
+    /**
+     * Find the first index that passes given truth test.
+     *
+     * @param callable $fn The truth test callback.
+     *
+     * @return mixed|null
+     */
+    public function firstIndex($fn = null)
     {
-        return $this->find($fn, false);
+        return $this->find($this->valueFn($fn), false);
     }
 
-    public function lastIndex($fn)
+    /**
+     * Find the larst index that passes given truth test.
+     *
+     * @param callable $fn The truth test callback.
+     *
+     * @return mixed|null
+     */
+    public function lastIndex($fn = null)
     {
-        return (new static(\array_reverse($this->data, true)))->find($fn, false);
+        return (new static(\array_reverse($this->data, true)))->find($this->valueFn($fn), false);
     }
 
+    /**
+     * Find the first index of given value if available null otherwise.
+     *
+     * @param callable $fn The truth test callback.
+     *
+     * @return string|int|null
+     */
     public function indexOf($value)
     {
-        return \array_search($value, $this->data);
+        return (false === $index = \array_search($value, $this->data)) ? null : $index;
     }
 
+    /**
+     * Find the last index of given value if available null otherwise.
+     *
+     * @param callable $fn The truth test callback.
+     *
+     * @return string|int|null
+     */
     public function lastIndexOf($value)
     {
-        return \array_search($value, \array_reverse($this->data, true));
+        return (false === $index = \array_search($value, \array_reverse($this->data, true))) ? null : $index;
     }
 
+    /**
+     * Creates a new range from start to stop with given step.
+     *
+     * @param int $start
+     * @param int $stop
+     * @param int $step
+     *
+     * @return self
+     */
     public function range($start, $stop, $step = 1)
     {
         return new static(\range($start, $stop, $step));