EnumMap: added seek(), getKeys() and getValues() + null aware contains()

Author: marc-mabe

bench/EnumMapBench.php

@@ -48,11 +48,41 @@ public function init()
 
         $this->emptyMap = new EnumMap(Enum66::class);
         $this->fullMap  = new EnumMap(Enum66::class);
-        foreach ($this->enumerators as $enumerator) {
-            $this->fullMap->offsetSet($enumerator);
+        foreach ($this->enumerators as $i => $enumerator) {
+            $this->fullMap->offsetSet($enumerator, $i);
         }
     }
 
+    public function benchGetKeysEmpty()
+    {
+        $this->emptyMap->getKeys();
+    }
+
+    public function benchGetKeysFull()
+    {
+        $this->fullMap->getKeys();
+    }
+
+    public function benchGetValuesEmpty()
+    {
+        $this->emptyMap->getValues();
+    }
+
+    public function benchGetValuesFull()
+    {
+        $this->fullMap->getValues();
+    }
+
+    public function benchSearchTypeJuggling()
+    {
+        $this->fullMap->search('31');
+    }
+
+    public function benchSearchStrict()
+    {
+        $this->fullMap->search(31, true);
+    }
+
     public function benchOffsetSetEnumerator()
     {
         foreach ($this->enumerators as $enumerator) {
@@ -81,31 +111,31 @@ public function benchOffsetUnsetValue()
         }
     }
 
-    public function benchOffsetExistsEnumeratorTrue()
+    public function benchOffsetExistsEnumerator()
     {
         foreach ($this->enumerators as $enumerator) {
             $this->fullMap->offsetExists($enumerator);
         }
     }
 
-    public function benchOffsetExistsEnumeratorFalse()
+    public function benchOffsetExistsValue()
     {
-        foreach ($this->enumerators as $enumerator) {
-            $this->fullMap->offsetExists($enumerator);
+        foreach ($this->values as $value) {
+            $this->fullMap->offsetExists($value);
         }
     }
 
-    public function benchOffsetExistsValueTrue()
+    public function benchContainsEnumerator()
     {
-        foreach ($this->values as $value) {
-            $this->fullMap->offsetExists($value);
+        foreach ($this->enumerators as $enumerator) {
+            $this->fullMap->contains($enumerator);
         }
     }
 
-    public function benchOffsetExistsValueFalse()
+    public function benchContainsValue()
     {
         foreach ($this->values as $value) {
-            $this->fullMap->offsetExists($value);
+            $this->fullMap->contains($value);
         }
     }
 

src/EnumMap.php

@@ -5,7 +5,8 @@
 use ArrayAccess;
 use Countable;
 use InvalidArgumentException;
-use Iterator;
+use OutOfBoundsException;
+use SeekableIterator;
 use UnexpectedValueException;
 
 /**
@@ -15,7 +16,7 @@
  * @copyright Copyright (c) 2017 Marc Bennewitz
  * @license http://github.com/marc-mabe/php-enum/blob/master/LICENSE.txt New BSD License
  */
-class EnumMap implements ArrayAccess, Countable, Iterator
+class EnumMap implements ArrayAccess, Countable, SeekableIterator
 {
     /**
      * The classname of the enumeration type
@@ -67,43 +68,63 @@ public function getEnumeration()
     }
 
     /**
-     * Attach a new enumerator or overwrite an existing one
-     * @param Enum|null|boolean|int|float|string $enumerator
-     * @param mixed                              $data
-     * @return void
-     * @throws InvalidArgumentException On an invalid given enumerator
+     * Get a list of map keys
+     * @return Enum[]
      */
-    public function attach($enumerator, $data = null)
+    public function getKeys()
     {
-        return $this->offsetSet($enumerator, $data);
+        return \array_map([$this->enumeration, 'byOrdinal'], $this->ordinals);
     }
 
     /**
-     * Test if the given enumerator exists
-     * @param Enum|null|boolean|int|float|string $enumerator
-     * @return boolean
+     * Get a list of map values
+     * @return mixed[]
      */
-    public function contains($enumerator)
+    public function getValues()
     {
-        return $this->offsetExists($enumerator);
+        return \array_values($this->map);
     }
 
     /**
-     * Detach an enumerator
-     * @param Enum|null|boolean|int|float|string $enumerator
-     * @return void
-     * @throws InvalidArgumentException On an invalid given enumerator
+     * Search for the given value
+     * @param mixed $value
+     * @param bool $strict Use strict type comparison
+     * @return Enum|null The found key or NULL
      */
-    public function detach($enumerator)
+    public function search($value, $strict = false)
     {
-        $this->offsetUnset($enumerator);
+        $ord = \array_search($value, $this->map, $strict);
+        if ($ord !== false) {
+            $enumeration = $this->enumeration;
+            return $enumeration::byOrdinal($ord);
+        }
+
+        return null;
     }
 
     /**
      * Test if the given enumerator exists
      * @param Enum|null|boolean|int|float|string $enumerator
      * @return boolean
-     * @see contains()
+     * @see offsetExists
+     */
+    public function contains($enumerator)
+    {
+        try {
+            $enumeration = $this->enumeration;
+            $ord  = $enumeration::get($enumerator)->getOrdinal();
+            return array_key_exists($ord, $this->map);
+        } catch (InvalidArgumentException $e) {
+            // An invalid enumerator can't be contained in this map
+            return false;
+        }
+    }
+
+    /**
+     * Test if the given enumerator key exists and is not NULL
+     * @param Enum|null|boolean|int|float|string $enumerator
+     * @return boolean
+     * @see contains
      */
     public function offsetExists($enumerator)
     {
@@ -112,7 +133,7 @@ public function offsetExists($enumerator)
             $ord  = $enumeration::get($enumerator)->getOrdinal();
             return isset($this->map[$ord]);
         } catch (InvalidArgumentException $e) {
-            // An invalid enumerator can't be contained in this map
+            // An invalid enumerator can't be an offset of this map
             return false;
         }
     }
@@ -145,15 +166,15 @@ public function offsetGet($enumerator)
      * @throws InvalidArgumentException On an invalid given enumerator
      * @see attach()
      */
-    public function offsetSet($enumerator, $data = null)
+    public function offsetSet($enumerator, $value = null)
     {
         $enumeration = $this->enumeration;
         $ord = $enumeration::get($enumerator)->getOrdinal();
 
         if (!isset($this->map[$ord])) {
             $this->ordinals[] = $ord;
         }
-        $this->map[$ord] = $data;
+        $this->map[$ord] = $value;
     }
 
     /**
@@ -170,9 +191,24 @@ public function offsetUnset($enumerator)
 
         if (($idx = \array_search($ord, $this->ordinals, true)) !== false) {
             unset($this->map[$ord], $this->ordinals[$idx]);
+            $this->ordinals = \array_values($this->ordinals);
         }
     }
 
+    /**
+     * Seeks to the given iterator position.
+     * @param int $pos
+     */
+    public function seek($pos)
+    {
+        $pos = (int)$pos;
+        if (!isset($this->ordinals[$pos])) {
+            throw new OutOfBoundsException("Position {$pos} not found");
+        }
+
+        $this->pos = $pos;
+    }
+
     /**
      * Get the current value
      * @return mixed