dijkstra_fast 1.4.2 → 1.5.2

data/lib/dijkstra_fast/graph.rb

@@ -24,8 +24,10 @@ module DijkstraFast
   ##
   class Graph
 
+    include DijkstraFast::ShortestPath
+
     def initialize
-      @nodes = {}
+      @edges = {}
     end
 
     # Adds a weighted edge to the graph. This represents a possible path from the
@@ -36,27 +38,15 @@ module DijkstraFast
     #                           If not provided, a default distance of `1` is used.
     # @return [nil]
     def add(source, dest, distance: 1)
-      _add_edge(node(source), node(dest), distance) unless source == dest
-    end
+      return if source == dest
 
-    # Finds the shortest path between items, returning both the path as well as
-    # the total distance travelled.
-    # @param source [Object] Any Ruby object that represents the source item
-    # @param dest [Object] Any Ruby object that represents the destination item
-    # @return [BestPath]
-    def shortest_path(source, dest)
-      best_path = BestPath.new
-      best_path.distance = _shortest_path(node(source), node(dest), best_path.path)
-      if best_path.path.empty? || best_path.distance.nil? || best_path.distance < 0
-        raise NoPathExistsError
-      end
-      best_path
+      @edges[source] ||= []
+      @edges[source] << [dest, distance]
     end
 
-    private
-
-    def node(obj)
-      @nodes[obj] ||= @nodes.size # Auto-increment id
+    def connections(source, &block)
+      @edges[source]&.each(&block)
+      nil
     end
 
   end

data/lib/dijkstra_fast/native.rb

@@ -0,0 +1,68 @@
+module DijkstraFast
+  ##
+  # Do not use this class. For internal purposes only.
+  ##
+  class Native
+
+    private
+
+    def initialize(delegate)
+      @delegate = delegate
+      @ids = {}
+      @nodes = {}
+    end
+
+    def connections(source_id)
+      @delegate.connections(node(source_id)) do |dest, distance = 1|
+        yield node_id(dest), distance
+      end
+    end
+
+    def shortest_path(source, dest, progress: false)
+      if !progress
+        progress = nil
+      elsif !progress.is_a?(Proc)
+        progress_bar = create_progress_bar(progress)
+        progress = lambda do |completed, total|
+          progress_bar.total = total
+          progress_bar.progress = completed
+        end
+      end
+
+      distance, path = _shortest_path(node_id(source), node_id(dest), progress)
+      [distance, @ids.invert.values_at(*path)]
+    ensure
+      progress_bar&.clear
+    end
+
+    def node_id(node)
+      id = @ids[node]
+      if id.nil?
+        id = @ids[node] = @ids.size + 1 # Auto-incrementing id (starting at 1 to leave 0 = nil)
+        @nodes[id] = node
+      end
+      id
+    end
+
+    def node(id)
+      @nodes.fetch(id)
+    end
+
+    def create_progress_bar(config)
+      require 'progressbar' unless defined?(ProgressBar)
+      return ProgressBar.create(config) if config.is_a?(Hash)
+
+      format = config.is_a?(String) ? config : "%a %b\u{15E7}%i %p%% %t"
+      ProgressBar.create(
+        format:         format,
+        progress_mark:  ' ',
+        remainder_mark: "\u{FF65}",
+        total:          100,
+        autofinish:     false,
+      )
+    rescue LoadError
+      raise LoadError, 'The default implementation of progress reporting requires the progressbar gem'
+    end
+
+  end
+end

data/lib/dijkstra_fast/shortest_path.rb

