philiprehberger-graph 0.2.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ea79730e427e091bf405d36a868055b567b90218a8227d8d59eabde37bc04c4
-  data.tar.gz: a57a435c08e6a966b227234216997ab886e13a0cf28a7666d2ad9bcd0eb8057c
+  metadata.gz: 73596f486ec100249fa2df0e4a9ef6aa1bdcd5e37e16b9b587dd6802f3fc9584
+  data.tar.gz: 0ddc969e510fb5543d9b981d53f73c15b53e73066defb0b7226998c79ef7ec15
 SHA512:
-  metadata.gz: 80f68b85ca03998c51dada82ca2e82fb059ab75ca00fb0ef12c0b45f0cab7f666183ec510a9d3857210c7d955f05f86a513a3adc3750bee8771a05299c681628
-  data.tar.gz: 97a78d205f80b0bf95f803da97dbbad1d735486fa12af3f78aa4eb98dc39d89a49609a570d7fd5be87d4e3114447c928223d8207a37efbd4b2f557a0d89c4167
+  metadata.gz: 4cffa4c6398bfa251b9b8f82704d883d36e4c2dc7f1296369ff073364b8a71d0256a8f75b056d78372a38ca99809e8a09c560d549da4b8b8efa38ccf35130811
+  data.tar.gz: 80ca432cc5c0b1b35c979ccfebb1e7409d9170687a99ae9f4336e5159ce72a8d063cd5c8f7cc4829a4e22d9bad34c8d329e4fb8e8d3a3a668876994455ac628d

data/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Node and edge existence checks (`node?`, `edge?`)
+- Edge weight retrieval (`weight`)
+- Graph size queries (`node_count`, `edge_count`, `empty?`)
+- Directed graph degree decomposition (`in_degree`, `out_degree`)
+- Path existence check (`path?`)
+- Subgraph extraction (`subgraph`)
+- Graph transpose (`transpose`)
+- Graph density calculation (`density`)
+
+### Changed
+- Update gemspec description to reflect full feature set
+- Add missing fields to GitHub issue templates
+
 ## [0.2.4] - 2026-04-08
 
 ### Changed

data/README.md

@@ -139,6 +139,101 @@ 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
+```
+
+### Query Methods
+
+```ruby
+g = Philiprehberger::Graph.new
+g.add_edge(:a, :b, weight: 3)
+g.add_edge(:b, :c)
+g.add_node(:d)
+
+g.node?(:a)       # => true
+g.edge?(:a, :b)   # => true
+g.weight(:a, :b)  # => 3
+g.node_count       # => 4
+g.edge_count       # => 2
+g.empty?           # => false
+g.path?(:a, :c)   # => true
+g.path?(:a, :d)   # => false
+g.density          # => 0.333...
+```
+
+### Directed Degree
+
+```ruby
+g = Philiprehberger::Graph.new(directed: true)
+g.add_edge(:a, :b)
+g.add_edge(:a, :c)
+g.add_edge(:b, :c)
+
+g.in_degree(:c)   # => 2
+g.out_degree(:a)  # => 2
+```
+
+### Subgraph
+
+```ruby
+g = Philiprehberger::Graph.new
+g.add_edge(:a, :b)
+g.add_edge(:b, :c)
+g.add_edge(:c, :d)
+
+sg = g.subgraph([:a, :b, :c])
+sg.nodes  # => [:a, :b, :c]
+sg.edge?(:a, :b)  # => true
+sg.node?(:d)      # => false
+```
+
+### Transpose
+
+```ruby
+g = Philiprehberger::Graph.new(directed: true)
+g.add_edge(:a, :b)
+g.add_edge(:b, :c)
+
+t = g.transpose
+t.edge?(:b, :a)  # => true
+t.edge?(:c, :b)  # => true
+```
+
 ### Serialization
 
 ```ruby
@@ -163,13 +258,25 @@ g2 = Philiprehberger::Graph::Graph.from_json(g.to_json)
 | `#add_edge(from, to, weight:)` | Add a weighted edge |
 | `#remove_node(id)` | Remove a node and its edges |
 | `#remove_edge(from, to)` | Remove an edge |
+| `#node?(id)` | Check if a node exists |
+| `#edge?(from, to)` | Check if an edge exists |
+| `#weight(from, to)` | Get edge weight (nil if none) |
 | `#neighbors(node)` | Get neighbor node ids |
 | `#degree(node)` | Number of edges on a node |
+| `#in_degree(node)` | Incoming edges (directed) |
+| `#out_degree(node)` | Outgoing edges (directed) |
 | `#nodes` | All node ids |
 | `#edges` | All edges as hashes |
+| `#node_count` | Number of nodes |
+| `#edge_count` | Number of 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 |
@@ -180,6 +287,10 @@ g2 = Philiprehberger::Graph::Graph.from_json(g.to_json)
 | `#bipartite?` | Check if graph is bipartite |
 | `#bipartite_sets` | Get bipartite partition sets |
 | `#strongly_connected_components` | Tarjan's SCC algorithm |
