cantor 1.2.0

data/lib/cantor/abstract_set.rb

@@ -0,0 +1,174 @@
+module Cantor
+
+  #
+  # {AbstractSet} describes the common interface implemented by its concrete
+  # subclasses. The two main implementations are {RelativeSet} and
+  # {AbsoluteSet} which are each optimized for different kinds of set
+  # operations.
+  #
+  class AbstractSet
+
+    # True if the set includes the given `object`
+    # abstract :include?, :args => %w(object)
+
+    def member?(object)
+      include?(object)
+    end
+
+    def contain?(object)
+      include?(object)
+    end
+
+    # True if the set does not include the given `object`
+    def exclude?(object)
+      not include?(object)
+    end
+
+    # True if {#size} `< Infinity`
+    # abstract :finite?
+
+    # True if {#size} `== 0`
+    # abstract :empty?
+
+    # Returns the number of elements in the set
+    #
+    # @return [Numeric]
+    # abstract :size
+
+    # Returns the `other` set, converting it to an {AbstractSet} if it isn't
+    # already.
+    #
+    # @return [AbstractSet]
+    # abstract :replace, :args => %w(other)
+
+    # True if the set contains infinitely many elements
+    def infinite?
+      not finite?
+    end
+
+    # @group Set Operations
+    #########################################################################
+
+    # (see AbstractSet#~)
+    # abstract :complement
+
+    # (see AbstractSet#|)
+    # abstract :union, :args => %w(other)
+
+    # (see AbstractSet#-)
+    # abstract :difference, :args => %w(other)
+
+    # (see AbstractSet#^)
+    # abstract :symmetric_difference, :args => %w(other)
+
+    # (see AbstractSet#&)
+    # abstract :intersection, :args => %w(other)
+
+    # Computes the union of two sets: the set of elements in _either_ or
+    # _both_ sets
+    #
+    # @return [AbstractSet]
+    #
+    # @see http://en.wikipedia.org/wiki/Union_(set_theory)
+    def |(other) union(other) end
+
+    # (see AbstractSet#|)
+    def +(other) union(other) end
+
+    # Computes the difference of two sets: the set of elements elements in
+    # _this_ set and not the _other_.
+    #
+    # @return [AbstractSet]
+    #
+    # @see http://en.wikipedia.org/wiki/Set_difference#Relative_complement
+    def -(other) difference(other) end
+
+    # Computes the complement of the set: the set of elements _not_ in this
+    # set
+    #
+    # @return [AbstractSet]
+    #
+    # @see http://en.wikipedia.org/wiki/Complement_(set_theory)
+    def ~; complement end
+
+    # Computes the symmetric difference of two sets: the set of elements which
+    # are in _either_ of the two sets but _not_ in both.
+    #
+    # @return [AbstractSet]
+    #
+    # @see http://en.wikipedia.org/wiki/Symmetric_difference
+    def ^(other) symmetric_difference(other) end
+
+    # Computes the intersection of two sets: the set of elements common
+    # between _both_ sets.
+    #
+    # @return [AbstractSet]
+    #
+    # @see http://en.wikipedia.org/wiki/Intersection_(set_theory)
+    def &(other) intersection(other) end
+
+    # @endgroup
+    #########################################################################
+
+    # @group Set Ordering
+    #########################################################################
+
+    # True if every element in this set also belongs to the `other` set
+    #
+    # @see http://en.wikipedia.org/wiki/Subset
+    def subset?(other)
+      intersection(other) == self
+    end
+
+    # True if this set is a subset of the `other` set and there exists at
+    # least one element in the `other` set that doesn't belong to this set
+    #
+    # @see http://en.wikipedia.org/wiki/Subset
+    def proper_subset?(other)
+      other.size > size and subset?(other)
+    end
+
+    # True if every element in the `other` set also belongs to this set
+    #
+    # @see http://en.wikipedia.org/wiki/Subset
+    def superset?(other)
+      intersection(other) == other
+    end
+
+    # True if this set is a superset of the `other` set and there exists at
+    # least one element in this set that doesn't belong to the `other` set
+    #
+    # @see http://en.wikipedia.org/wiki/Subset
+    def proper_superset?(other)
+      other.size < size and superset?(other)
+    end
+
+    # True if this and the `other` set have no common elements
+    #
+    # @see http://en.wikipedia.org/wiki/Disjoint_sets
+    def disjoint?(other)
+      intersection(other).empty?
+    end
+
+    # True if this and the `other` set have exactly the same elements
+    #
+    # @return [Boolean]
+    # abstract :==, :args => %w(other)
+
+    # (see AbstractSet#proper_subset?)
+    def <(other) proper_subset?(other) end
+
+    # (see AbstractSet#proper_superset?)
+    def >(other) proper_superset?(other) end
+
+    # (see AbstractSet#subset?)
+    def <=(other) subset?(other) end
+
+    # (see AbstractSet#superset?)
+    def >=(other) superset?(other) end
+
+    # @endgroup
+    #########################################################################
+  end
+
+end

