philiprehberger-graph 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e3ace407427d0a54b4279defb1a165c04aa85f1286c2234be016e96a359ad27
-  data.tar.gz: 03d2e98d913ee10c80ed8a2d18f5c896095e568f1e21f57dfb023815c55d8e72
+  metadata.gz: 178b5edb15123981edaaa93532c454677d40753f5ff3729fbe62026c0020f768
+  data.tar.gz: 3446356ba683b0077338dfa55dc052e36546c39d9606e67e0e37ad114368cdfd
 SHA512:
-  metadata.gz: 61b9e62ef38c0993c979f032453f7a142f57079e0c46434265371ad7344e2dbcd8b7a9a32ebf92fa1ce22b5fbd42a1b55895479bdf83e7d6b8bce5c907502575
-  data.tar.gz: 47f5e812b101281eff00b8d0e261caf2473e5f3fc47c5686800fb6a3d5e9c155fbedd67bcadfbe608c2dde0a89b79b8fa0141a350a21e6adf544af441ed49f74
+  metadata.gz: f24fbd86ab0237395a61f5b012091817c4b152b24af2797e7264b2e853177fba4502a234863f1c56c83ecd9adb4bd11f5f0af4d804fae3afdf820a574ae09530
+  data.tar.gz: 16ecb22d98f3a29f2db9d12ae2f08d7ca4e5b03abd0af0c6a348dc2706a6bd4b0bec4e966a05bf662166c857bd6f73c06842c0cd3610caeafeba8454d9e1bf77

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-29
+
+### Added
+- `Graph#total_weight` returning the sum of edge weights across all edges (cheap baseline for MST/flow comparisons)
+
+## [0.4.0] - 2026-04-17
+
+### Added
+- Enumerator-style node iteration (`each_node`)
+- Enumerator-style edge iteration (`each_edge`)
+- Distance-only shortest path query (`shortest_path_distance`)
+- Graph complement operation (`complement`)
+
 ## [0.3.0] - 2026-04-10
 
 ### Added

data/README.md

@@ -139,6 +139,54 @@ g.add_edge(:d, :c)
 g.strongly_connected_components  # => [[:d, :c], [:b, :a]]
 ```
 
+### Iteration
+
+```ruby
+g = Philiprehberger::Graph.new
+g.add_edge(:a, :b)
+g.add_edge(:a, :c)
+
+g.each_node { |id| puts id }
+g.each_edge { |e| puts "#{e[:from]} -> #{e[:to]}" }
+
+# Enumerator chaining
+high_degree = g.each_node.select { |id| g.degree(id) > 1 }
+heavy_edges = g.each_edge.select { |e| e[:weight] > 5 }
+```
+
+### Shortest Path Distance
+
+```ruby
+g = Philiprehberger::Graph.new
+g.add_edge(:a, :b, weight: 1)
+g.add_edge(:b, :c, weight: 2)
+g.add_edge(:a, :c, weight: 10)
+
+g.shortest_path_distance(:a, :c)  # => 3
+```
+
+### Graph Complement
+
+```ruby
+g = Philiprehberger::Graph.new
+g.add_edge(:a, :b)
+g.add_edge(:b, :c)
+
+c = g.complement
+c.edge?(:a, :c)  # => true
+c.edge?(:a, :b)  # => false
+```
+
+### Total Edge Weight
+
+```ruby
+g = Philiprehberger::Graph.new
+g.add_edge(:a, :b, weight: 3)
+g.add_edge(:b, :c, weight: 5)
+
+g.total_weight  # => 8
+```
+
 ### Query Methods
 
 ```ruby
@@ -231,11 +279,15 @@ g2 = Philiprehberger::Graph::Graph.from_json(g.to_json)
 | `#edges` | All edges as hashes |
 | `#node_count` | Number of nodes |
 | `#edge_count` | Number of edges |
+| `#total_weight` | Sum of edge weights across all edges |
 | `#empty?` | Whether the graph has no nodes |
+| `#each_node` | Iterate nodes (yields or returns Enumerator) |
+| `#each_edge` | Iterate edges (yields or returns Enumerator) |
 | `#path?(from, to)` | Check if a path exists |
 | `#bfs(start)` | Breadth-first search |
 | `#dfs(start)` | Depth-first search |
 | `#shortest_path(from, to)` | Dijkstra's shortest path |
