cantor 1.2.0

data/README.md

@@ -0,0 +1,97 @@
+# Cantor
+
+Fast implementation of finite and complement sets in Ruby
+
+## Constructors
+
+* `Cantor.empty`  
+  Finite set that contains no elements
+
+* `Cantor.build(enum)`  
+  Finite set containing each element in `enum`, whose domain of discourse is
+  unrestricted
+
+* `Cantor.absolute(enum, universe)`  
+  Finite set containing each element in `enum`, whose domain of discourse is
+  `universe`
+
+* `Cantor.universal`  
+  Infinite set containing every value in the universe
+
+* `Cantor.complement(enum)`  
+  Set containing every value except those in `enum`. Finite when `enum` is
+  infinite. Infinite when `enum` is finite
+
+## Operations
+
+* `xs.include?(x)`
+* `xs.exclude?(x)`
+* `xs.finite?`
+* `xs.infinite?`
+* `xs.empty?`
+* `xs.size`
+* `xs.replace(ys)`
+* `~xs`
+* `xs.complement`
+* `xs + xs`
+* `xs | ys`
+* `xs.union(ys)`
+* `xs - ys`
+* `xs.difference(ys)`
+* `xs ^ ys`
+* `xs.symmetric_difference(ys)`
+* `xs & ys`
+* `xs.intersection(ys)`
+* `xs <= ys`
+* `xs.subset?(ys)`
+* `xs < ys`
+* `xs.proper_subset?(ys)`
+* `xs >= ys`
+* `xs.superset?(ys)`
+* `xs > ys`
+* `xs.proper_superset?(ys)`
+* `xs.disjoint?(ys)`
+* `xs == ys`
+
+## Performance
+
+Sets with a finite domain of discourse are represented using a bit string of
+2<sup>|U|</sup> bits, where |U| is the size of the domain. This provides nearly
+O(1) constant-time implementation using bitwise operations for all of the above
+set operations.
+
+The bit string is represented as an Integer, but as the domain grows larger
+than `0.size * 8 - 2` items, the type is automatically expanded to a Bignum.
+Bitwise operations on Bignums are O(|U|), which is still be significantly
+faster than using the default Set library.
+
+Sets with an unrestricted domain of discourse are implemented using a Hash.
+Unary operations and membership tests are O(1) constant-time. Binary operations
+on these sets is close to that of the default Set library.
+
+### Benchmarks
+
+These benchmarks aren't intended to be useful. While they indicate the
+worst-case performance for Cantor, they probably don't show the worst
+case for the standard Set library.
+
+<table>
+  <tbody>
+    <tr>
+      <td><img title="intersection" src="/kputnam/cantor/raw/master/benchmark/intersection.png"/></td>
+      <td><img title="difference" src="/kputnam/cantor/raw/master/benchmark/difference.png"/></td>
+    </tr>
+    <tr>
+      <td><img title="union" src="/kputnam/cantor/raw/master/benchmark/union.png"/></td>
+      <td><img title="symmetric difference" src="/kputnam/cantor/raw/master/benchmark/sdifference.png"/></td>
+    </tr>
+    <tr>
+      <td><img title="subset" src="/kputnam/cantor/raw/master/benchmark/subset.png"/></td>
+      <td><img title="superset" src="/kputnam/cantor/raw/master/benchmark/superset.png"/></td>
+    </tr>
+    <tr>
+      <td><img title="equality" src="/kputnam/cantor/raw/master/benchmark/equality.png"/></td>
+      <td><img title="membership" src="/kputnam/cantor/raw/master/benchmark/membership.png"/></td>
+    </tr>
+  </tbody>
+</table>

data/Rakefile

