stream method for maps

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,31 @@ $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)

doc/README.ru.md

@@ -593,6 +593,7 @@ $queue->peek(); // RuntimeException
 - [*containsKey* – Признак наличия пары по ключу](#containskey---признак-наличия-пары-по-ключу)
 - [*containsValue* – Признак наличия пары по значению](#containsvalue---признак-наличия-пары-по-значению)
 - [*size* – Количество пар в карте](#size---количество-пар-в-карте)
+- [*stream* – Получение потока обхода коллекции пар ключ/значение (Stream)](#stream---получение-потока-обхода-коллекции-пар-ключ-значение-stream)
 - [Обход объекта map при помощи цикла _foreach_](#обход-объекта-map-при-помощи-цикла-_foreach_)
 
 #### _put_ - Добавление пары *ключ/значение*
@@ -762,6 +763,32 @@ $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)
 

src/WS/Utils/Collections/HashMap.php

@@ -136,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/MapInterfaceTestTrait.php

@@ -250,4 +250,26 @@ public function foreachAnyKeyValueChecking(): void
             }
         }
     }
+
+    /**
+     * @test
+     */
+    public function streamGetting(): void
+    {
+        $map = $this->createInstance();
+
+        $map->put('1', 1);
+        $map->put('2', 2);
+        $map->put('3', 3);
+
+        $stream = $map->stream();
+        self::assertThat($stream, self::isInstanceOf(Stream::class));
+
+        self::assertGreaterThan(0, $stream->getCollection()->size());
+
+        $stream
+            ->each(static function (MapEntry $mapEntry) {
+                self::assertThat($mapEntry->getKey() === ''.$mapEntry->getValue(), self::isTrue());
+            });
+    }
 }