Merge branch 'add-vertices-class' (closes PR #48)

Conflicts:
	CHANGELOG.md

Author: clue

CHANGELOG.md

@@ -6,6 +6,41 @@ you spot any mistakes.
 
 ## 0.7.0 (2013-xx-xx)
 
+*   Feature: Add new `Set\Vertices` and `Set\Edges` classes that handle common
+    operations on a Set of multiple `Vertex` and `Edge` instances respectively.
+    ([#48](https://github.com/clue/graph/issues/48))
+
+*   BC break: Move operations and their corresponding constants concerning Sets
+    to their corresponding Sets:
+
+    | Old name | New name |
+    |---|---|
+    | `Edge\Base::getFirst()` | `Set\Edges::getEdgeOrder()` |
+    | `Edge\Base::getAll()` | `Set\Edges::getEdgesOrder()` |
+    | `Edge\Base::ORDER_*` | `Set\Edges::ORDER_* |
+    |---|---|
+    | `Vertex::getFirst()` | `Set\Vertices::getVertexOrder()` |
+    | `Vertex::getAll()` | `Set\Vertices::getVerticesOrder()` |
+    | `Vertex::ORDER_` | `Set\Vertices::ORDER_*` |
+
+*   BC break: Each `getVertices*()` and `getEdges*()` method now returns a `Set`
+    instead of a primitive array of instances. *Most* of the time this should
+    work without changing your code, because each `Set` implements an `Iterator`
+    interface and can easily be iterated using `foreach`. However, using a `Set`
+    instead of a plain array differs when checking its boolean value or
+    comparing two Sets. I.e. if you happen to want to check if an `Set` is empty,
+    you now have to use the more explicit syntax `$set->isEmpty()`.
+    
+*   BC break: `Vertex::getVertices()`, `Vertex::getVerticesEdgeTo()` and
+    `Vertex::getVerticesEdgeFrom()` now return a `Set\Vertices` instance that
+    may contain duplicate vertices if parallel (multiple) edges exist. Previously
+    there was no easy way to detect this situation - this is now the default. If
+    you also want to get unique / distinct `Vertex` instances, use
+    `Vertex::getVertices()->getVerticesDistinct()` where applicable.
+
+*   BC break: Remove all occurances of `getVerticesId()`, use
+    `getVertices()->getIds()` instead.
+
 * BC break: Merge `Cycle` into `Walk` ([#61](https://github.com/clue/graph/issues/61)).
 As such, its static factory methods had to be renamed. Update your references if applicable:
 
@@ -15,6 +50,12 @@ As such, its static factory methods had to be renamed. Update your references if
 | `Cycle::factoryFromVertices()` | `Walk::factoryCycleFromVertices()` |
 | `Cycle::factoryFromEdges()` | `Walk::factoryCycleFromEdges()` |
 
+* BC break: Remove `Graph::isEmpty()` because it's not well-defined and might
+be confusing. Most literature suggests it should check for existing edges,
+whereas the old behavior was to check for existing vertices instead. Use either
+of the more transparent methods
+`Algorithm\Property\GraphProperty::isNull()` (old behavior) or (where applicable)
+`Algorithm\Property\GraphProperty::isEmpty()` ([#59](https://github.com/clue/graph/issues/59)).
 * BC break: Each of the above methods (`Walk::factoryCycleFromPredecessorMap()`,
 `Walk::factoryCycleFromVertices()`, `Walk::factoryCycleFromEdges()`) now
 actually makes sure the returned `Walk` instance is actually a valid Cycle,
@@ -28,6 +69,7 @@ Vertex ([#62](https://github.com/clue/graph/issues/62))
 * Feature: Add `Algorithm\ShortestPath::hasVertex(Vertex $vertex)` to check whether
 a path to the given Vertex exists ([#62](https://github.com/clue/graph/issues/62)).
 * Feature: Support opening GraphViz images on Mac OS X in default image viewer ([#67](https://github.com/clue/graph/issues/67) @onigoetz)
+* Feature: Add `Walk::factoryFromVertices()` ([#64](https://github.com/clue/graph/issues/64)).
 * Fix: Checking `Walk::isValid()` ([#61](https://github.com/clue/graph/issues/61))
 * Fix: Missing import prevented
 `Algorithm\ShortestPath\MooreBellmanFord::getCycleNegative()` from actually

lib/Fhaculty/Graph/Algorithm/Bipartit.php

@@ -51,7 +51,7 @@ public function getColors()
         $colors = array();
 
         // get color for each vertex
-        foreach ($this->graph->getVertices() as $vid => $startVertex) {
+        foreach ($this->graph->getVertices()->getMap() as $vid => $startVertex) {
             if (!isset($colors[$vid])) {
                 $queue = array($startVertex);
                 // initialize each components color
@@ -65,7 +65,7 @@ public function getColors()
                     $nextColor = 1-$color;
 
                     // scan all vertices connected to this vertex
-                    foreach ($vertex->getVerticesEdge() as $vid => $nextVertex) {
+                    foreach ($vertex->getVerticesEdge()->getMap() as $vid => $nextVertex) {
                         // color unknown, so expect next color for this vertex
                         if (!isset($colors[$vid])) {
                             $colors[$vid] = $nextColor;
@@ -92,7 +92,7 @@ public function getColorVertices()
         $colors = $this->getColors();
         $ret = array(0 => array(), 1 => array());
 
-        foreach ($this->graph->getVertices() as $vid => $vertex) {
+        foreach ($this->graph->getVertices()->getMap() as $vid => $vertex) {
             $ret[$colors[$vid]][$vid] = $vertex;
         }
 
@@ -113,7 +113,7 @@ public function createGraphGroups()
         $colors = $this->getColors();
 
         $graph = $this->graph->createGraphClone();
-        foreach ($graph->getVertices() as $vid => $vertex) {
+        foreach ($graph->getVertices()->getMap() as $vid => $vertex) {
             $vertex->setGroup($colors[$vid]);
         }
 

lib/Fhaculty/Graph/Algorithm/Complete.php

@@ -26,7 +26,7 @@ class Complete extends BaseGraph
     public function isComplete()
     {
         // copy of array (separate iterator but same vertices)
-        $c = $vertices = $this->graph->getVertices();
+        $c = $vertices = $this->graph->getVertices()->getVector();
         // from each vertex
         foreach ($vertices as $vertex) {
             // to each vertex

lib/Fhaculty/Graph/Algorithm/ConnectedComponents.php

@@ -24,7 +24,7 @@ class ConnectedComponents extends BaseGraph
      * @param  Vertex                   $vertex
      * @return Graph
      * @throws InvalidArgumentException if given vertex is not from same graph
-     * @uses AlgorithmSearchBreadthFirst::getVerticesIds()
+     * @uses AlgorithmSearchBreadthFirst::getVertices()
      * @uses Graph::createGraphCloneVertices()
      */
     public function createGraphComponentVertex(Vertex $vertex)
@@ -36,6 +36,11 @@ public function createGraphComponentVertex(Vertex $vertex)
         return $this->graph->createGraphCloneVertices($this->createSearch($vertex)->getVertices());
     }
 
+    /**
+     *
+     * @param Vertex $vertex
+     * @return SearchBreadthFirst
+     */
     private function createSearch(Vertex $vertex)
     {
         $alg = new SearchBreadthFirst($vertex);
@@ -84,20 +89,20 @@ public function isSingle()
      *
      * @return int number of components
      * @uses Graph::getVertices()
-     * @uses AlgorithmSearchBreadthFirst::getVerticesIds()
+     * @uses AlgorithmSearchBreadthFirst::getVertices()
      */
     public function getNumberOfComponents()
     {
         $visitedVertices = array();
         $components = 0;
 
         // for each vertices
-        foreach ($this->graph->getVertices() as $vid => $vertex) {
+        foreach ($this->graph->getVertices()->getMap() as $vid => $vertex) {
             // did I visit this vertex before?
             if (!isset($visitedVertices[$vid])) {
 
                 // get all vertices of this component
-                $newVertices = $this->createSearch($vertex)->getVerticesIds();
+                $newVertices = $this->createSearch($vertex)->getVertices()->getIds();
 
                 ++$components;
 
@@ -125,7 +130,7 @@ public function createGraphsComponents()
         $graphs = array();
 
         // for each vertices
-        foreach ($this->graph->getVertices() as $vid => $vertex) {
+        foreach ($this->graph->getVertices()->getMap() as $vid => $vertex) {
             // did I visit this vertex before?
             if (!isset($visitedVertices[$vid])) {
 
@@ -134,7 +139,7 @@ public function createGraphsComponents()
                 $newVertices = $alg->getVertices();
 
                 // mark the vertices of this component as visited
-                foreach ($newVertices as $vid => $unusedVertex) {
+                foreach ($newVertices->getIds() as $vid) {
                     $visitedVertices[$vid] = true;
                 }
 

lib/Fhaculty/Graph/Algorithm/Degree.php

@@ -6,6 +6,7 @@
 use Fhaculty\Graph\Graph;
 use Fhaculty\Graph\Vertex;
 use Fhaculty\Graph\Exception\UnexpectedValueException;
+use Fhaculty\Graph\Set\Vertices;
 
 /**
  * Basic algorithms for working with the degrees of Graphs.
@@ -49,25 +50,25 @@ public function getDegree()
      *
      * @return int
      * @throws Exception if graph is empty or directed
-     * @uses Vertex::getFirst()
+     * @uses Vertices::getVertexOrder()
      * @uses self::getDegreeVertex()
      */
     public function getDegreeMin()
     {
-        return $this->getDegreeVertex(Vertex::getFirst($this->graph->getVertices(), Vertex::ORDER_DEGREE));
+        return $this->getDegreeVertex($this->graph->getVertices()->getVertexOrder(Vertices::ORDER_DEGREE));
     }
 
     /**
      * get maximum degree of vertices
      *
      * @return int
      * @throws Exception if graph is empty or directed
-     * @uses Vertex::getFirst()
+     * @uses Vertices::getVertexOrder()
      * @uses self::getDegreeVertex()
      */
     public function getDegreeMax()
     {
-        return $this->getDegreeVertex(Vertex::getFirst($this->graph->getVertices(), Vertex::ORDER_DEGREE, true));
+        return $this->getDegreeVertex($this->graph->getVertices()->getVertexOrder(Vertices::ORDER_DEGREE, true));
     }
 
     /**
@@ -79,7 +80,7 @@ public function getDegreeMax()
     public function isRegular()
     {
         // an empty graph is considered regular
-        if ($this->graph->isEmpty()) {
+        if ($this->graph->getVertices()->isEmpty()) {
             return true;
         }
         try {
@@ -174,7 +175,7 @@ public function getDegreeVertex(Vertex $vertex)
      */
     public function isVertexIsolated(Vertex $vertex)
     {
-        return !$vertex->getEdges();
+        return $vertex->getEdges()->isEmpty();
     }
 
     /**

lib/Fhaculty/Graph/Algorithm/DetectNegativeCycle.php

@@ -37,22 +37,22 @@ public function hasCycleNegative()
      *
      * @return Walk
      * @throws UnderflowException if there's no negative cycle
-     * @uses AlgorithmSpMooreBellmanFord::getVerticesId()
+     * @uses AlgorithmSpMooreBellmanFord::getVertices()
      */
     public function getCycleNegative()
     {
         // remember vertices already visited, as they can not lead to a new cycle
         $verticesVisited = array();
         // check for all vertices
-        foreach ($this->graph->getVertices() as $vid => $vertex) {
+        foreach ($this->graph->getVertices()->getMap() as $vid => $vertex) {
             // skip vertices already visited
             if (!isset($verticesVisited[$vid])) {
                 // start MBF algorithm on current vertex
                 $alg = new SpMooreBellmanFord($vertex);
 
                 try {
                     // try to get all connected vertices (or throw new cycle)
-                    foreach ($alg->getVerticesId() as $vid) {
+                    foreach ($alg->getVertices()->getIds() as $vid) {
                         // getting connected vertices succeeded, so skip over all of them
                         $verticesVisited[$vid] = true;
                     // no cycle found, check next vertex...

lib/Fhaculty/Graph/Algorithm/Groups.php

@@ -4,6 +4,7 @@
 
 use Fhaculty\Graph\Algorithm\BaseGraph;
 use Fhaculty\Graph\Graph;
+use Fhaculty\Graph\Set\Vertices;
 
 class Groups extends BaseGraph
 {
@@ -66,21 +67,21 @@ public function getGroups()
     }
 
     /**
-     * get array of all vertices in the given group
+     * get set of all Vertices in the given group
      *
      * @param  int      $group
-     * @return Vertex[]
+     * @return Vertices
      * @uses Vertex::getGroup()
      */
     public function getVerticesGroup($group)
     {
         $vertices = array();
-        foreach ($this->graph->getVertices() as $vid => $vertex) {
+        foreach ($this->graph->getVertices()->getMap() as $vid => $vertex) {
             if ($vertex->getGroup() === $group) {
                 $vertices[$vid] = $vertex;
             }
         }
 
-        return $vertices;
+        return new Vertices($vertices);
     }
 }

lib/Fhaculty/Graph/Algorithm/MaxFlow/EdmondsKarp.php

@@ -17,6 +17,7 @@
 use Fhaculty\Graph\Graph;
 use Fhaculty\Graph\Vertex;
 use Fhaculty\Graph\Edge\Base as Edge;
+use Fhaculty\Graph\Set\Edges;
 use Fhaculty\Graph\Algorithm\Base;
 use Fhaculty\Graph\Algorithm\ResidualGraph;
 use Fhaculty\Graph\Exception;
@@ -86,7 +87,7 @@ public function createGraph()
             // If path exists add the new flow to graph
             if ($pathFlow) {
                 // 2. get max flow from path
-                $maxFlowValue = Edge::getFirst($pathFlow->getEdges(), Edge::ORDER_CAPACITY)->getCapacity();
+                $maxFlowValue = $pathFlow->getEdges()->getEdgeOrder(Edges::ORDER_CAPACITY)->getCapacity();
 
                 // 3. add flow to path
                 foreach ($pathFlow->getEdges() as $edge) {

lib/Fhaculty/Graph/Algorithm/MaximumMatching/Base.php

@@ -5,6 +5,7 @@
 use Fhaculty\Graph\Algorithm\BaseGraph;
 use Fhaculty\Graph\Graph;
 use Fhaculty\Graph\Edge\Base as Edge;
+use Fhaculty\Graph\Set\Edges;
 
 abstract class Base extends BaseGraph
 {
@@ -35,7 +36,7 @@ public function createGraph()
     /**
      * create new resulting graph with minimum-cost flow on edges
      *
-     * @return Edge[]
+     * @return Edges
      */
     abstract public function getEdges();
 }

lib/Fhaculty/Graph/Algorithm/MaximumMatching/Flow.php

@@ -11,6 +11,7 @@
 use Fhaculty\Graph\Algorithm\MaxFlow\EdmondsKarp as MaxFlowEdmondsKarp;
 use Fhaculty\Graph\Algorithm\Groups;
 use Fhaculty\Graph\Exception;
+use Fhaculty\Graph\Set\Edges;
 
 class Flow extends Base
 {
@@ -29,11 +30,6 @@ public function getEdges()
         // create temporary flow graph with supersource and supersink
         $graphFlow = $this->graph->createGraphCloneEdgeless();
 
-        // get all vertices
-        $vertices = $graphFlow->getVertices();
-        // above $vertices does NOT contain supersource and supersink, because
-        // we want to skip over them as they do not have a partition assigned
-
         $superSource = $graphFlow->createVertex()->setLayoutAttribute('label', 's*');
         $superSink   = $graphFlow->createVertex()->setLayoutAttribute('label', 't*');
 
@@ -42,7 +38,10 @@ public function getEdges()
         $groupB = $groups[1];
 
         // connect supersource s* to set A and supersink t* to set B
-        foreach ($vertices as $vertex) {
+        foreach ($graphFlow->getVertices() as $vertex) {
+            // we want to skip over supersource & supersink as they do not have a partition assigned
+            if ($vertex === $superSource || $vertex === $superSink) continue;
+
             $group = $vertex->getGroup();
 
             // source
@@ -83,6 +82,6 @@ public function getEdges()
             }
         }
 
-        return $returnEdges;
+        return new Edges($returnEdges);
     }
 }