Improve Graph::createVertices() to return vertices and accept array of vertex IDs

CHANGELOG.md

@@ -4,6 +4,11 @@ This file is a manually maintained list of changes for each release. Feel free
 to add your changes here when sending pull requests. Also send corrections if
 you spot any mistakes.
 
+## 0.6.0 (2013-xx-xx)
+
+* BC break: `Graph::createVertices()` now returns an array of vertices instead of the chainable `Graph` (#19)
+* Feature: `Graph::createVertices()` now also accepts an array of vertex IDs (#19)
+
 ## 0.5.0 (2013-05-07)
 
 * First tagged release (See issue #20 for more info on why it starts as v0.5.0)

lib/Fhaculty/Graph/Graph.php

@@ -215,19 +215,43 @@ private function createEdgeCloneInternal(Edge $originalEdge, $ia, $ib)
     }
 
     /**
-     * create the given number of vertices
+     * create the given number of vertices or given array of Vertex IDs
      *
-     * @param  int   $n
-     * @return Graph (chainable)
+     * @param  int|array $n number of vertices to create or array of Vertex IDs to create
+     * @return Vertex[]  array of vertices created
      * @uses Graph::getNextId()
      */
     public function createVertices($n)
     {
-        for ($id = $this->getNextId(), $n += $id; $id < $n; ++$id) {
-            $this->vertices[$id] = new Vertex($id, $this);
+        $vertices = array();
+        if (is_int($n) && $n >= 0) {
+            for ($id = $this->getNextId(), $n += $id; $id < $n; ++$id) {
+                $vertices[$id] = $this->vertices[$id] = new Vertex($id, $this);
+            }
+        } elseif (is_array($n)) {
+            // array given => check to make sure all given IDs are available (atomic operation)
+            foreach ($n as $id) {
+                if (!is_int($id) && !is_string($id)) {
+                    throw new InvalidArgumentException('All Vertex IDs have to be of type integer or string');
+                } elseif (isset($this->vertices[$id])) {
+                    throw new OverflowException('Given array of Vertex IDs contains an ID that already exists. Given IDs must be unique');
+                } elseif (isset($vertices[$id])) {
+                    throw new InvalidArgumentException('Given array of Vertex IDs contain duplicate IDs. Given IDs must be unique');
+                }
+
+                // temporary marker to check for duplicate IDs in the array
+                $vertices[$id] = false;
+            }
+
+            // actually create all requested vertices
+            foreach ($n as $id) {
+                $vertices[$id] = $this->vertices[$id] = new Vertex($id, $this);
+            }
+        } else {
+            throw new InvalidArgumentException('Invalid number of vertices given. Must be non-negative integer or an array of Vertex IDs');
         }
 
-        return $this;
+        return $vertices;
     }
 
     /**

tests/Fhaculty/Graph/GraphTest.php

@@ -4,6 +4,7 @@
 use Fhaculty\Graph\Exporter\Image;
 use Fhaculty\Graph\Vertex;
 use Fhaculty\Graph\Exception\OverflowException;
+use Fhaculty\Graph\Exception\InvalidArgumentException;
 use Fhaculty\Graph\Graph;
 
 class GraphTest extends TestCase
@@ -178,4 +179,78 @@ public function testCreateMixedGraph()
         $this->assertEquals(array(1, 3), array_keys($v2->getVerticesEdgeTo()));
         $this->assertEquals(array(1), array_keys($v2->getVerticesEdgeFrom()));
     }
+
+    public function testCreateVerticesNone()
+    {
+        $graph = new Graph();
+
+        $this->assertEquals(array(), $graph->createVertices(0));
+        $this->assertEquals(array(), $graph->createVertices(array()));
+
+        $this->assertEquals(0, $graph->getNumberOfVertices());
+    }
+
+    /**
+     * expect to fail for invalid number of vertices
+     * @expectedException InvalidArgumentException
+     * @dataProvider testCreateVerticesFailProvider
+     */
+    public function testCreateVerticesFail($number)
+    {
+        $graph = new Graph();
+        $graph->createVertices($number);
+    }
+
+    public static function testCreateVerticesFailProvider()
+    {
+        return array(
+            array(-1),
+            array("10"),
+            array(0.5),
+            array(null),
+            array(array(1, 1))
+        );
+    }
+
+    public function testCreateVerticesOkay()
+    {
+        $graph = new Graph();
+
+        $vertices = $graph->createVertices(2);
+        $this->assertCount(2, $vertices);
+        $this->assertEquals(array(0, 1), array_keys($graph->getVertices()));
+
+        $vertices = $graph->createVertices(array(7, 9));
+        $this->assertCount(2, $vertices);
+        $this->assertEquals(array(0, 1, 7, 9), array_keys($graph->getVertices()));
+
+        $vertices = $graph->createVertices(3);
+        $this->assertCount(3, $vertices);
+        $this->assertEquals(array(0, 1, 7, 9, 10, 11, 12), array_keys($graph->getVertices()));
+    }
+
+    public function testCreateVerticesAtomic()
+    {
+        $graph = new Graph();
+
+        // create vertices 10-19 (inclusive)
+        $vertices = $graph->createVertices(range(10, 19));
+        $this->assertCount(10, $vertices);
+
+        try {
+            $graph->createVertices(array(9, 19, 20));
+            $this->fail('Should be unable to create vertices because of duplicate IDs');
+        }
+        catch (OverflowException $ignoreExpected) {
+            $this->assertEquals(10, $graph->getNumberOfVertices());
+        }
+
+        try {
+            $graph->createVertices(array(20, 21, 21));
+            $this->fail('Should be unable to create vertices because of duplicate IDs');
+        }
+        catch (InvalidArgumentException $ignoreExpected) {
+            $this->assertEquals(10, $graph->getNumberOfVertices());
+        }
+    }
 }