interval_notation 0.1.0

data/lib/interval_notation/interval_set.rb

@@ -0,0 +1,190 @@
+require_relative 'basic_intervals'
+require_relative 'error'
+require_relative 'operations'
+
+module IntervalNotation
+  class IntervalSet
+    attr_reader :intervals
+
+    # +IntervalSet.new+ accepts an ordered list of intervals.
+    # Intervals should be sorted from leftmost to rightmost and should not overlap.
+    # It's not recommended to use this constructor directly. Instead take a look at +IntervalNotation::Syntax+ module.
+    #
+    # Example:
+    #   # don't use this
+    #   IntervalSet.new([OpenOpenInterval.new(1,3), Point.new(5)])
+    #   # instead use
+    #   oo(1,3) | pt(5)
+
+    def initialize(intervals)
+      unless IntervalSet.check_valid?(intervals)
+        raise Error,  "IntervalSet.new accepts non-overlapping, sorted regions.\n" +
+                      "Try to use IntervalNotation.union(...) to create interval from overlapping or not-sorted intervals"
+      end
+      @intervals = intervals.freeze
+    end
+
+    # Method to create an interval set from string.
+    # It accepts strings obtained by +#to_s+ and many other formats.
+    # Spaces inside are ignored
+    # Intervals can be joined with +u+ or +U+ letters and unicode union character +∪+
+    # Points can go separately or be combined inside of single curly braces. Single point can go without braces at all
+    # +,+ and +;+ are both valid value separators.
+    # Infinity can be represented by +inf+, +infty+, +\infty+, +infinity+, +∞+ (each can go with or without sign)
+    # Empty set is empty string, word +Empty+ or unicode character +∅+
+    # +R+ represents whole 1-D line (-∞, ∞)
+    def self.from_string(str)
+      intervals = str.split(/[uU∪]/).flat_map{|interval_str|
+        BasicIntervals.from_string(interval_str)
+      }.map(&:to_interval_set)
+      Operations.union(intervals)
+    end
+
+    # Output standard mathematical notation of interval set in left-to-right order.
+    # Each singular point is listed separately in curly braces.
+    def to_s
+      @intervals.empty? ? EMPTY_SET_SYMBOL : intervals.map(&:to_s).join(UNION_SYMBOL)
+    end
+
+    def inspect # :nodoc:
+      to_s
+    end
+
+    # Checks whether an interval set contains certain position.
+    # Operation complexity is O(ln N), where N is a number of contiguous regions in an interval set
+    def include_position?(value)
+      interval = @intervals.bsearch{|interv| interv.to >= value }
+      interval && interval.include_position?(value)
+    end
+
+    # Checks whether an interval set contains another interval set. Alias: +#include?+
+    def contain?(other)
+      self.intersection(other) == other
+    end
+    alias include? contain?
+
+    # Checks whether an interval set is covered by another interval set. Alias: +#covered_by?+
+    def contained_by?(other)
+      self.intersection(other) == self
+    end
+    alias covered_by? contained_by?
+
+    # TODO: optimize if possible.
+    # Checks whether an interval set intersects another interval set. Alias: +#intersect?+
+    def intersect?(other)
+      ! intersection(other).empty?
+    end
+    alias overlap? intersect?
+
+    # Checks whether an interval set is empty
+    def empty?
+      @intervals.empty?
+    end
+
+    # Checks whether an interval set is contiguous (empty set treated contiguous)
+    def contiguous?
+      @intervals.size <= 1
+    end
+
+    # Total length of all intervals in set
+    def total_length
+      @intervals.map(&:length).inject(0, &:+)
+    end
+
+    # Number of connected components
+    def num_connected_components
+      @intervals.size
+    end
+
+    # TODO: optimize.
+    # Closure of an interval set
+    def closure
+      Operations.union(@intervals.map(&:closure).map(&:to_interval_set))
+    end
+
+    # Minimal contiguous interval, covering interval set
+    def covering_interval
+      if @intervals.size == 0
+        Empty
+      elsif @intervals.size == 1
+        self
+      else
+        BasicIntervals.interval_by_boundary_inclusion(@intervals.first.include_from?, @intervals.first.from,
+                                                      @intervals.last.include_to?, @intervals.last.to).to_interval_set
+      end
+    end
+
+    def hash # :nodoc:
+      @intervals.hash
+    end
+
+    def eql?(other) # :nodoc:
+      other.class.equal?(self.class) && intervals == other.intervals
+    end
+
+    # Intervals are equal only if they contain exactly the same intervals.
+    # Point inclusion is also considered
+    def ==(other)
+      other.is_a?(IntervalSet) && intervals == other.intervals
+    end
+
+    # Union of an interval set with another interval set +other+. Alias: +|+
+    # To unite many (tens of thousands intervals) intervals use +IntervalNotation::Operations.unite+ method.
+    # (+Operations.unite+ is dramatically faster than sequentially uniting intervals one-by-one)
+    def union(other)
+      Operations.union([self, other])
+    end
+
+    # Intersection of an interval set with another interval set +other+. Alias: +&+
+    # To unite many (tens of thousands intervals) intervals use +IntervalNotation::Operations.intersection+ method.
+    # (+Operations.intersection+ is dramatically faster than sequentially intersecting intervals one-by-one)
+    def intersection(other)
+      Operations.intersection([self, other])
+    end
+
+    # Difference between an interval set and another interval set +other+. Alias: +-+
+    def subtract(other)
+      Operations.combine([self, other], SubtractCombiner.new)
+    end
+
+    # Symmetric difference between an interval set and another interval set +other+. Alias: +^+
+    def symmetric_difference(other)
+      Operations.combine([self, other], SymmetricDifferenceCombiner.new)
+    end
+
+    # Complement of an interval set in R. Alias: +~+
+    def complement
+      R.subtract(self)
+    end
+
+    alias :& :intersection
+    alias :| :union
+    alias :- :subtract
+    alias :^ :symmetric_difference
+    alias :~ :complement
+
+
+    # Auxiliary method to share part of common interface with basic intervals
+    def to_interval_set # :nodoc:
+      self
+    end
+
+    class << self
+      # auxiliary method to check that intervals are sorted and don't overlap
+      def check_valid?(intervals)
+        intervals.each_cons(2).all? do |interval_1, interval_2|
+          interval_1.to <= interval_2.from && !(interval_1.to == interval_2.from && (interval_1.include_to? || interval_2.include_from?))
+        end
+      end
+
+      # An +IntervalSet.new_unsafe+ is a constructor which skips validation. It's designed mostly for internal use.
+      # It can be used when you are absolutely sure, that intervals are ordered and don't overlap.
+      def new_unsafe(intervals)
+        obj = allocate
+        obj.instance_variable_set(:@intervals, intervals.freeze)
+        obj
+      end
+    end
+  end
+  extend Operations
+end

