Several useful utils for Traversables

src/Utils.php

@@ -1,18 +1,20 @@
 <?php
 namespace GraphQL;
 
+use \Traversable, \InvalidArgumentException;
+
 class Utils
 {
     /**
-     * @param $obj
+     * @param object $obj
      * @param array $vars
-     * @return mixed
+     * @return array
      */
     public static function assign($obj, array $vars, array $requiredKeys = array())
     {
         foreach ($requiredKeys as $key) {
             if (!isset($key, $vars)) {
-                throw new \InvalidArgumentException("Key {$key} is expected to be set and not to be null");
+                throw new InvalidArgumentException("Key {$key} is expected to be set and not to be null");
             }
         }
 
@@ -27,20 +29,77 @@ class Utils
     }
 
     /**
-     * @param array $list
-     * @param $predicate
+     * @param array|Traversable $traversable
+     * @param callable $predicate
      * @return null
      */
-    public static function find(array $list, $predicate)
+    public static function find($traversable, callable $predicate)
     {
-        for ($i = 0; $i < count($list); $i++) {
-            if ($predicate($list[$i])) {
-                return $list[$i];
+        self::invariant(is_array($traversable) || $traversable instanceof \Traversable, __METHOD__ . ' expects array or Traversable');
+
+        foreach ($traversable as $key => $value) {
+            if ($predicate($value, $key)) {
+                return $value;
             }
         }
         return null;
     }
 
+    public static function filter($traversable, callable $predicate)
+    {
+        self::invariant(is_array($traversable) || $traversable instanceof \Traversable, __METHOD__ . ' expects array or Traversable');
+
+        $result = [];
+        $assoc = false;
+        foreach ($traversable as $key => $value) {
+            if (!$assoc && !is_int($key)) {
+                $assoc = true;
+            }
+            if ($predicate($value, $key)) {
+                $result[$key] = $value;
+            }
+        }
+
+        return $assoc ? $result : array_values($result);
+    }
+
+    /**
+     * @param array|\Traversable $traversable
+     * @param callable $fn function($value, $key) => $newValue
+     * @return array
+     * @throws \Exception
+     */
+    public static function map($traversable, callable $fn)
+    {
+        self::invariant(is_array($traversable) || $traversable instanceof \Traversable, __METHOD__ . ' expects array or Traversable');
+
+        $map = [];
+        foreach ($traversable as $key => $value) {
+            $map[$key] = $fn($value, $key);
+        }
+        return $map;
+    }
+
+    /**
+     * @param $traversable
+     * @param callable $keyFn function($value, $key) => $newKey
+     * @return array
+     * @throws \Exception
+     */
+    public static function keyMap($traversable, callable $keyFn)
+    {
+        self::invariant(is_array($traversable) || $traversable instanceof \Traversable, __METHOD__ . ' expects array or Traversable');
+
+        $map = [];
+        foreach ($traversable as $key => $value) {
+            $newKey = $keyFn($value, $key);
+            if (is_scalar($newKey)) {
+                $map[$newKey] = $value;
+            }
+        }
+        return $map;
+    }
+
     /**
      * @param $test
      * @param string $message
@@ -69,6 +128,13 @@ class Utils
         return is_object($var) ? get_class($var) : gettype($var);
     }
 
+    /**
+     * UTF-8 compatible chr()
+     *
+     * @param string $ord
+     * @param string $encoding
+     * @return string
+     */
     public static function chr($ord, $encoding = 'UTF-8')
     {
         if ($ord <= 255) {
@@ -84,7 +150,7 @@ class Utils
     /**
      * UTF-8 compatible ord()
      *
-     * @param $char
+     * @param string $char
      * @param string $encoding
      * @return mixed
      */
@@ -94,28 +160,23 @@ class Utils
             return ord($char);
         }
         if ($encoding === 'UCS-4BE') {
-            list(, $ord) = (strlen($char) === 4) ? @unpack('N', $char) : @unpack('n', $char);
+            list(, $ord) = (strlen($char) === 4) ? unpack('N', $char) : unpack('n', $char);
             return $ord;
         } else {
             return self::ord(mb_convert_encoding($char, 'UCS-4BE', $encoding), 'UCS-4BE');
         }
     }
 
+    /**
+     * Returns UTF-8 char code at given $positing of the $string
+     *
+     * @param $string
+     * @param $position
+     * @return mixed
+     */
     public static function charCodeAt($string, $position)
     {
         $char = mb_substr($string, $position, 1, 'UTF-8');
         return self::ord($char);
     }
-
-    /**
-     *
-     */
-    public static function keyMap(array $list, callable $keyFn)
-    {
-        $map = [];
-        foreach ($list as $value) {
-            $map[$keyFn($value)] = $value;
-        }
-        return $map;
-    }
 }