From 9457beb4df560e4aebdc91fbbd05de05278b7c07 Mon Sep 17 00:00:00 2001
From: dantleech <dan.t.leech@gmail.com>
Date: Sat, 27 Jun 2015 10:17:46 +0200
Subject: [PATCH] Updated README

---
 CHANGELOG.md                  |  2 ++
 README.md                     | 11 +++++--
 lib/Collection.php            | 50 ++++++++++++++++++++++++++++++
 tests/Unit/CollectionTest.php | 58 +++++++++++++++++++++++++++++++++++
 4 files changed, 119 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ff9cb71..1d3de81 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,8 @@
 CHANGELOG
 =========
 
+- Added `materialize`, `replace`, and `compact` functions to `Collection`.
+
 0.3
 ---
 
diff --git a/README.md b/README.md
index 2f939d9..3a78076 100644
--- a/README.md
+++ b/README.md
@@ -109,14 +109,16 @@ Current functions:
 - `median`: Return the median value
 - `deviation`: Return the deviation as a percentage
 
-Partitioning and Forking
-------------------------
+Partitioning, Aggregation, and Materialization
+----------------------------------------------
 
 `Table` and `Row` instances provide the following methods:
 
 - `partition`: Internally divide the collection of elements according to a
   given callback.
 - `aggregate`: Aggregate the partitions of a table back to a single partition.
+- `materialize`: Materialize partitions of constituent Cellular instances into
+  Cellular instances.
 
 This is useful for creating summaries from multiple tables or rows:
 
@@ -143,6 +145,11 @@ partition for the collection upon which the operation is performed.
 
 The result will be anagous to the following SQL: `SELECT SUM(number) FROM table GROUP BY class`.
 
+Compacting
+----------
+
+TODO
+
 Sorting
 -------
 
diff --git a/lib/Collection.php b/lib/Collection.php
index 99542f5..fe8232c 100644
--- a/lib/Collection.php
+++ b/lib/Collection.php
@@ -236,6 +236,56 @@ public function partition(\Closure $closure)
         return $this;
     }
 
+    /**
+     * Materialize each partition of the child cellular instances
+     * into a concrete instance.
+     *
+     * @return Collection
+     */
+    public function materialize()
+    {
+        $cells = array();
+        foreach ($this as $cell) {
+            foreach ($cell->getPartitions() as $partition) {
+                $cells[] = $cell->create($partition->getElements());
+            }
+        }
+        $this->replace($cells);
+        return $this;
+    }
+
+    /**
+     * Aggregate all cells into a single cell.
+     *
+     * @return Collection
+     */
+    public function compact()
+    {
+        $newCell = null;
+        foreach ($this as $cell) {
+            if (null === $newCell) {
+                $newCell = $cell->create();
+            }
+
+            foreach ($cell as $element) {
+                $newCell[] = $element;
+            }
+        }
+
+        $this->replace(array($newCell));
+    }
+
+    /**
+     * Replace the elements in the collection
+     *
+     * @param array $elements
+     * @return Collection
+     */
+    public function replace($elements)
+    {
+        $this->partitions = array(new Partition($elements));
+    }
+
     /**
      * Aggregate the partions back to a single partition using
      * the given closure.
diff --git a/tests/Unit/CollectionTest.php b/tests/Unit/CollectionTest.php
index 2e5c976..b248fec 100644
--- a/tests/Unit/CollectionTest.php
+++ b/tests/Unit/CollectionTest.php
@@ -117,6 +117,36 @@ public function testPartition()
             ),
             array_values($partitions[1]->getElements())
         );
+
+        return $this->collection;
+    }
+
+    /**
+     * It should marerialize partitions of its consituent cellulars
+     *
+     * @depends testPartition
+     */
+    public function testMaterialize($collection)
+    {
+        $collection = new Collection(array($collection));
+        $this->assertCount(1, $collection);
+        $collection->materialize();
+        $this->assertCount(2, $collection);
+
+        $this->assertEquals(
+            array(
+                array('a', 'b'),
+                array('a', 'a'),
+            ),
+            $collection[0]->getElements()
+        );
+        $this->assertEquals(
+            array(
+                array('b', 'a'),
+                array('b', 'a'),
+            ),
+            array_values($collection[1]->getElements())
+        );
     }
 
     /**
@@ -150,6 +180,20 @@ public function testApply()
         );
     }
 
+    /**
+     * It should replace the elements in the collection
+     */
+    public function testReplace()
+    {
+        $collection = new Collection(array(1, 2), array(3, 4));
+        $collection->replace(array(100, 200, 300));
+
+        $this->assertEquals(
+            array(100, 200, 300),
+            $collection->getElements()
+        );
+    }
+
     /**
      * It should map a closure to each element.
      */
@@ -317,4 +361,18 @@ public function testCopyWithObject()
         $this->assertCount(2, $elements);
         $this->assertNotSame($elements[0], $object1);
     }
+
+    /**
+     * It should compact its constituent elements into a single element
+     */
+    public function testCompact()
+    {
+        $this->collection[] = new Collection(array('a', 'b'));
+        $this->collection[] = new Collection(array('c', 'd'));
+        $this->collection->compact();
+        $this->assertCount(1, $this->collection);
+        $this->assertEquals(array(
+            'a', 'b', 'c', 'd',
+        ), $this->collection->first()->getElements());
+    }
 }