@@ -0,0 +1,96 @@
+module DijkstraFast
+  ##
+  # Interface to allow arbitrary classes to calculate the shortest path between
+  # two "items" using a native implementation of Dijkstra's algorithm.
+  #
+  # @example
+  #
+  #   class GraphOne
+  #     include DijkstraFast::ShortestPath
+  #
+  #     def connections(source)
+  #       source.find_next do |dest, distance|
+  #         yield dest, distance
+  #       end
+  #     end
+  #   end
+  #
+  #   distance, path = GraphOne.new.shortest_path(source, dest)
+  #
+  # @example
+  #
+  #   class GraphTwo
+  #     include DijkstraFast::ShortestPath
+  #
+  #     def initialize
+  #       # All edges have distance 1
+  #       @edges = { 1 => [2, 3], 2 => [3] }
+  #     end
+  #
+  #     def connections(source, &block)
+  #       @edges.fetch(source, []).each(&block)
+  #     end
+  #   end
+  #
+  #   distance = GraphTwo.new.shortest_distance(source, dest)
+  #
+  # @example
+  #
+  #   class GraphThree
+  #     include DijkstraFast::ShortestPath
+  #
+  #     def connections(source)
+  #       case source
+  #       when 'A'
+  #         yield 'B', 3
+  #         yield 'C' # Default distance 1
+  #       when 'B'
+  #         yield 'C', 10
+  #       end
+  #     end
+  #   end
+  #
+  #   distance, path = GraphThree.new.shortest_path(source, dest)
+  #
+  # @see README
+  # @see https://en.wikipedia.org/wiki/Dijkstra's_algorithm
+  ##
+  module ShortestPath
+
+    # Returns the edges originating at source
+    # @param source [Object] Any Ruby object that represents the source item
+    # @yield [Object, int] A connection to destination object with given distance
+    # @return [nil]
+    def connections(source)
+      # Does nothing by default but should be implemented by class
+    end
+
+    # Finds the shortest path between items, returning both the path as well as
+    # the total distance travelled.
+    # @param source [Object] Any Ruby object that represents the source item
+    # @param dest [Object] Any Ruby object that represents the destination item
+    # @param progress [Boolean|String|Proc] If falsey (default), no progress will
+    #        be displayed.  If a Proc is given, it will be yielded progress
+    #        (completed / total) as progress is made.  If otherwise truthy the
+    #        ruby-progressbar gem will be required and displayed; if passed a
+    #        String it will be used as the progress bar's format.
+    # @return [Array<int, Array>]
+    def shortest_path(source, dest, progress: false)
+      Native.new(self).send(:shortest_path, source, dest, progress: progress)
+    end
+
+    # Finds the shortest distance between items
+    # @param source [Object] Any Ruby object that represents the source item
+    # @param dest [Object] Any Ruby object that represents the destination item
+    # @param progress [Boolean|String|Proc] If falsey (default), no progress will
+    #        be displayed.  If a Proc is given, it will be yielded progress
+    #        (completed / total) as progress is made.  If otherwise truthy the
+    #        ruby-progressbar gem will be required and displayed; if passed a
+    #        String it will be used as the progress bar's format.
+    # @return [int]
+    def shortest_distance(source, dest, progress: false)
+      shortest_path(source, dest, progress: progress).first
+    end
+
+  end
+end

data/lib/dijkstra_fast/version.rb

@@ -1,6 +1,6 @@
 module DijkstraFast
 
   # Current gem version
-  VERSION = '1.4.2'
+  VERSION = '1.5.2'
 
 end

data/lib/dijkstra_fast.rb

@@ -1,22 +1,92 @@
 ##
-# Provides native implementation of Dijkstra's algorithm for finding the shortest
-# path between two vertices in a large, sparse graph.
+# When graph nodes "know" which nodes they are connected to, one of the two
+# class methods on this module can be be used directly to calculate the shortest
+# distance between nodes.  Node objects must implement a method (by default
+# <code>connections</code>) which yields all connected nodes and (optionally) the
+# distance to that connected node. If the yield only supplies the connected
+# node, a defualt distance of <code>1</code> is used.
 #
-# Underlying algorithm is implemented in C using a priority queue.  Edges are
-# represented using linked lists rather than an adjacency matrix to reduce memory
-# footprint when operating on very large graphs where the average number of edges
-# between nodes is relatively small (e.g. < 1/10 the number of nodes). See
+# It is important to ensure that <code>hash</code> and <code>eql?</code> are properly implemented so
+# that two objects that are logically the same are treatest thusly.
 #
-# @see README
-# @see https://en.wikipedia.org/wiki/Dijkstra's_algorithm
+# @example
+#
+#   class SomethingWithConnections
+#     def find_next
+#       yield SomethingWithConnections.new('C'), 2
+#       yield SomethingWithConnections.new('D'), 4
+#     end
+#
+#     def hash
+#       # implement me
+#     end
+#
+#     def eql?(other)
+#       # implement me
+#     end
+#   end
+#
+#   a = SomethingWithConnections.new('A')
+#   b = SomethingWithConnections.new('B')
+#   distance, path = DijkstraFast.shortest_path(a, b, connections: :find_next)
+#
+# @example
+#
+#   class SomethingElseWithConnections
+#     def connections
+#       yield # implement me
+#       yield # implement me
+#     end
+#   end
+#
+#   a = SomethingElseWithConnections.new
+#   b = SomethingElseWithConnections.new
+#   distance = DijkstraFast.shortest_distance(a, b)
 ##
 module DijkstraFast
 