data/lib/interval_notation/operations.rb

@@ -0,0 +1,62 @@
+require_relative 'interval_set'
+require_relative 'basic_intervals'
+require_relative 'combiners'
+
+module IntervalNotation
+  module Operations
+    # Internal method which combines intervals according to an algorithm given by a combiner.
+    # Combiner tells whether current section or point should be included to a new interval.
+    def combine(interval_sets, combiner)
+      points = interval_sets.each_with_index.flat_map{|interval_set, interval_set_index|
+        interval_set.intervals.flat_map{|interval|
+          interval.interval_boundaries(interval_set_index)
+        }
+      }.sort_by(&:value)
+
+      intervals = []
+
+      incl_from = nil
+      from = nil
+
+      points.chunk(&:value).each do |point_value, points_on_place|
+        combiner.pass(points_on_place)
+
+        if combiner.previous_state
+          if combiner.state
+            unless combiner.include_last_point
+              intervals << BasicIntervals.interval_by_boundary_inclusion(incl_from, from, false, point_value)
+              incl_from = false
+              from = point_value
+            end
+          else
+            to = point_value
+            incl_to = combiner.include_last_point
+            intervals << BasicIntervals.interval_by_boundary_inclusion(incl_from, from, incl_to, to)
+            from = nil # easier to find an error (but not necessary code)
+            incl_from = nil # ditto
+          end
+        else
+          if combiner.state
+            from = point_value
+            incl_from = combiner.include_last_point
+          else
+            intervals << BasicIntervals::Point.new(point_value)  if combiner.include_last_point
+          end
+        end
+      end
+      IntervalSet.new_unsafe(intervals)
+    end
+
+    # Union of multiple intervals.
+    def union(intervals)
+      combine(intervals, UnionCombiner.new(intervals.size))
+    end
+
+    # Intersection of multiple intervals
+    def intersection(intervals)
+      combine(intervals, IntersectCombiner.new(intervals.size))
+    end
+
+    module_function :combine, :union, :intersection
+  end
+end

data/lib/interval_notation/version.rb

@@ -0,0 +1,3 @@
+module IntervalNotation
+  VERSION = "0.1.0"
+end

data/lib/interval_notation.rb

