Merge pull request #19 from worksolutions/dev

Map interface improvements (stream, foreach)

Author: sokolovsky

README.md

@@ -593,6 +593,8 @@ Classes implement `Stack` interface: ```HashMap```
 - [*containsKey* – Sign of the presence of a key pair](#containskey---sign-of-the-presence-of-a-key-pair)
 - [*containsValue* – Sign of the presence of a pair by value](#containsvalue---sign-of-the-presence-of-a-pair-by-value)
 - [*size* – Number of pairs in the card](#size---number-of-pairs-in-the-card)
+- [*stream* - Getting traverse stream with collection of key/value pair (Stream)](#stream---getting-traverse-streamw-with-collection-of-key-value-pair-stream)
+- [Traverse map in _foreach_ loop](#Traverse-map-in-_foreach_-loop)
 
 #### put - Adding key/value pair
 [[↑ Map]](#map)
@@ -761,6 +763,56 @@ $map->size(); // 0
 
 ```
 
+#### _stream_ - Getting traverse stream with collection of pair key/value (Stream)
+[[↑ Map]](#map)
+```
+stream(): Stream;
+```
+
+Method returns object of Stream interface. Internal collection elements are pair of key/value. 
+
+```php
+
+use \WS\Utils\Collections\HashMap;
+use \WS\Utils\Collections\MapEntry;
+
+$map = new HashMap();
+
+$map->put('one', 1);
+$map->put('two', 2);
+$map->put('tree', 3);
+
+$map->stream()->each(static function (MapEntry $mapEntry) {
+    var_export($mapEntry->getKey()); // 'one', 'two', 'three'
+    var_export($mapEntry->getKey()); // 1    , 2    , 3
+});
+
+```
+
+#### Traverse map in _foreach_ loop
+[[↑ Map]](#map)
+
+Object of Map interface can iterated in *foreach* loop. In this case keys and values will be passed before ones. Key can be of any type except an array.
+
+```php
+
+use \WS\Utils\Collections\HashMap;
+
+$map = new HashMap();
+
+$map->put(new SplObjectStorage(), 1);
+$map->put(null, 2);
+$map->put(false, 3);
+$map->put(true, 4);
+$map->put(0, 5);
+
+foreach($map as $key => $value) {
+    var_export($key);   // object of SplObjectStorage class| null| false| true| 0 
+    var_export($value); // 1                               | 2   | 3    | 4   | 5
+}
+
+```
+
 ## Collection factory
 [[↑ Up]](#php-collections)
 

composer.json

@@ -3,7 +3,7 @@
   "description": "Collections library for php language",
   "minimum-stability": "dev",
   "license": "MIT",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "authors": [
     {
       "name": "Maxim Sokolovsky",

doc/README.ru.md

@@ -593,6 +593,8 @@ $queue->peek(); // RuntimeException
 - [*containsKey* – Признак наличия пары по ключу](#containskey---признак-наличия-пары-по-ключу)
 - [*containsValue* – Признак наличия пары по значению](#containsvalue---признак-наличия-пары-по-значению)
 - [*size* – Количество пар в карте](#size---количество-пар-в-карте)
+- [*stream* – Получение потока обхода коллекции пар ключ/значение (Stream)](#stream---получение-потока-обхода-коллекции-пар-ключ-значение-stream)
+- [Обход объекта map при помощи цикла _foreach_](#обход-объекта-map-при-помощи-цикла-_foreach_)
 
 #### _put_ - Добавление пары *ключ/значение*
 [[↑ Карта (Map)]](#карта-map)
@@ -761,6 +763,56 @@ $map->size(); // 0
 
 ```
 
+#### _stream_ - Получение потока обхода коллекции пар ключ/значение (Stream)
+[[↑ Карта (Map)]](#карта-map)
+```
+stream(): Stream;
+```
+
+Метод возвращает объект, который реализует интерфейс обхода (Stream). Элементами коллекции потока являются объекты пар ключ/значение `KeyPair`. [Подробнее...](#Поток обхода коллекции)
+
+```php
+
+use \WS\Utils\Collections\HashMap;
+use \WS\Utils\Collections\MapEntry;
+
+$map = new HashMap();
+
+$map->put('one', 1);
+$map->put('two', 2);
+$map->put('tree', 3);
+
+$map->stream()->each(static function (MapEntry $mapEntry) {
+    var_export($mapEntry->getKey()); // 'one', 'two', 'three'
+    var_export($mapEntry->getKey()); // 1    , 2    , 3
+});
+
+```
+
+#### Обход объекта map при помощи цикла _foreach_
+[[↑ Карта (Map)]](#карта-map)
+
+Объект типа Map можно итерировать в цикле *foreach*. В этом случае ключи и значения будут оригинальные. Таким образом ключом может быть любой тип кроме массива.
+
+```php
+
+use \WS\Utils\Collections\HashMap;
+
+$map = new HashMap();
+
+$map->put(new SplObjectStorage(), 1);
+$map->put(null, 2);
+$map->put(false, 3);
+$map->put(true, 4);
+$map->put(0, 5);
+
+foreach($map as $key => $value) {
+    var_export($key);   // object of SplObjectStorage class| null| false| true| 0 
+    var_export($value); // 1                               | 2   | 3    | 4   | 5
+}
+
+```
+
 ## Фабрика создания коллекции
 [[↑ В начало]](#PHP-Коллекции)
 

src/WS/Utils/Collections/HashMap.php

@@ -22,9 +22,25 @@ public function put($key, $value): bool
 
     public function getIterator()
     {
-        return new ArrayIterator(array_map(static function (MapEntry $entry) {
-            return $entry->getValue();
-        }, $this->entries));
+        return new class($this->entries) extends ArrayIterator {
+            private $entries;
+            public function __construct(array $entries)
+            {
+                $hashToValueArray = array_map(static function (MapEntry $entry) {
+                    return $entry->getValue();
+                }, $entries);
+                parent::__construct($hashToValueArray);
+                $this->entries = $entries;
+            }
+
+            public function key()
+            {
+                $arrayKey = parent::key();
+                /** @var MapEntry $entry */
+                $entry = $this->entries[$arrayKey];
+                return $entry->getKey();
+            }
+        };
     }
 
     public function values(): Collection
@@ -120,4 +136,9 @@ public function containsValue($tested): bool
         }
         return false;
     }
+
+    public function stream(): Stream
+    {
+        return new SerialStream(CollectionFactory::from(array_values($this->entries)));
+    }
 }

src/WS/Utils/Collections/Map.php

@@ -47,4 +47,10 @@ public function size(): int;
      * @return mixed|null
      */
     public function get($key);
+
+    /**
+     * Creates a stream with internal collection MapEntry objects
+     * @return Stream Stream<MapEntry>
+     */
+    public function stream(): Stream;
 }

tests/WS/Utils/Collections/HashMapTest.php

@@ -11,7 +11,7 @@ class HashMapTest extends TestCase
 {
     use MapInterfaceTestTrait;
 
-    private function createInstance(): Map
+    protected function createInstance(): Map
     {
         return new HashMap();
     }