Collection > the getByIndex() method > returns element with given index

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Common and useful classes, methods, exceptions etc.
 
+# 0.1.7
+
+1. Collection > create trait (to make it more flexible)
+
 # 0.1.6
 
 1. Arrays > refactoring & more tests

VERSION

@@ -1 +1 @@
-0.1.6
+0.1.7

src/Collection/Collection.php

@@ -9,10 +9,9 @@
 namespace Meritoo\Common\Collection;
 
 use ArrayAccess;
-use ArrayIterator;
 use Countable;
 use IteratorAggregate;
-use Meritoo\Common\Utilities\Arrays;
+use Meritoo\Common\Traits\CollectionTrait;
 
 /**
  * Collection of elements.
@@ -23,12 +22,7 @@ use Meritoo\Common\Utilities\Arrays;
  */
 class Collection implements Countable, ArrayAccess, IteratorAggregate
 {
-    /**
-     * The elements of collection
-     *
-     * @var array
-     */
-    private $elements;
+    use CollectionTrait;
 
     /**
      * Class constructor
@@ -39,247 +33,4 @@ class Collection implements Countable, ArrayAccess, IteratorAggregate
     {
         $this->elements = $elements;
     }
-
-    /**
-     * {@inheritdoc}
-     * Required by interface Countable
-     */
-    public function count()
-    {
-        return count($this->elements);
-    }
-
-    /**
-     * {@inheritdoc}
-     * Required by interface ArrayAccess
-     */
-    public function offsetExists($offset)
-    {
-        return $this->exists($offset);
-    }
-
-    /**
-     * {@inheritdoc}
-     * Required by interface ArrayAccess
-     */
-    public function offsetGet($offset)
-    {
-        if ($this->exists($offset)) {
-            return $this->elements[$offset];
-        }
-
-        return null;
-    }
-
-    /**
-     * {@inheritdoc}
-     * Required by interface ArrayAccess
-     */
-    public function offsetSet($offset, $value)
-    {
-        $this->elements[$offset] = $value;
-    }
-
-    /**
-     * {@inheritdoc}
-     * Required by interface ArrayAccess
-     */
-    public function offsetUnset($offset)
-    {
-        if ($this->exists($offset)) {
-            unset($this->elements[$offset]);
-        }
-    }
-
-    /**
-     * {@inheritdoc}
-     * Required by interface IteratorAggregate
-     */
-    public function getIterator()
-    {
-        return new ArrayIterator($this->elements);
-    }
-
-    /**
-     * Adds given element (at the end of collection)
-     *
-     * @param mixed $element The element to add
-     * @param mixed $index   (optional) Index / key of the element
-     * @return $this
-     */
-    public function add($element, $index = null)
-    {
-        if (null === $index || '' === $index) {
-            $this->elements[] = $element;
-        } else {
-            $this->elements[$index] = $element;
-        }
-
-        return $this;
-    }
-
-    /**
-     * Adds given elements (at the end of collection)
-     *
-     * @param array|Collection $elements   The elements to add
-     * @param bool|false       $useIndexes (optional) If is set to true, indexes of given elements will be used in
-     *                                     this collection. Otherwise - not.
-     * @return $this
-     */
-    public function addMultiple($elements, $useIndexes = false)
-    {
-        if (!empty($elements)) {
-            foreach ($elements as $index => $element) {
-                if ($useIndexes) {
-                    $this->add($element, $index);
-                    continue;
-                }
-
-                $this->add($element);
-            }
-        }
-
-        return $this;
-    }
-
-    /**
-     * Prepends given element (adds given element at the beginning of collection)
-     *
-     * @param mixed $element The element to prepend
-     * @return $this
-     */
-    public function prepend($element)
-    {
-        array_unshift($this->elements, $element);
-
-        return $this;
-    }
-
-    /**
-     * Removes given element
-     *
-     * @param mixed $element The element to remove
-     * @return $this
-     */
-    public function remove($element)
-    {
-        if ($this->count() > 0) {
-            foreach ($this->elements as $index => $existing) {
-                if ($element === $existing) {
-                    unset($this->elements[$index]);
-                    break;
-                }
-            }
-        }
-
-        return $this;
-    }
-
-    /**
-     * Returns information if collection is empty
-     *
-     * @return bool
-     */
-    public function isEmpty()
-    {
-        return empty($this->elements);
-    }
-
-    /**
-     * Returns information if given element is first in the collection
-     *
-     * @param mixed $element The element to verify
-     * @return bool
-     */
-    public function isFirst($element)
-    {
-        return reset($this->elements) === $element;
-    }
-
-    /**
-     * Returns information if given element is last in the collection
-     *
-     * @param mixed $element The element to verify
-     * @return bool
-     */
-    public function isLast($element)
-    {
-        return end($this->elements) === $element;
-    }
-
-    /**
-     * Returns information if the collection has given element, iow. if given element exists in the collection
-     *
-     * @param mixed $element The element to verify
-     * @return bool
-     */
-    public function has($element)
-    {
-        $index = Arrays::getIndexOf($this->elements, $element);
-
-        return null !== $index && false !== $index;
-    }
-
-    /**
-     * Returns previous element for given element
-     *
-     * @param mixed $element The element to verify
-     * @return mixed|null
-     */
-    public function getPrevious($element)
-    {
-        return Arrays::getPreviousElement($this->elements, $element);
-    }
-
-    /**
-     * Returns next element for given element
-     *
-     * @param mixed $element The element to verify
-     * @return mixed|null
-     */
-    public function getNext($element)
-    {
-        return Arrays::getNextElement($this->elements, $element);
-    }
-
-    /**
-     * Returns the first element in the collection
-     *
-     * @return mixed
-     */
-    public function getFirst()
-    {
-        return Arrays::getFirstElement($this->elements);
-    }
-
-    /**
-     * Returns the last element in the collection
-     *
-     * @return mixed
-     */
-    public function getLast()
-    {
-        return Arrays::getLastElement($this->elements);
-    }
-
-    /**
-     * Returns representation of object as array
-     *
-     * @return array
-     */
-    public function toArray()
-    {
-        return $this->elements;
-    }
-
-    /**
-     * Returns information if element with given index/key exists
-     *
-     * @param string|int $index The index/key of element
-     * @return bool
-     */
-    private function exists($index)
-    {
-        return isset($this->elements[$index]) || array_key_exists($index, $this->elements);
-    }
 }