data/lib/cantor/null_set.rb

@@ -0,0 +1,123 @@
+# encoding: UTF-8
+
+module Cantor
+
+  # @private
+  NullSet = Class.new(RelativeSet) do
+
+    def initialize
+    end
+
+    # @return [NullSet]
+    def build
+      self
+    end
+
+    # Yields each element in the set to the implicit block argument. Since
+    # there are no elements, the block is never executed
+    #
+    # @return [void]
+    def each
+    end
+
+    # Returns an {Array} containing each element in this set. Since there are
+    # no elements, the {Array} is empty
+    #
+    # @return [Array]
+    def to_a
+      []
+    end
+
+    # @return false
+    def include?(other)
+      false
+    end
+
+    # @return true
+    def finite?
+      true
+    end
+
+    # @return [Set] other
+    def replace(other)
+      Cantor.build(other)
+    end
+
+    # @return 0
+    def size
+      0
+    end
+
+    # @return true
+    def empty?
+      true
+    end
+
+    # @group Set Operations
+    #########################################################################
+
+    # @return self
+    def map
+      self
+    end
+
+    # @return self
+    def select
+      self
+    end
+
+    # @return self
+    def reject
+      self
+    end
+
+    # @return UniversalSet
+    def complement
+      # ¬∅ = U
+      UniversalSet.build
+    end
+
+    # @return self
+    def intersection(other)
+      # ∅ ∩ A = ∅
+      self
+    end
+
+    # @return [Set] other
+    def union(other)
+      # ∅ ∪ A = A
+      Cantor.build(other)
+    end
+
+    # @return self
+    def difference(other)
+      # ∅ ∖ A = A
+      self
+    end
+
+    # @return [Set] other
+    def symmetric_difference(other)
+      # ∅ ⊖ A = A
+      Cantor.build(other)
+    end
+
+    # @group Set Ordering
+    #########################################################################
+
+    def ==(other)
+      eql?(other) or other.empty?
+    end
+
+    # @group Pretty Printing
+    #########################################################################
+
+    # @return [String]
+    def inspect
+      "NullSet"
+    end
+
+    # @endgroup
+    #########################################################################
+  end.new
+
+end

data/lib/cantor/relative_complement.rb

