d_heap 0.3.0 → 0.7.0

data/ext/d_heap/extconf.rb

@@ -2,10 +2,52 @@
 
 require "mkmf"
 
-# if /darwin/ =~ RUBY_PLATFORM
-#   $CFLAGS << " -D__D_HEAP_DEBUG"
-# end
+# For testing in CI (because I don't otherwise have easy access to Mac OS):
+# $CFLAGS << " -D__D_HEAP_DEBUG" if /darwin/ =~ RUBY_PLATFORM
+# $CFLAGS << " -debug inline-debug-info "
+# $CFLAGS << " -g -ginline-points "
+# $CFLAGS << " -fno-omit-frame-pointer "
+
+# Use `rake compile -- --enable-debug`
+debug_mode = enable_config("debug", ENV["EXTCONF_DEBUG"] == "1")
+
+# Use `rake compile -- --enable-development`
+devel_mode = enable_config("development") || debug_mode
+
+if debug_mode
+  $stderr.puts "Building in debug mode." # rubocop:disable Style/StderrPuts
+  CONFIG["warnflags"] \
+    << " -ggdb" \
+    << " -DDEBUG"
+end
+
+if devel_mode
+  $stderr.puts "Building in development mode." # rubocop:disable Style/StderrPuts
+  CONFIG["warnflags"] \
+    << " -Wall " \
+    << " -Wpedantic" \
+  # There are warnings on MacOS that are annoying to debug (I don't have a Mac).
+  unless RbConfig::CONFIG["target_os"] =~ /darwin/
+    CONFIG["warnflags"] << " -Werror"
+  end
+end
+
+# Use `rake compile -- --enable-heapmap`
+if enable_config("heapmap", true)
+  $stderr.puts "Building with DHeap::Map support." # rubocop:disable Style/StderrPuts
+  $defs.push "-DDHEAP_MAP"
+end
 
 have_func "rb_gc_mark_movable" # since ruby-2.7
 
+check_sizeof("long")
+check_sizeof("unsigned long long")
+check_sizeof("long double")
+check_sizeof("double")
+
+unless have_macro("LDBL_MANT_DIG", "float.h")
+  raise NotImplementedError, "Missing LDBL_MANT_DIG."
+end
+
+create_header
 create_makefile("d_heap/d_heap")

data/lib/d_heap.rb

@@ -10,13 +10,126 @@ require "d_heap/version"
 # the nodes have _d_ children instead of 2.  This allows for "decrease priority"
 # operations to be performed more quickly with the tradeoff of slower delete
 # minimum.  Additionally, _d_-ary heaps can have better memory cache behavior than
-# binary heaps, allowing them to run more quickly in practice despite slower
+# binary heaps, allowing them to pop more quickly in practice despite slower
 # worst-case time complexity.
 #
+# Although _d_ can be configured when creating the heap, it's usually best to
+# keep the default value of 4, because d=4 gives the smallest coefficient for
+# <tt>(d + 1) log n / log d</tt> result.  As always, use benchmarks for your
+# particular use-case.
+#
+# @example Basic push, peek, and pop
+#     # create some example objects to place in our heap
+#     Task = Struct.new(:id, :time) do
+#       def to_f; time.to_f end
+#     end
+#     t1 = Task.new(1, Time.now + 5*60)
+#     t2 = Task.new(2, Time.now + 50)
+#     t3 = Task.new(3, Time.now + 60)
+#     t4 = Task.new(4, Time.now +  5)
+#
+#     # create the heap
+#     require "d_heap"
+#     heap = DHeap.new
+#
+#     # push with an explicit score (which might be extrinsic to the value)
+#     heap.push t1, t1.to_f
+#
+#     # the score will be implicitly cast with Float, so any object with #to_f
+#     heap.push t2, t2
+#
+#     # if the object has an intrinsic score via #to_f, "<<" is the simplest API
+#     heap << t3 << t4
+#
+#     # pop returns the lowest scored item, and removes it from the heap
+#     heap.pop    # => #<struct Task id=4, time=2021-01-17 17:02:22.5574 -0500>
+#     heap.pop    # => #<struct Task id=2, time=2021-01-17 17:03:07.5574 -0500>
+#
+#     # peek returns the lowest scored item, without removing it from the heap
+#     heap.peek   # => #<struct Task id=3, time=2021-01-17 17:03:17.5574 -0500>
+#     heap.pop    # => #<struct Task id=3, time=2021-01-17 17:03:17.5574 -0500>
+#
+#     # pop_lte handles the common "h.pop if h.peek_score < max" pattern
+#     heap.pop_lte(Time.now + 65) # => nil
+#
+#     # the heap size can be inspected with size and empty?
+#     heap.empty? # => false
+#     heap.size   # => 1
+#     heap.pop    # => #<struct Task id=1, time=2021-01-17 17:07:17.5574 -0500>
+#     heap.empty? # => true
+#     heap.size   # => 0
+#
+#     # popping from an empty heap returns nil
+#     heap.pop    # => nil
+#
 class DHeap