src/Traits/Collection/ArrayAccessTrait.php

@@ -0,0 +1,67 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Meritoo\Common\Traits\Collection;
+
+/**
+ * Trait for the Collection required by ArrayAccess interface
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+trait ArrayAccessTrait
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function offsetExists($offset)
+    {
+        return $this->exists($offset);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function offsetGet($offset)
+    {
+        if ($this->exists($offset)) {
+            return $this->elements[$offset];
+        }
+
+        return null;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function offsetSet($offset, $value)
+    {
+        $this->elements[$offset] = $value;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function offsetUnset($offset)
+    {
+        if ($this->exists($offset)) {
+            unset($this->elements[$offset]);
+        }
+    }
+
+    /**
+     * Returns information if element with given index/key exists
+     *
+     * @param string|int $index The index/key of element
+     * @return bool
+     */
+    private function exists($index)
+    {
+        return isset($this->elements[$index]) || array_key_exists($index, $this->elements);
+    }
+}

src/Traits/Collection/CountableTrait.php

@@ -0,0 +1,26 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Meritoo\Common\Traits\Collection;
+
+/**
+ * Trait for the Collection required by Countable interface
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+trait CountableTrait
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function count()
+    {
+        return count($this->elements);
+    }
+}

src/Traits/Collection/IteratorAggregateTrait.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Meritoo\Common\Traits\Collection;
+
+use ArrayIterator;
+
+/**
+ * Trait for the Collection required by IteratorAggregate interface
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+trait IteratorAggregateTrait
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getIterator()
+    {
+        return new ArrayIterator($this->elements);
+    }
+}

src/Traits/Collection/MainTrait.php

@@ -0,0 +1,215 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Meritoo\Common\Traits\Collection;
+
+use Meritoo\Common\Collection\Collection;
+use Meritoo\Common\Utilities\Arrays;
+
+/**
+ * Main trait for the Collection
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+trait MainTrait
+{
+    /**
+     * The elements of collection
+     *
+     * @var array
+     */
+    private $elements;
+
+    /**
+     * Adds given element (at the end of collection)
+     *
+     * @param mixed $element The element to add
+     * @param mixed $index   (optional) Index / key of the element
+     * @return $this
+     */
+    public function add($element, $index = null)
+    {
+        if (null === $index || '' === $index) {
+            $this->elements[] = $element;
+        } else {
+            $this->elements[$index] = $element;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Adds given elements (at the end of collection)
+     *
+     * @param array|Collection $elements   The elements to add
+     * @param bool|false       $useIndexes (optional) If is set to true, indexes of given elements will be used in
+     *                                     this collection. Otherwise - not.
+     * @return $this
+     */
+    public function addMultiple($elements, $useIndexes = false)
+    {
+        if (!empty($elements)) {
+            foreach ($elements as $index => $element) {
+                if ($useIndexes) {
+                    $this->add($element, $index);
+                    continue;
+                }
+
+                $this->add($element);
+            }
+        }
+
+        return $this;
+    }
+
+    /**
+     * Prepends given element (adds given element at the beginning of collection)
+     *
+     * @param mixed $element The element to prepend
+     * @return $this
+     */
+    public function prepend($element)
+    {
+        array_unshift($this->elements, $element);
+
+        return $this;
+    }
+
+    /**
+     * Removes given element
+     *
+     * @param mixed $element The element to remove
+     * @return $this
+     */
+    public function remove($element)
+    {
+        if ($this->count() > 0) {
+            foreach ($this->elements as $index => $existing) {
+                if ($element === $existing) {
+                    unset($this->elements[$index]);
+                    break;
+                }
+            }
+        }
+
+        return $this;
+    }
+
+    /**
+     * Returns information if collection is empty
+     *
+     * @return bool
+     */
+    public function isEmpty()
+    {
+        return empty($this->elements);
+    }
+
+    /**
+     * Returns information if given element is first in the collection
+     *
+     * @param mixed $element The element to verify
+     * @return bool
+     */
+    public function isFirst($element)
+    {
+        return reset($this->elements) === $element;
+    }
+
+    /**
+     * Returns information if given element is last in the collection
+     *
+     * @param mixed $element The element to verify
+     * @return bool
+     */
+    public function isLast($element)
+    {
+        return end($this->elements) === $element;
+    }
+
+    /**
+     * Returns information if the collection has given element, iow. if given element exists in the collection
+     *
+     * @param mixed $element The element to verify
+     * @return bool
+     */
+    public function has($element)
+    {
+        $index = Arrays::getIndexOf($this->elements, $element);
+
+        return null !== $index && false !== $index;
+    }
+
+    /**
+     * Returns previous element for given element
+     *
+     * @param mixed $element The element to verify
+     * @return mixed|null
+     */
+    public function getPrevious($element)
+    {
+        return Arrays::getPreviousElement($this->elements, $element);
+    }
+
+    /**
+     * Returns next element for given element
+     *
+     * @param mixed $element The element to verify
+     * @return mixed|null
+     */
+    public function getNext($element)
+    {
+        return Arrays::getNextElement($this->elements, $element);
+    }
+
+    /**
+     * Returns the first element in the collection
+     *
+     * @return mixed
+     */
+    public function getFirst()
+    {
+        return Arrays::getFirstElement($this->elements);
+    }
+
+    /**
+     * Returns the last element in the collection
+     *
+     * @return mixed
+     */
+    public function getLast()
+    {
+        return Arrays::getLastElement($this->elements);
+    }
+
+    /**
+     * Returns element with given index
+     *
+     * @param mixed $index Index / key of the element
+     * @return mixed|null
+     */
+    public function getByIndex($index)
+    {
+        if (isset($this->elements[$index])) {
+            return $this->elements[$index];
+        }
+
+        return null;
+    }
+
+    /**
+     * Returns representation of object as array
+     *
+     * @return array
+     */
+    public function toArray()
+    {
+        return $this->elements;
+    }
+}

src/Traits/CollectionTrait.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * (c) Meritoo.pl, http://www.meritoo.pl
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Meritoo\Common\Traits;
+
+use Meritoo\Common\Traits\Collection\ArrayAccessTrait;
+use Meritoo\Common\Traits\Collection\CountableTrait;
+use Meritoo\Common\Traits\Collection\IteratorAggregateTrait;
+use Meritoo\Common\Traits\Collection\MainTrait;
+
+/**
+ * Trait for the Collection
+ *
+ * @author    Meritoo <github@meritoo.pl>
+ * @copyright Meritoo <http://www.meritoo.pl>
+ */
+trait CollectionTrait
+{
+    use MainTrait;
+    use CountableTrait;
+    use ArrayAccessTrait;
+    use IteratorAggregateTrait;
+}

tests/Collection/CollectionTest.php

@@ -327,6 +327,19 @@ class CollectionTest extends BaseTestCase
         static::assertMethodVisibilityAndArguments(Collection::class, 'exists', OopVisibilityType::IS_PRIVATE, 1, 1);
     }
 