@@ -0,0 +1,135 @@
+# encoding: UTF-8
+
+module Cantor
+
+  #
+  # This data type is an infinite and non-enumerable set of values that
+  # encodes the complement of a {RelativeSet}
+  #
+  class RelativeComplement < AbstractSet
+
+    def initialize(complement)
+      @complement = complement
+    end
+
+    # (see AbstractSet#include?)
+    def include?(object)
+      not @complement.include?(object)
+    end
+
+    # (see AbstractSet#size)
+    # @return Infinity
+    def size
+      1.0 / 0.0
+    end
+
+    # (see AbstractSet#finite?)
+    # @return false
+    def finite?
+      false
+    end
+
+    # (see AbstractSet#empty?)
+    # @return false
+    def empty?
+      false
+    end
+
+    # (see AbstractSet#replace)
+    def replace(other)
+      Cantor.build(other)
+    end
+
+    # @group Set Operations
+    #########################################################################
+
+    # (see AbstractSet#complement)
+    def complement
+      # ¬(¬A) = A
+      @complement
+    end
+
+    # (see AbstractSet#intersection)
+    def intersection(other)
+      if other.is_a?(RelativeComplement)
+        # ¬A ∩ ¬B = ¬(A ∪ B)
+        complement.union(other.complement).complement
+      else
+        # ¬A ∩ B = B ∖ A
+        Cantor.build(other).difference(complement)
+      end
+    end
+
+    # (see AbstractSet#union)
+    def union(other)
+      if other.is_a?(RelativeComplement)
+        # ¬A ∪ ¬B = ¬(A ∩ B)
+        complement.intersection(other.complement).complement
+      else
+        # ¬A ∪ B = ¬(A ∖ B)
+        complement.difference(Cantor.build(other)).complement
+      end
+    end
+
+    # (see AbstractSet#symmetric_difference)
+    def symmetric_difference(other)
+      if other.is_a?(RelativeComplement)
+        # ¬A ⊖ ¬B = (¬A ∖ ¬B) ∪ (¬B ∖ ¬A)
+        #         =  (B ∖ A)  ∪ (A ∖ B)
+        #         = A ⊖ B
+        complement.symmetric_difference(other.complement)
+      else
+        # ¬A ⊖ B = (¬A ∖ B)  ∪ (B ∖ ¬A)
+        #        = (¬A ∩ ¬B) ∪ (B ∩ A)
+        #        = (¬B ∖ A)  ∪ (A ∖ ¬B)
+        #        = A ⊖ ¬B
+        other = Cantor.build(other)
+
+        intersection(other.complement).
+          union(other.intersection(complement))
+      end
+    end
+
+    # (see AbstractSet#difference)
+    def difference(other)
+      if other.is_a?(RelativeComplement)
+        # ¬A ∖ ¬B = ¬A ∩ B = B ∖ A
+        other.complement.difference(complement)
+      else
+        # ¬A ∖ B = ¬A ∩ ¬B = ¬(A ∪ B)
+        complement.union(Cantor.build(other)).complement
+      end
+    end
+
+    # @group Set Ordering
+    #########################################################################
+
+    # (see AbstractSet#proper_subset?)
+    def proper_subset?(other)
+      other.is_a?(RelativeComplement) and intersection(other) == self
+    end
+
+    # (see AbstractSet#proper_superset?)
+    def proper_superset?(other)
+      other.is_a?(RelativeComplement) and intersection(other) == other
+    end
+
+    # (see AbstractSet#==)
+    def ==(other)
+      eql?(other) or
+       (other.is_a?(RelativeComplement) and complement == other.complement)
+    end
+
+    # @group Pretty Printing
+    #########################################################################
+
+    # @return [String]
+    def inspect
+      "RelativeComplement(#{@complement.inspect})"
+    end
+
+    # @endgroup
+    #########################################################################
+  end
+
+end

data/lib/cantor/relative_set.rb