+| `#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
@@ -79,6 +99,63 @@ module Philiprehberger
         (@adjacency[node] || []).length
       end
 
+      # Return the in-degree of a node (directed graphs).
+      # For undirected graphs, returns the same as degree.
+      #
+      # @param node [Object] the node
+      # @return [Integer]
+      def in_degree(node)
+        return degree(node) unless @directed
+
+        count = 0
+        @adjacency.each_value do |edges_list|
+          edges_list.each { |e| count += 1 if e[:node] == node }
+        end
+        count
+      end
+
+      # Return the out-degree of a node (directed graphs).
+      # For undirected graphs, returns the same as degree.
+      #
+      # @param node [Object] the node
+      # @return [Integer]
+      def out_degree(node)
+        return degree(node) unless @directed
+
+        (@adjacency[node] || []).length
+      end
+
+      # Check if a node exists.
+      #
+      # @param id [Object] the node identifier
+      # @return [Boolean]
+      def node?(id)
+        @adjacency.key?(id)
+      end
+
+      # Check if an edge exists between two nodes.
+      #
+      # @param from [Object] source node
+      # @param to [Object] destination node
+      # @return [Boolean]
+      def edge?(from, to)
+        return false unless @adjacency.key?(from)
+
+        @adjacency[from].any? { |e| e[:node] == to }
+      end
+
+      # Get the weight of an edge.
+      #
+      # @param from [Object] source node
+      # @param to [Object] destination node
+      # @return [Numeric, nil] the edge weight, or nil if no edge exists
+      def weight(from, to)
+        return nil unless @adjacency.key?(from)
+
+        edge = @adjacency[from].find { |e| e[:node] == to }
+        edge&.dig(:weight)
+      end
+
       # Return all node ids.
       #
       # @return [Array<Object>]
@@ -86,6 +163,27 @@ module Philiprehberger
         @adjacency.keys
       end
 
+      # Return the number of nodes.
+      #
+      # @return [Integer]
+      def node_count
+        @adjacency.length
+      end
+
+      # Return the number of edges.
+      #
+      # @return [Integer]
+      def edge_count
+        edges.length
+      end
+
+      # Whether the graph has no nodes.
+      #
+      # @return [Boolean]
+      def empty?
+        @adjacency.empty?
+      end
+
       # Return all edges as [from, to, weight] tuples.
       #
       # @return [Array<Hash>]
@@ -176,6 +274,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
@@ -205,6 +333,111 @@ module Philiprehberger
         end
       end
 
+      # Check if a path exists between two nodes using BFS.
+      #
+      # @param from [Object] source node
+      # @param to [Object] destination node
+      # @return [Boolean]
+      def path?(from, to)
+        return false unless @adjacency.key?(from) && @adjacency.key?(to)
+        return true if from == to
+
+        visited = { from => true }
+        queue = [from]
+
+        until queue.empty?
+          node = queue.shift
+          neighbors(node).each do |neighbor|
+            return true if neighbor == to
+
+            unless visited[neighbor]
+              visited[neighbor] = true
+              queue << neighbor
+            end
+          end
+        end
+
+        false
+      end
+
+      # Extract a subgraph containing only the specified nodes and edges between them.
+      #
+      # @param node_ids [Array<Object>] the nodes to include
+      # @return [Graph] a new graph
+      def subgraph(node_ids)
+        node_set = node_ids.is_a?(Set) ? node_ids : Set.new(node_ids)
+        g = self.class.new(directed: @directed)
+
+        node_set.each { |id| g.add_node(id) if @adjacency.key?(id) }
+
+        @adjacency.each do |from, edges_list|
+          next unless node_set.include?(from)
+
+          edges_list.each do |edge|
+            next unless node_set.include?(edge[:node])
+            next if !@directed && from.to_s > edge[:node].to_s
+
+            g.add_edge(from, edge[:node], weight: edge[:weight])
+          end
+        end
+
+        g
+      end
+
+      # Return a new graph with all edges reversed.
+      # Only works on directed graphs.
+      #
+      # @return [Graph] a new graph with reversed edges
+      # @raise [Error] if the graph is not directed
+      def transpose
+        raise Error, 'transpose requires a directed graph' unless @directed
+
+        g = self.class.new(directed: true)
+        @adjacency.each_key { |id| g.add_node(id) }
+        @adjacency.each do |from, edges_list|
+          edges_list.each do |edge|
+            g.add_edge(edge[:node], from, weight: edge[:weight])
+          end
+        end
+        g
+      end
+
+      # Calculate the density of the graph.
+      # Density is the ratio of actual edges to possible edges.
+      #
+      # @return [Float] density between 0.0 and 1.0
+      def density
+        n = @adjacency.length
+        return 0.0 if n < 2
+
+        m = edge_count.to_f
+        max_edges = @directed ? n * (n - 1) : n * (n - 1) / 2.0
+        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.2.4'
+    VERSION = '0.4.0'
   end
 end

metadata

@@ -1,18 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-graph
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-04-17 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
-  detection, and connected component discovery.
+  detection, connected components, minimum spanning tree, maximum flow, graph coloring,
+  bipartiteness checking, strongly connected components, and DOT/JSON serialization.
 email:
 - me@philiprehberger.com
 executables: []