-  autoload :BestPath,           'dijkstra_fast/best_path'
   autoload :Graph,              'dijkstra_fast/graph'
+  autoload :Native,             'dijkstra_fast/native'
   autoload :NoPathExistsError,  'dijkstra_fast/no_path_exists_error'
+  autoload :PriorityQueue,      'dijkstra_fast/priority_queue'
+  autoload :ShortestPath,       'dijkstra_fast/shortest_path'
   autoload :VERSION,            'dijkstra_fast/version'
 
+  # Finds the shortest path between items, returning both the path as well as
+  # the total distance travelled.
+  # @param source [Object] Any Ruby object that represents the source item
+  # @param dest [Object] Any Ruby object that represents the destination item
+  # @param progress [Boolean|String|Proc] If falsey (default), no progress will
+  #        be displayed.  If a Proc is given, it will be yielded progress
+  #        (completed / total) as progress is made.  If otherwise truthy the
+  #        ruby-progressbar gem will be required and displayed; if passed a
+  #        String it will be used as the progress bar's format.
+  # @param connections [Symbol|String] The method to call on each item to
+  #        obtain adjacent items in the graph.  Defaults to 'connections'
+  # @return [Array<int, Array>]
+  def self.shortest_path(source, dest, connections: 'connections', progress: false)
+    clazz = Class.new { include DijkstraFast::ShortestPath }
+    clazz.define_method(:connections) do |source, &block|
+      source.send(connections, &block)
+    end
+    clazz.new.shortest_path(source, dest, progress: progress)
+  end
+
+  # Finds the shortest distance between items
+  # @param source [Object] Any Ruby object that represents the source item
+  # @param dest [Object] Any Ruby object that represents the destination item
+  # @param progress [Boolean|String|Proc] If falsey (default), no progress will
+  #        be displayed.  If a Proc is given, it will be yielded progress
+  #        (completed / total) as progress is made.  If otherwise truthy the
+  #        ruby-progressbar gem will be required and displayed; if passed a
+  #        String it will be used as the progress bar's format.
+  # @param connections [Symbol|String] The method to call on each item to
+  #        obtain adjacent items in the graph.
+  # @return [int]
+  def self.shortest_distance(source, dest, connections: 'connections', progress: false)
+    shortest_path(source, dest, connections: connections, progress: progress).first
+  end
+
 end
 
 require 'dijkstra_fast/dijkstra_fast'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dijkstra_fast
 version: !ruby/object:Gem::Version
-  version: 1.4.2
+  version: 1.5.2
 platform: ruby
 authors:
 - David McCullars
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-12-23 00:00:00.000000000 Z
+date: 2022-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: github-markup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -157,6 +185,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - ".travis.yml"
+- ".yardopts"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE
@@ -164,20 +193,26 @@ files:
 - Rakefile
 - dijkstra_fast.gemspec
 - ext/dijkstra_fast/dijkstra_fast.c
-- ext/dijkstra_fast/dijkstra_graph.c
-- ext/dijkstra_fast/dijkstra_graph.h
+- ext/dijkstra_fast/errors.c
+- ext/dijkstra_fast/errors.h
+- ext/dijkstra_fast/expand_capacity.h
 - ext/dijkstra_fast/extconf.rb
-- ext/dijkstra_fast/prioritized_item_list.c
-- ext/dijkstra_fast/prioritized_item_list.h
+- ext/dijkstra_fast/native.c
+- ext/dijkstra_fast/native.h
+- ext/dijkstra_fast/native_shortest_path.c
+- ext/dijkstra_fast/priority_queue.c
+- ext/dijkstra_fast/priority_queue.h
 - lib/dijkstra_fast.rb
-- lib/dijkstra_fast/best_path.rb
 - lib/dijkstra_fast/graph.rb
+- lib/dijkstra_fast/native.rb
 - lib/dijkstra_fast/no_path_exists_error.rb