@@ -0,0 +1,117 @@
+require_relative 'interval_notation/version'
+
+require_relative 'interval_notation/error'
+require_relative 'interval_notation/basic_intervals'
+require_relative 'interval_notation/combiners'
+require_relative 'interval_notation/interval_set'
+require_relative 'interval_notation/operations'
+
+module IntervalNotation
+  UNION_SYMBOL = '∪'.freeze
+  PLUS_INFINITY_SYMBOL = '+∞'.freeze
+  MINUS_INFINITY_SYMBOL = '-∞'.freeze
+  EMPTY_SET_SYMBOL = '∅'.freeze
+
+  R = IntervalSet.new_unsafe( [BasicIntervals::OpenOpenInterval.new(-Float::INFINITY, Float::INFINITY)] )
+  Empty = IntervalSet.new_unsafe([])
+
+  module Syntax
+    # Long syntax for interval factory methods
+    module Short
+      R = ::IntervalNotation::R
+      Empty = ::IntervalNotation::Empty
+
+      def int(str)
+        IntervalSet.from_string(str)
+      end
+
+      def oo(from, to)
+        IntervalSet.new_unsafe( [BasicIntervals::OpenOpenInterval.new(from, to)] )
+      end
+
+      def co(from, to)
+        IntervalSet.new_unsafe( [BasicIntervals::ClosedOpenInterval.new(from, to)] )
+      end
+
+      def oc(from, to)
+        IntervalSet.new_unsafe( [BasicIntervals::OpenClosedInterval.new(from, to)] )
+      end
+
+      def cc(from, to)
+        IntervalSet.new_unsafe( [BasicIntervals::ClosedClosedInterval.new(from, to)] )
+      end
+
+      def pt(value)
+        IntervalSet.new_unsafe( [BasicIntervals::Point.new(value)] )
+      end
+
+      def lt(value)
+        IntervalSet.new_unsafe( [BasicIntervals::OpenOpenInterval.new(-Float::INFINITY, value)] )
+      end
+
+      def le(value)
+        IntervalSet.new_unsafe( [BasicIntervals::OpenClosedInterval.new(-Float::INFINITY, value)] )
+      end
+
+      def gt(value)
+        IntervalSet.new_unsafe( [BasicIntervals::OpenOpenInterval.new(value, Float::INFINITY)] )
+      end
+
+      def ge(value)
+        IntervalSet.new_unsafe( [BasicIntervals::ClosedOpenInterval.new(value, Float::INFINITY)] )
+      end
+
+      module_function :oo, :co, :oc, :cc, :pt, :lt, :le, :gt, :ge, :int
+    end
+
+    # Long syntax for interval factory methods
+    module Long
+      R = ::IntervalNotation::R
+      Empty = ::IntervalNotation::Empty
+
+      def interval(str)
+        IntervalSet.from_string(str)
+      end
+
+      def open_open(from, to)
+        IntervalSet.new_unsafe( [BasicIntervals::OpenOpenInterval.new(from, to)] )
+      end
+
+      def closed_open(from, to)
+        IntervalSet.new_unsafe( [BasicIntervals::ClosedOpenInterval.new(from, to)] )
+      end
+
+      def open_closed(from, to)
+        IntervalSet.new_unsafe( [BasicIntervals::OpenClosedInterval.new(from, to)] )
+      end
+
+      def closed_closed(from, to)
+        IntervalSet.new_unsafe( [BasicIntervals::ClosedClosedInterval.new(from, to)] )
+      end
+
+      def point(value)
+        IntervalSet.new_unsafe( [BasicIntervals::Point.new(value)] )
+      end
+
+      def less_than(value)
+        IntervalSet.new_unsafe( [BasicIntervals::OpenOpenInterval.new(-Float::INFINITY, value)] )
+      end
+
+      def less_than_or_equal_to(value)
+        IntervalSet.new_unsafe( [BasicIntervals::OpenClosedInterval.new(-Float::INFINITY, value)] )
+      end
+
+      def greater_than(value)
+        IntervalSet.new_unsafe( [BasicIntervals::OpenOpenInterval.new(value, Float::INFINITY)] )
+      end
+
+      def greater_than_or_equal_to(value)
+        IntervalSet.new_unsafe( [BasicIntervals::ClosedOpenInterval.new(value, Float::INFINITY)] )
+      end
+
+      module_function :open_open, :closed_open, :open_closed, :closed_closed, :point,
+                      :less_than, :less_than_or_equal_to, :greater_than, :greater_than_or_equal_to,
+                      :interval
+    end
+  end
+end

data/spec/basic_intervals_spec.rb