+  alias deq        pop
+  alias shift      pop
+  alias next       pop
+  alias pop_all_lt pop_all_below
+  alias pop_below  pop_lt
+
+  alias enq        push
+
+  alias first      peek
+
+  alias length     size
+  alias count      size
+
+  # Initialize a _d_-ary min-heap.
+  #
+  # @param d [Integer] Number of children for each parent node.
+  #          Higher values generally speed up push but slow down pop.
+  #          If all pushes are popped, the default is probably best.
+  # @param capacity [Integer] initial capacity of the heap.
+  def initialize(d: DEFAULT_D, capacity: DEFAULT_CAPA) # rubocop:disable Naming/MethodParameterName
+    __init_without_kw__(d, capacity, false)
+  end
+
+  # Consumes the heap by popping each minumum value until it is empty.
+  #
+  # If you want to iterate over the heap without consuming it, you will need to
+  # first call +#dup+
+  #
+  # @param with_score [Boolean] if scores shoul also be yielded
+  #
+  # @yieldparam value [Object] each value that would be popped
+  # @yieldparam score [Numeric] each value's score, if +with_scores+ is true
+  #
+  # @return [Enumerator] if no block is given
+  # @return [nil] if a block is given
+  def each_pop(with_scores: false)
+    return to_enum(__method__, with_scores: with_scores) unless block_given?
+    if with_scores
+      yield(*pop_with_score) until empty?
+    else
+      yield pop until empty?
+    end
+    nil
+  end
+
+  if defined?(Map)
+
+    # Unlike {DHeap}, an object can only be added into a {DHeap::Map} once.  Any
+    # subsequent addition simply rescores the already existing member.  Objects
+    # are identified by their {#hash} value, just like with Hash.
+    class Map
+      alias score   :[]
+      alias rescore :[]=
+      alias update  :[]=
+
+      # Initialize a _d_-ary min-heap which can map objects to scores.
+      #
+      # @param d [Integer] Number of children for each parent node.
+      #          Higher values generally speed up push but slow down pop.
+      #          If all pushes are popped, the default is probably best.
+      # @param capacity [Integer] initial capacity of the heap.
+      def initialize(d: DEFAULT_D, capacity: DEFAULT_CAPA) # rubocop:disable Naming/MethodParameterName
+        __init_without_kw__(d, capacity, true)
+      end
+
+    end
 
-  def initialize_copy(other)
-    raise NotImplementedError, "initialize_copy should deep copy array"
   end
 
 end

data/lib/d_heap/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 class DHeap
-  VERSION = "0.3.0"
+  VERSION = "0.7.0"
 
 end

metadata

@@ -1,17 +1,31 @@
 --- !ruby/object:Gem::Specification
 name: d_heap
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.7.0
 platform: ruby
 authors:
 - nicholas a. evans
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-12-29 00:00:00.000000000 Z
+date: 2021-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rspec-benchmark
+  name: benchmark_driver
+  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: ruby-prof
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -34,26 +48,28 @@ extensions:
 - ext/d_heap/extconf.rb
 extra_rdoc_files: []
 files:
+- ".clang-format"
 - ".github/workflows/main.yml"
 - ".gitignore"
-- ".rspec"
 - ".rubocop.yml"
-- ".travis.yml"
+- ".yardopts"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
-- Gemfile
-- Gemfile.lock
+- D
 - LICENSE.txt
 - README.md
-- Rakefile
-- bin/console
-- bin/rake
-- bin/rspec
-- bin/rubocop
-- bin/setup
 - d_heap.gemspec