+| `#shortest_path_distance(from, to)` | Shortest distance (numeric) |
 | `#topological_sort` | Topological ordering (DAG only) |
 | `#cycle?` | Check for cycles |
 | `#connected_components` | Find connected components |
@@ -249,6 +301,7 @@ g2 = Philiprehberger::Graph::Graph.from_json(g.to_json)
 | `#subgraph(nodes)` | Extract a subgraph |
 | `#transpose` | Reverse all edges (directed) |
 | `#density` | Graph density (0.0 to 1.0) |
+| `#complement` | Graph complement (missing edges) |
 | `#to_dot` | Serialize to DOT format |
 | `#to_json` | Serialize to JSON |
 | `.from_json(str)` | Deserialize from JSON |

data/lib/philiprehberger/graph/graph.rb

@@ -17,6 +17,26 @@ module Philiprehberger
         @directed
       end
 
+      # Iterate over all node ids.
+      #
+      # @yield [Object] each node id
+      # @return [Enumerator] if no block given
+      def each_node(&)
+        return enum_for(:each_node) unless block_given?
+
+        @adjacency.each_key(&)
+      end
+
+      # Iterate over all edges as {from:, to:, weight:} hashes.
+      #
+      # @yield [Hash] each edge
+      # @return [Enumerator] if no block given
+      def each_edge(&)
+        return enum_for(:each_edge) unless block_given?
+
+        edges.each(&)
+      end
+
       # Add a node to the graph.
       #
       # @param id [Object] the node identifier
@@ -157,6 +177,17 @@ module Philiprehberger
         edges.length
       end
 
+      # Sum of weights across all edges. Returns 0 for an empty or edgeless graph.
+      #
+      # For undirected graphs each edge is counted once.
+      #
+      # @return [Numeric]
+      def total_weight
+        total = 0
+        each_edge { |edge| total += edge[:weight] }
+        total
+      end
+
       # Whether the graph has no nodes.
       #
       # @return [Boolean]
@@ -254,6 +285,36 @@ module Philiprehberger
         nil
       end
 
+      # Find the shortest distance between two nodes using Dijkstra's algorithm.
+      #
+      # @param from [Object] source node
+      # @param to [Object] destination node
+      # @return [Numeric, nil] the shortest distance, or nil if no path exists
+      def shortest_path_distance(from, to)
+        return nil unless @adjacency.key?(from) && @adjacency.key?(to)
+        return 0 if from == to
+
+        distances = Hash.new(Float::INFINITY)
+        distances[from] = 0
+        unvisited = @adjacency.keys.dup
+
+        until unvisited.empty?
+          current = unvisited.min_by { |n| distances[n] }
+          break if distances[current] == Float::INFINITY
+
+          unvisited.delete(current)
+
+          return distances[to] if current == to
+
+          (@adjacency[current] || []).each do |edge|
+            alt = distances[current] + edge[:weight]
+            distances[edge[:node]] = alt if alt < distances[edge[:node]]
+          end
+        end
+
+        nil
+      end
+
       # Topological sort (directed acyclic graphs only).
       #
       # @return [Array<Object>] nodes in topological order
@@ -365,6 +426,29 @@ module Philiprehberger
         m / max_edges
       end
 
+      # Return the complement graph.
+      # The complement contains edges between all pairs of nodes that are NOT connected
+      # in the original graph.
+      #
+      # @return [Graph] a new graph with complementary edges
+      def complement
+        g = self.class.new(directed: @directed)
+        @adjacency.each_key { |id| g.add_node(id) }
+
+        node_list = @adjacency.keys
+        node_list.each_with_index do |a, i|
+          targets = @directed ? node_list : node_list[(i + 1)..]
+          targets.each do |b|
+            next if a == b
+            next if edge?(a, b)
+
+            g.add_edge(a, b)
+          end
+        end
+
+        g
+      end
+
       # Find connected components (undirected) or weakly connected components (directed).
       #
       # @return [Array<Array<Object>>] arrays of node ids per component

data/lib/philiprehberger/graph/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module Graph
-    VERSION = '0.3.0'
+    VERSION = '0.5.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-graph
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-11 00:00:00.000000000 Z
+date: 2026-04-29 00:00:00.000000000 Z
 dependencies: []
 description: Graph data structure supporting directed and undirected modes with adjacency
   list storage. Includes BFS, DFS, Dijkstra shortest path, topological sort, cycle