@@ -0,0 +1,140 @@
+require 'interval_notation'
+
+include IntervalNotation
+include IntervalNotation::BasicIntervals
+include IntervalNotation::Syntax::Short
+
+describe IntervalNotation do
+  describe OpenOpenInterval do
+    describe '.new' do
+      { [1,3] => :ok,
+        [1, Float::INFINITY] => :ok,
+        [-Float::INFINITY, 1] => :ok,
+        [-Float::INFINITY, Float::INFINITY] => :ok,
+
+        [1,1] => :fail,
+        [3,1] => :fail,
+        [1,-Float::INFINITY] => :fail,
+        [Float::INFINITY, 1] => :fail,
+        [-Float::INFINITY, -Float::INFINITY] => :fail,
+        [Float::INFINITY, Float::INFINITY] => :fail,
+        [Float::INFINITY, -Float::INFINITY] => :fail,
+      }.each do |(from, to), result|
+        if result == :ok
+          it "OpenOpenInterval.new(#{from}, #{to}) should not raise" do 
+            expect{ OpenOpenInterval.new(from, to) }.not_to raise_error
+          end
+        elsif result == :fail
+          it "OpenOpenInterval.OpenOpenInterval(#{from}, #{to}) should raise" do
+            expect{ OpenOpenInterval.new(from, to) }.to raise_error Error
+          end
+        else
+          raise 'Incorrect test'
+        end
+      end
+    end
+  end
+
+
+  describe OpenClosedInterval do
+    describe '.new' do
+      { [1,3] => :ok,
+        [-Float::INFINITY, 1] => :ok,
+
+        [1, Float::INFINITY] => :fail,
+        [-Float::INFINITY, Float::INFINITY] => :fail,
+        [1,1] => :fail,
+        [3,1] => :fail,
+        [1,-Float::INFINITY] => :fail,
+        [Float::INFINITY, 1] => :fail,
+        [-Float::INFINITY, -Float::INFINITY] => :fail,
+        [Float::INFINITY, Float::INFINITY] => :fail,
+        [Float::INFINITY, -Float::INFINITY] => :fail,
+      }.each do |(from, to), result|
+        if result == :ok
+          it "OpenClosedInterval.new(#{from}, #{to}) should not raise" do 
+            expect{ OpenClosedInterval.new(from, to) }.not_to raise_error
+          end
+        elsif result == :fail
+          it "OpenOpenInterval.new(#{from}, #{to}) should raise" do
+            expect{ OpenClosedInterval.new(from, to) }.to raise_error Error
+          end
+        else
+          raise 'Incorrect test'
+        end
+      end
+    end
+  end
+
+
+  describe ClosedOpenInterval do
+    describe '.new' do
+      { [1,3] => :ok,
+        [1, Float::INFINITY] => :ok,
+
+        [-Float::INFINITY, 1] => :fail,
+        [-Float::INFINITY, Float::INFINITY] => :fail,
+        [1,1] => :fail,
+        [3,1] => :fail,
+        [1,-Float::INFINITY] => :fail,
+        [Float::INFINITY, 1] => :fail,
+        [-Float::INFINITY, -Float::INFINITY] => :fail,
+        [Float::INFINITY, Float::INFINITY] => :fail,
+        [Float::INFINITY, -Float::INFINITY] => :fail,
+      }.each do |(from, to), result|
+        if result == :ok
+          it "ClosedOpenInterval.new(#{from}, #{to}) should not raise" do 
+            expect{ ClosedOpenInterval.new(from, to) }.not_to raise_error
+          end
+        elsif result == :fail
+          it "OpenOpenInterval.new(#{from}, #{to}) should raise" do
+            expect{ ClosedOpenInterval.new(from, to) }.to raise_error Error
+          end
+        else
+          raise 'Incorrect test'
+        end
+      end
+    end
+  end
+
+
+  describe ClosedClosedInterval do
+    describe '.new' do
+      { [1,3] => :ok,
+
+        [1, Float::INFINITY] => :fail,
+        [-Float::INFINITY, 1] => :fail,
+        [-Float::INFINITY, Float::INFINITY] => :fail,
+        [1,1] => :fail,
+        [3,1] => :fail,
+        [1,-Float::INFINITY] => :fail,
+        [Float::INFINITY, 1] => :fail,
+        [-Float::INFINITY, -Float::INFINITY] => :fail,
+        [Float::INFINITY, Float::INFINITY] => :fail,
+        [Float::INFINITY, -Float::INFINITY] => :fail,
+      }.each do |(from, to), result|
+        if result == :ok
+          it "ClosedClosedInterval.new(#{from}, #{to}) should not raise" do 
+            expect{ ClosedClosedInterval.new(from, to) }.not_to raise_error
+          end
+        elsif result == :fail
+          it "OpenOpenInterval.new(#{from}, #{to}) should raise" do
+            expect{ ClosedClosedInterval.new(from, to) }.to raise_error Error
+          end
+        else
+          raise 'Incorrect test'
+        end
+      end
+    end
+  end
+
+  describe Point do
+    it 'should not raise if finite' do
+      expect{ Point.new(3) }.not_to raise_error      
+    end
+    it 'should raise if infinite' do
+      expect{ Point.new(-Float::INFINITY) }.to raise_error      
+      expect{ Point.new(Float::INFINITY) }.to raise_error      
+    end
+  end
+end