+- docs/benchmarks-2.txt
+- docs/benchmarks-mem.txt
+- docs/benchmarks.txt
+- docs/profile.txt
+- ext/d_heap/.rubocop.yml
 - ext/d_heap/d_heap.c
-- ext/d_heap/d_heap.h
 - ext/d_heap/extconf.rb
+- images/push_n.png
+- images/push_n_pop_n.png
+- images/push_pop.png
+- images/wikipedia-min-heap.png
 - lib/d_heap.rb
 - lib/d_heap/version.rb
 homepage: https://github.com/nevans/d_heap
@@ -62,7 +78,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/nevans/d_heap
   source_code_uri: https://github.com/nevans/d_heap
-  changelog_uri: https://github.com/nevans/d_heap/blob/master/Changelog.md
+  changelog_uri: https://github.com/nevans/d_heap/blob/master/CHANGELOG.md
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -71,7 +87,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -81,5 +97,5 @@ requirements: []
 rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
-summary: A d-ary heap implementation, for priority queues
+summary: very fast min-heap priority queue
 test_files: []

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.travis.yml

@@ -1,6 +0,0 @@
----
-language: ruby
-cache: bundler
-rvm:
-  - 2.7.2
-before_install: gem install bundler -v 2.1.4

data/Gemfile

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in d_heap.gemspec
-gemspec
-
-gem "rake", "~> 13.0"
-gem "rake-compiler"
-gem "rspec", "~> 3.10"
-gem "rubocop", "~> 1.0"

data/Gemfile.lock

@@ -1,67 +0,0 @@
-PATH
-  remote: .
-  specs:
-    d_heap (0.3.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    ast (2.4.1)
-    benchmark-malloc (0.2.0)
-    benchmark-perf (0.6.0)
-    benchmark-trend (0.4.0)
-    diff-lcs (1.4.4)
-    parallel (1.19.2)
-    parser (2.7.2.0)
-      ast (~> 2.4.1)
-    rainbow (3.0.0)
-    rake (13.0.3)
-    rake-compiler (1.1.1)
-      rake
-    regexp_parser (1.8.2)
-    rexml (3.2.3)
-    rspec (3.10.0)
-      rspec-core (~> 3.10.0)
-      rspec-expectations (~> 3.10.0)
-      rspec-mocks (~> 3.10.0)
-    rspec-benchmark (0.6.0)
-      benchmark-malloc (~> 0.2)
-      benchmark-perf (~> 0.6)
-      benchmark-trend (~> 0.4)
-      rspec (>= 3.0)
-    rspec-core (3.10.0)
-      rspec-support (~> 3.10.0)
-    rspec-expectations (3.10.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-support (3.10.0)
-    rubocop (1.2.0)
-      parallel (~> 1.10)
-      parser (>= 2.7.1.5)
-      rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8)
-      rexml
-      rubocop-ast (>= 1.0.1)
-      ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 2.0)
-    rubocop-ast (1.1.1)
-      parser (>= 2.7.1.5)
-    ruby-progressbar (1.10.1)
-    unicode-display_width (1.7.0)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  d_heap!
-  rake (~> 13.0)
-  rake-compiler
-  rspec (~> 3.10)
-  rspec-benchmark
-  rubocop (~> 1.0)
-
-BUNDLED WITH
-   2.2.3

data/Rakefile

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-require "rake/extensiontask"
-
-task build: :compile
-
-Rake::ExtensionTask.new("d_heap") do |ext|
-  ext.lib_dir = "lib/d_heap"
-end
-
-task default: %i[clobber compile spec rubocop]

data/bin/console

@@ -1,15 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "d_heap"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)

data/bin/rake

@@ -1,29 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-#
-# This file was generated by Bundler.
-#
-# The application 'rake' is installed as part of a gem, and
-# this file is here to facilitate running it.
-#
-
-require "pathname"
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
-  Pathname.new(__FILE__).realpath)
-
-bundle_binstub = File.expand_path("../bundle", __FILE__)
-
-if File.file?(bundle_binstub)
-  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
-    load(bundle_binstub)
-  else
-    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
-Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
-  end
-end
-
-require "rubygems"
-require "bundler/setup"
-
-load Gem.bin_path("rake", "rake")