+    /**
+     * @param string     $description Description of test
+     * @param Collection $collection  Collection to search for element with given index
+     * @param mixed      $index       Index / key of the element
+     * @param mixed      $expected    Expected element with given index
+     *
+     * @dataProvider provideElementGetByIndex
+     */
+    public function testGetByIndex($description, Collection $collection, $index, $expected)
+    {
+        static::assertEquals($expected, $collection->getByIndex($index), $description);
+    }
+
     /**
      * Provides element to add to collection
      *
@@ -408,6 +421,73 @@ class CollectionTest extends BaseTestCase
         ];
     }
 
+    public function provideElementGetByIndex()
+    {
+        yield[
+            'An empty collection and empty index',
+            new Collection(),
+            '',
+            null,
+        ];
+
+        yield[
+            'An empty collection and non-empty index',
+            new Collection(),
+            'test',
+            null,
+        ];
+
+        yield[
+            'Non-empty collection and not existing index',
+            new Collection([
+                'lorem' => 'ipsum',
+                'dolor' => 'sit',
+            ]),
+            'test',
+            null,
+        ];
+
+        yield[
+            'Collection with existing index',
+            new Collection([
+                'lorem' => 'ipsum',
+                'dolor' => 'sit',
+            ]),
+            'lorem',
+            'ipsum',
+        ];
+
+        yield[
+            'Collection with existing index (collection of arrays)',
+            new Collection([
+                [
+                    'lorem',
+                    'ipsum',
+                ],
+                [
+                    'dolor',
+                    'sit',
+                ],
+            ]),
+            0,
+            [
+                'lorem',
+                'ipsum',
+            ],
+        ];
+
+        yield[
+            'Collection with existing index (collection of objects)',
+            new Collection([
+                'x' => new \DateTime(),
+                'y' => new \DateTime('2001-01-01'),
+                'z' => new \DateTime('yesterday'),
+            ]),
+            'y',
+            new \DateTime('2001-01-01'),
+        ];
+    }
+
     /**
      * {@inheritdoc}
      */