@@ -0,0 +1,81 @@
+require "pathname"
+abspath = Pathname.new(File.dirname(__FILE__)).expand_path
+relpath = abspath.relative_path_from(Pathname.pwd)
+
+begin
+  require "rubygems"
+  require "bundler/setup"
+rescue LoadError
+  warn "couldn't load bundler:"
+  warn "  #{$!}"
+end
+
+task :console do
+  exec *%w(irb -I lib -r cantor)
+end
+
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new do |t|
+    t.verbose = false
+    t.pattern = "#{relpath}/spec/examples/**/*.example"
+
+    t.rspec_opts  = %w(--color --format p)
+    t.rspec_opts << "-I#{abspath}/spec"
+  end
+rescue LoadError
+  task :spec do
+    warn "couldn't load rspec"
+    warn "  #{$!}"
+    exit 1
+  end
+end
+
+begin
+  require "rcov"
+  begin
+    require "rspec/core/rake_task"
+    RSpec::Core::RakeTask.new(:rcov) do |t|
+      t.rcov = true
+      t.rcov_opts = "--exclude spec/,gems/,00401"
+
+      t.verbose = false
+      t.pattern = "#{relpath}/spec/examples/**/*.example"
+
+      t.rspec_opts  = %w(--color --format p)
+      t.rspec_opts << "-I#{abspath}/spec"
+    end
+  rescue LoadError
+    task :rcov do
+      warn "couldn't load rspec"
+      warn "  #{$!}"
+      exit 1
+    end
+  end
+rescue LoadError
+  task :rcov do
+    warn "couldn't load rcov:"
+    warn "  #{$!}"
+    exit 1
+  end
+end
+
+begin
+  require "yard"
+
+  # Note options are loaded from .yardopts
+  YARD::Rake::YardocTask.new(:yard => :clobber_yard)
+
+  task :clobber_yard do
+    rm_rf "#{relpath}/doc/generated"
+    mkdir_p "#{relpath}/doc/generated/images"
+  end
+rescue LoadError
+  task :yard do
+    warn "couldn't load yard:"
+    warn "  #{$!}"
+    exit 1
+  end
+end
+
+task :default => :spec

data/lib/cantor.rb

@@ -0,0 +1,54 @@
+module Cantor
+  autoload :AbstractSet,        "cantor/abstract_set"
+  autoload :AbsoluteSet,        "cantor/absolute_set"
+  autoload :NullSet,            "cantor/null_set"
+  autoload :RelativeComplement, "cantor/relative_complement"
+  autoload :RelativeSet,        "cantor/relative_set"
+  autoload :UniversalSet,       "cantor/universal_set"
+end
+
+class << Cantor
+  # @group Constructors
+  ###########################################################################
+
+  # @return [Cantor::AbstractSet]
+  def build(object)
+    if object.is_a?(Cantor::AbstractSet)
+      object
+    elsif object.is_a?(Enumerable)
+      Cantor::RelativeSet.build(object)
+    else
+      raise TypeError,
+        "argument must be an AbstractSet or Enumerable"
+    end
+  end
+
+  # @return [Cantor::AbstractSet]
+  def complement(other)
+    build(other).complement
+  end
+
+  # @return [Cantor::UniversalSet]
+  def universal
+    Cantor::UniversalSet.build
+  end
+
+  # @return [Cantor::NullSet]
+  def empty
+    Cantor::NullSet.build
+  end
+
+  # @return [Cantor::AbsoluteSet]
+  def absolute(other, universe = other)
+    if universe == Cantor::UniversalSet
+      build(other)
+    elsif universe.eql?(other)
+      Cantor::AbsoluteSet.build(universe)
+    else
+      Cantor::AbsoluteSet.build(universe).intersection(other)
+    end
+  end
+
+  # @endgroup
+  ###########################################################################
+end

data/lib/cantor/absolute_set.rb