+- lib/dijkstra_fast/shortest_path.rb
 - lib/dijkstra_fast/version.rb
 homepage: https://github.com/david-mccullars/dijkstra_fast
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -186,7 +221,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/ext/dijkstra_fast/dijkstra_graph.c

@@ -1,234 +0,0 @@
-#include <ruby.h>
-#include <dijkstra_graph.h>
-#include <prioritized_item_list.h>
-
-const size_t VERTEX_LIST_SIZE = sizeof(VertexListStruct);
-const size_t EDGE_LIST_SIZE = sizeof(EdgeListStruct);
-const size_t VERTEX_SIZE = sizeof(VertexStruct);
-const size_t EDGE_SIZE = sizeof(EdgeStruct);
-const size_t GRAPH_SIZE = sizeof(GraphStruct);
-
-static const rb_data_type_t graph_typed_data = {
-  "Dijkstra/Graph",
-  { 0, free_graph, },
-  0, 0,
-  RUBY_TYPED_FREE_IMMEDIATELY,
-};
-
-//////////////////////////////////////////////////////////////////////////////////////
-
-void Init_dijkstra_graph() {
-  VALUE DijkstraFastModule, GraphClass;
-
-  DijkstraFastModule = rb_const_get(rb_cObject, rb_intern("DijkstraFast"));
-  GraphClass = rb_const_get(DijkstraFastModule, rb_intern("Graph"));
-
-  rb_define_alloc_func(GraphClass, dijkstra_graph_allocate);
-  rb_define_private_method(GraphClass, "_add_edge", dijkstra_graph_add_edge, 3);
-  rb_define_private_method(GraphClass, "_shortest_path", dijkstra_graph_shortest_path, 3);
-}
-
-VALUE dijkstra_graph_allocate(VALUE self) {
-  Graph g = malloc(GRAPH_SIZE);
-
-  // Grab a reference to the hash type used by a generic Ruby {}
-  // which accepts any key and any value.  We'll need this type to create
-  // a st_table in which to put arbitrary VALUE keys.  This hash type
-  // should be a static constant and thus should be safe to utilize without
-  // fear of garbage collection.
-  const struct st_hash_type *objhash = rb_hash_tbl(rb_hash_new(), "dijkstra.c", 1)->type;
-
-  g->vertex_count = 0;
-  g->vertices = NULL;
-  g->vertex_lookup = st_init_table_with_size(objhash, 0);
-
-  return TypedData_Wrap_Struct(self, &graph_typed_data, g);
-}
-
-VALUE dijkstra_graph_add_edge(VALUE self, VALUE source_label, VALUE dest_label, VALUE distance) {
-  Graph g;
-
-  TypedData_Get_Struct(self, GraphStruct, &graph_typed_data, g);
-  add_edge_with_labels(g, source_label, dest_label, NUM2INT(distance));
-  return Qnil;
-}
-
-VALUE dijkstra_graph_shortest_path(VALUE self, VALUE source_label, VALUE dest_label, VALUE best_path) {
-  Graph g;
-  Vertex source, dest;
-
-  TypedData_Get_Struct(self, GraphStruct, &graph_typed_data, g);
-  source = lookup_vertex(g, source_label, false);
-  dest = lookup_vertex(g, dest_label, false);
-
-  if (source == NULL || dest == NULL) {
-    return Qnil;
-  } else {
-    return INT2NUM(shortest_path(g, source, dest, best_path));
-  }
-}
-
-//////////////////////////////////////////////////////////////////////////////////////
-
-void free_graph(void *data) {
-  Graph g = (Graph)data;
-
-  struct EdgeListStruct **vertices;
-
-  free_vertex_list(g->vertices, free_vertex);
-  free(g->vertex_lookup);
-  free(g);
-}
-
-void free_vertex(Vertex n) {
-  free_edge_list(n->edges, free_edge);
-  free(n);
-}
-
-void free_vertex_list(VertexList vertices, void (*free_item)(Vertex)) {
-  VertexList tmp;
-  while (vertices != NULL) {
-    tmp = vertices;
-    vertices = vertices->next;
-    if (free_item) {
-      free_item(tmp->vertex);
-    }
-    free(tmp);
-  }
-}
-
-void free_edge(Edge e) {
-  // Assume source and destination vertices were allocated elsewhere and will be free'd elsewhere
-  free(e);
-}
-
-void free_edge_list(EdgeList edges, void (*free_item)(Edge)) {
-  EdgeList tmp;
-  while (edges != NULL) {
-    tmp = edges;
-    edges = edges->next;
-    if (free_item) {
-      free_item(tmp->edge);
-    }
-    free(tmp);
-  }
-}
-
-//////////////////////////////////////////////////////////////////////////////////////
-
-Vertex add_vertex(Graph g, VALUE label) {
-  VertexList tmp = malloc(VERTEX_LIST_SIZE);
-
-  tmp->vertex = malloc(VERTEX_SIZE);
-  tmp->vertex->id = g->vertices != NULL ? g->vertices->vertex->id + 1 : 0; // Auto-incrementing id
-  tmp->vertex->label = label;
-  tmp->vertex->edges = NULL;
-
-  tmp->next = g->vertices;
-  g->vertices = tmp;
-  g->vertex_count += 1;
-
-  return tmp->vertex;
-}
-
-VertexList add_vertex_to_list(VertexList list, VALUE label) {
-  VertexList tmp = malloc(VERTEX_LIST_SIZE);
-
-  tmp->vertex = malloc(VERTEX_SIZE);
-  tmp->vertex->label = label;
-  tmp->vertex->edges = NULL;
-
-  tmp->next = list;
-  return tmp;
-}
-
-Edge add_edge(Vertex source, Vertex dest, int distance) {
-  EdgeList tmp = malloc(EDGE_LIST_SIZE);
-
-  tmp->edge = malloc(EDGE_SIZE);
-  tmp->edge->source = source;
-  tmp->edge->dest = dest;
-  tmp->edge->distance = distance;
-
-  tmp->next = source->edges;
-  source->edges = tmp;
-
-  return tmp->edge;
-}
-
-Edge add_edge_with_labels(Graph g, VALUE source_label, VALUE dest_label, int distance) {
-  Vertex source, dest;
-
-  source = lookup_vertex(g, source_label, true);
-  dest = lookup_vertex(g, dest_label, true);
-
-  return add_edge(source, dest, distance);
-}
-
-Vertex lookup_vertex(Graph g, VALUE label, bool create_if_missing) {
-  Vertex n = NULL;
-
-  if (!st_lookup(g->vertex_lookup, (st_data_t)label, (st_data_t *)&n)) {
-    if (!create_if_missing) return NULL;
-    n = add_vertex(g, label);
-    st_add_direct(g->vertex_lookup, (st_data_t)label, (st_data_t)n);
-  }
-  return n;
-}
-
-//////////////////////////////////////////////////////////////////////////////////////
-
-int shortest_path(Graph g, Vertex source, Vertex dest, VALUE best_path) {
-  Vertex *items, *prevs;
-  PrioritizedItemList list;
-
-  int d, du, dv;
-  Vertex u, v;
-  VertexList vl;
-  EdgeList el;
-  bool reached = source == dest;
-
-  items = malloc(g->vertex_count * sizeof(Vertex));
-  prevs = malloc(g->vertex_count * sizeof(Vertex));
-  list = make_prioritized_item_list(g->vertex_count);
-
-  for (vl = g->vertices; vl != NULL; vl = vl->next) {
-    v = vl->vertex;
-    items[v->id] = v;
-    prevs[v->id] = NULL;
-  }
-
-  update_prioritized_item(list, source->id, 0);
-
-  while (!empty_prioritized_item_list(list)) {
-    u = items[next_prioritized_item(list)];
-    du = get_priority(list, u->id);
-    for (el = u->edges; el != NULL; el = el->next) {
-      v = el->edge->dest;
-      dv = get_priority(list, v->id);
-      d = du + el->edge->distance;
-      if (d < 0) d = INT_MAX; // Wrapped around
-
-      if (in_prioritized_item_list(list, v->id) && d < dv) {
-        update_prioritized_item(list, v->id, d);
-        prevs[v->id] = u;
-        reached = reached || v == dest;
-      }
-    }
-  }
-
-  if (reached) {
-    for (v = dest; v != NULL; v = prevs[v->id]) {
-      rb_ary_unshift(best_path, v->label); 
-    }
-    d = get_priority(list, dest->id);
-  } else {
-    d = -1;
-  }
-
-  free(items);
-  free(prevs);
-  free_prioritized_item_list(list);
-
-  return d;
-}