@@ -0,0 +1,267 @@
+# encoding: UTF-8
+
+module Cantor
+
+  #
+  # This data type encodes a set of unique values that belong to an _infinite_
+  # universe of possible values (aka domain). Set operations generally perform
+  # worse than {AbsoluteSet}, as they operate on {Hash} values and require
+  # iterating the underlying {Hash} of at least one of the two sets in `O(n)`
+  # time.
+  #
+  # This is suitable for sets that don't have an inherently restricted domain
+  # (eg sets of arbitrary {String} values), including those where the domain
+  # is significantly large compared to the typical size of sets built from
+  # those values. {RelativeSet} also requires only a single step to execute
+  # {#include?}, while {AbsoluteSet} requires two.
+  #
+  class RelativeSet < AbstractSet
+    include Enumerable
+
+    def initialize(hash)
+      @hash = hash
+    end
+
+    # Yields each element in the set to the implicit block argument.
+    #
+    # @return [void]
+    def each
+      @hash.keys.each{|o| yield o }
+    end
+
+    # Returns an {Array} containing each element in this set
+    #
+    # @return [Array]
+    def to_a
+      @hash.keys
+    end
+
+    # (see AbstractSet#include?)
+    def include?(object)
+      @hash.include?(object)
+    end
+
+    # (see AbstractSet#finite?)
+    #
+    # @return true
+    def finite?
+      true
+    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
+      @hash.keys.first
+    end
+
+    # (see AbstractSet#replace)
+    def replace(other)
+      Cantor.build(other)
+    end
+
+    # (see AbstractSet#size)
+    def size
+      @hash.size
+    end
+
+    # (see AbstractSet#empty?)
+    def empty?
+      @hash.empty?
+    end
+
+    # @group Set Operations
+    #########################################################################
+
+    # @return [RelativeSet]
+    def map
+      RelativeSet.new(@hash.keys.inject({}) do |hash, key|
+        hash[yield(key)] = true
+        hash
+      end)
+    end
+
+    # @return [RelativeSet]
+    def select
+      RelativeSet.new(@hash.clone.delete_if{|o,_| not yield(o) })
+    end
+
+    # @return [RelativeSet]
+    def reject
+      RelativeSet.new(@hash.clone.delete_if{|o,_| yield(o) })
+    end
+
+    # (see AbstractSet#complement)
+    # @return [RelativeComplement]
+    def complement
+      RelativeComplement.new(self)
+    end
+
+    # (see AbstractSet#intersection)
+    def intersection(other)
+      if other.is_a?(RelativeComplement)
+        # A ∩ ¬B = ¬B ∩ A
+        other.intersection(self)
+      elsif other.is_a?(AbstractSet)
+        if other.is_a?(RelativeSet) and size > other.size
+          # For efficiency, iterate the smaller of the two sets: A ∩ B = B ∩ A
+          other.intersection(self)
+        elsif other.empty?
+          # A ∩ ∅ = ∅
+          NullSet.build
+        else
+          hash = @hash.clone.delete_if{|o,_| not other.include?(o) }
+
+          if hash.empty?
+            NullSet.build
+          else
+            RelativeSet.new(hash)
+          end
+        end
+      else
+        intersection(Cantor.build(other))
+      end
+    end
+
+    # (see AbstractSet#intersection)
+    def union(other)
+      if other.is_a?(RelativeComplement)
+        # A ∪ ¬B = ¬B ∪ A
+        other.union(self)
+      elsif other.is_a?(AbstractSet)
+        unless other.is_a?(RelativeSet) and size < other.size
+          hash = other.inject(@hash.clone){|h,o| h[o] = true; h }
+
+          if hash.empty?
+            NullSet.build
+          else
+            RelativeSet.new(hash)
+          end
+        else
+          # For efficiency, iterate the smaller of the two sets: A ∪ B = B ∪ A
+          if other.empty?
+            self
+          else
+            other.union(self)
+          end
+        end
+      else
+        union(Cantor.build(other))
+      end
+    end
+
+    # (see AbstractSet#difference)
+    def difference(other)
+      if other.is_a?(RelativeComplement)
+        # A ∖ ¬B = A ∩ B
+        intersection(other.complement)
+      elsif other.is_a?(AbstractSet)
+        if other.empty?
+          self
+        else
+          # A ∖ B = A ∩ ¬B
+          hash = @hash.clone.delete_if{|o,_| other.include?(o) }
+
+          if hash.empty?
+            NullSet.build
+          else
+            RelativeSet.new(hash)
+          end
+        end
+      else
+        difference(Cantor.build(other))
+      end
+    end
+
+    # (see AbstractSet#symmetric_difference)
+    def symmetric_difference(other)
+      if other.is_a?(RelativeComplement)
+        # A ⊖ ~B = (A ∖ ¬B) | (¬B ∖ A)
+        #        = (A ∩ B)  | (¬B ∩ ¬A)
+        #        = (B ∖ ¬A) | (¬A ∖ B)
+        #        = ~A ⊖ B
+        intersection(other.complement).
+          union(other.intersection(complement))
+      else
+        # A ⊖ B = (A ∖ B) | (B ∖ A)
+        #       = (A ∪ B) - (A ∩ B)
+        other = Cantor.build(other)
+
+        if other.empty?
+          self
+        else
+          union(other).difference(intersection(other))
+        end
+      end
+    end
+
+    # @group Set Ordering
+    #########################################################################
+
+    # (see AbstractSet#==)
+    def ==(other)
+      eql?(other) or
+        (other.is_a?(Enumerable) and
+         @hash.keys == other.to_a)
+    end
+
+    # @group Pretty Printing
+    #########################################################################
+
+    # @return [void]
+    def pretty_print(q)
+      q.text("RelativeSet[#{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
+      "RelativeSet(#{to_a.map(&:inspect).join(', ')})"
+    end
+
+    # @endgroup
+    #########################################################################
+  end
+
+  class << RelativeSet
+    # @group Constructors
+    #########################################################################
+
+    # @return [RelativeSet]
+    def build(object)
+      if object.is_a?(RelativeSet)
+        object
+      elsif object.is_a?(Enumerable)
+        if object.empty?
+          NullSet.build
+        elsif object.is_a?(Hash)
+          new(object)
+        else
+          new(object.inject({}){|h,o| h[o] = true; h })
+        end
+      else
+        raise TypeError
+      end
+    end
+
+    # @endgroup
+    #########################################################################
+  end
+
+end