@@ -0,0 +1,295 @@
+module Cantor
+
+  #
+  # {AbsoluteSet} is a subset of a finite, fully-enumerated universe set. This
+  # means every possible value that can belong to the {AbsoluteSet} must
+  # already belong to the universe set, which is a _finite_ collection.
+  #
+  # This implementation is fairly efficient when computing set operations on
+  # two sets from the same universe, especially compared to {RelativeSet}.
+  # Efficiency is achieved by encoding each element in the universe's
+  # membership to the specific subset as a bitmask. Operations can then be
+  # performed using bitwise operations, instead of using operations on a Hash.
+  #
+  # This data type is not suitable for sets whose elements belong to an
+  # huge universe of possible values, as each set requires `2**|U|` bits of
+  # storage where `|U|` is the size of the universe. Operations on sets that
+  # belong to different universes do not currently attempt to merge the two
+  # universe sets, as this probably a better use case for {RelativeSet}.
+  #
+  class AbsoluteSet < AbstractSet
+    include Enumerable
+
+    # @return [Integer]
+    attr_reader :mask
+
+    # @return [Hash]
+    attr_reader :universe
+
+    def initialize(mask, universe)
+      @mask, @universe = mask, universe.freeze
+    end
+
+    # @private
+    # @return [AbsoluteSet]
+    def copy(changes = {})
+      AbsoluteSet.new \
+        changes.fetch(:mask, @mask),
+        changes.fetch(:universe, @universe)
+    end
+
+    # Returns a single element from the set, with no guarantees about which
+    # element. If the set is {#empty?}, the return value is undefined.
+    def first
+      @universe.each do |value, n|
+        unless @mask[n].zero?
+          return value
+        end
+      end
+    end
+
+    # Yields each element in the set to the implicit block argument
+    #
+    # @return [void]
+    def each
+      @universe.each do |value, n|
+        unless @mask[n].zero?
+          yield(value)
+        end
+      end
+    end
+
+    # (see AbstractSet#finite?)
+    def finite?
+      true
+    end
+
+    # (see AbstractSet#empty?)
+    def empty?
+      @mask.zero?
+    end
+
+    # (see AbstractSet#size)
+    def size
+      @universe.inject(0){|size, (value, n)| size + @mask[n] }
+    end
+
+    # (see AbstractSet#replace)
+    def replace(other)
+      if other.is_a?(AbstractSet)
+        other
+      else
+        copy(:mask => as_mask(other, true))
+      end
+    end
+
+    # (see AbstractSet#include?)
+    def include?(element)
+      if n = @universe.fetch(element, false)
+        # Same as (@mask & (1 << n)).zero? but potentially eliminates
+        # converting the intermediate computation to a Ruby value
+        not @mask[n].zero?
+      end
+    end
+
+    # @group Set Operations
+    #########################################################################
+
+    # @return [AbsoluteSet]
+    def map
+      mask = 0
+
+      @universe.each do |value, n|
+        unless @mask[n].zero?
+          value = yield(value)
+
+          if m = @universe.fetch(value, false)
+            mask |= (1 << m)
+          else
+            raise "universe does not contain element #{value.inspect}"
+          end
+        end
+      end
+
+      copy(:mask => mask)
+    end
+
+    # @return [AbsoluteSet]
+    def select
+      mask = 0
+
+      @universe.each do |value, n|
+        unless @mask[n].zero? or not yield(value)
+          mask |= (1 << n)
+        end
+      end
+
+      copy(:mask => mask)
+    end
+
+    # @return [AbsoluteSet]
+    def reject
+      mask = 0
+
+      @universe.each do |value, n|
+        unless @mask[n].zero? or yield(value)
+          mask |= (1 << n)
+        end
+      end
+
+      copy(:mask => mask)
+    end
+
+    # (see AbstractSet#complement)
+    def complement
+      copy(:mask => ~@mask & ((1 << @universe.size) - 1))
+    end
+
+    # (see AbstractSet#union)
+    def union(other)
+      if other.is_a?(AbsoluteSet) and other.universe.eql?(@universe)
+        copy(:mask => @mask | other.mask)
+      elsif other.is_a?(AbstractSet) and other.infinite?
+        other.union(self)
+      else
+        copy(:mask => @mask | as_mask(other, true))
+      end
+    end
+
+    # (see AbstractSet#intersection)
+    def intersection(other)
+      if other.is_a?(AbsoluteSet) and other.universe.eql?(@universe)
+        copy(:mask => @mask & other.mask)
+      elsif other.is_a?(AbstractSet) and other.infinite?
+        other.intersection(self)
+      else
+        copy(:mask => @mask & as_mask(other, false))
+      end
+    end
+
+    # (see AbstractSet#difference)
+    def difference(other)
+      if other.is_a?(AbsoluteSet) and other.universe.eql?(@universe)
+        copy(:mask => @mask & ~other.mask)
+      elsif other.is_a?(AbstractSet) and other.infinite?
+        intersection(other.complement)
+      else
+        copy(:mask => @mask & ~as_mask(other, false))
+      end
+    end
+
+    # (see AbstractSet#symmetric_difference)
+    def symmetric_difference(other)
+      if other.is_a?(AbsoluteSet) and other.universe.eql?(@universe)
+        copy(:mask => @mask ^ other.mask)
+      elsif other.is_a?(AbstractSet) and other.infinite?
+        other.symmetric_difference(self)
+      else
+        copy(:mask => @mask ^ as_mask(other, true))
+      end
+    end
+
+    # @group Set Ordering
+    #########################################################################
+
+    # (see AbstractSet#==)
+    def ==(other)
+      if other.is_a?(AbsoluteSet) and other.universe.eql?(@universe)
+        @mask == other.mask
+      elsif other.is_a?(AbstractSet) and other.infinite?
+        false
+      elsif other.is_a?(Enumerable)
+        @mask == as_mask(other, false) and size == other.size
+      end
+    end
+
+    # @group Pretty Printing
+    #########################################################################
+
+    # @return [void]
+    def pretty_print(q)
+      q.text("AbsoluteSet[#{size}/#{@universe.size}]")
+      q.group(2, "(", ")") do
+        q.breakable ""
+
+        elements = to_a
+        elements.take(5).each do |e|
+          unless q.current_group.first?
+            q.text ","
+            q.breakable
+          end
+          q.pp e
+        end
+
+        if elements.length > 5
+          q.text ","
+          q.breakable
+          q.text "..."
+        end
+      end
+    end
+
+    # @return [String]
+    def inspect
+      "AbsoluteSet(#{to_a.map(&:inspect).join(', ')})"
+    end
+
+    # @endgroup
+    #########################################################################
+
+  private
+
+    # @return [Integer]
+    def as_mask(other, strict)
+      mask = 0
+      size = 0
+
+      if other.is_a?(AbstractSet) and @universe.size < other.size
+        @universe.each do |value, n|
+          if other.include?(value)
+            mask |= (1 << n)
+            size += 1
+          end
+        end
+
+        if strict and size < other.size
+          # other is not a subset of @universe
+          raise ArgumentError,
+            "universe does not contain all elements from #{other.inspect}"
+        end
+      else
+        # We might land here if other is an Array, since its probably
+        # much worse to repeatedly call Array#include? than it is to
+        # iterate the entire Array only once
+        other.each do |x|
+          if n = @universe.fetch(x, false)
+            mask |= (1 << n)
+          elsif strict
+            raise ArgumentError,
+              "universe does not contain element #{x.inspect}"
+          end
+        end
+      end
+
+      mask
+    end
+
+  end
+
+  class << AbsoluteSet
+    # @group Constructors
+    #########################################################################
+
+    # @return [AbsoluteSet]
+    def build(values)
+      count    = -1
+      universe = values.inject({}){|hash, v| hash.update(v => (count += 1)) }
+
+      new((1 << (count + 1)) - 1, universe)
+    end
+
+    # @endgroup
+    #########################################################################
+  end
+
+end