range_with_gaps 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Timothy Elliott
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,94 @@
+## Range With Gaps: A ruby class to work with discontinuous ranges
+
+The RangeWithGaps class lets you easily collect many ranges into one. It accepts
+individual values (3, 4, 5) as well as ranges (2..3000) and will fold them
+together to efficiently work with them as a single set of ranges.
+
+Once you have inserted your values and ranges, you can perform logic operations
+such as union and intersection. This is particularly useful for finding
+overlapping time spans.
+
+I took care to allow for non-sequential ranges, such as ranges of floats, to
+work with this class. Non-sequential ranges are ranges for data types that don't
+have a succ method.
+
+This gem adds only a single constant to the Ruby namespace; RangeWithGaps.
+
+## Usage
+
+In order to include the class
+
+    require 'range_with_gaps'
+
+Optionally, you can add math operations to the Range class:
+
+    require 'range_with_gaps/core_ext/range'
+
+Initialize a range with gaps, the order doesn't matter, and overlapping values
+are folded together:
+
+    range_with_gaps = RangeWithGaps.new 55...900, 1..34, 22, 23
+
+Add values to a range with gaps:
+
+    range_with_gaps << 0.4
+    range_with_gaps.add(Time.now...(Time.now + 5000))
+
+Delete values from a range with gaps:
+
+    range_with_gaps.delete(Date.today - 15)
+    range_with_gaps.delete(50..3000)
+
+Fast calculation of the size of a range with gaps:
+
+    range_with_gaps.size
+
+Use logic operations on a range with gaps:
+
+    # returns a range with gaps of all overlapping ranges
+    range_with_gaps_one & range_with_gaps_two
+    range_with_gaps & ((Date.today - 30)..Date.today)
+
+    # returns a range with gaps of all ranges combined
+    range_with_gaps_one | range_with_gaps_two
+
+I created this class in order to simplify the calculation of billing periods in
+a rails project that uses a audit table:
+
+    require 'range_with_gaps'
+
+    def get_premium_time_spans
+      premium_time_spans = RangeWithGaps.new
+
+      # Get all events from an audit table, i.e. every time a customer toggles
+      # the premium flag on their account.
+      premium_toggles = Customer.audits.premium_column
+
+      # We only care when premium was on, so eat the first event if it was a
+      # toggle to a non-premium account.
+      premium_toggles.shift unless premium_toggles.first.value
+
+      premium_toggles.each_slice(2) do |toggle_pair|
+        # If we only got one element in the slice then inject a fake toggle
+        # at the end of the span
+        span_end = toggle_pair[1] ? toggle_pair[1].created_at : Time.now
+
+        premium_time_spans.add(toggle_pair[0].created_at..span_end)
+      end
+
+      premium_time_spans
+    end
+
+    premium_time_spans = get_premium_time_spans
+
+    # Calculate how long the customer had a premium account in January
+    january = Time.local(2010, 1, 1)...Time.local(2010, 2, 1)
+    puts "January Premium: #{(premium_time_spans & january).size} seconds"
+
+    # Calculate how long the customer had a premium account during the two last
+    # service outages
+    disk_recovery = Time.local(2009, 12, 24, 15, 30)..Time.local(2009, 12, 24, 16)
+    net_outage = Time.local(2010, 2, 1, 12, 15)..Time.local(2010, 2, 2, 2, 30)
+    outages = RangeWithGaps.new disk_recovery, net_outage
+
+    puts "Outage Premium: #{(premium_time_spans & outages).size} seconds"

data/lib/range_with_gaps.rb

@@ -0,0 +1,122 @@
+require 'range_with_gaps/range_with_math'
+
+class RangeWithGaps
+  def initialize(*ranges)
+    @ranges = []
+    ranges.each{|r| self.add r}
+  end
+
+  def dup
+    self.class.new *to_a
+  end
+
+  def ==(rset)
+    @ranges == rset.instance_variable_get(:@ranges)
+  end
+
+  def add(o)
+    case o
+    when Range then _add(o)
+    when self.class, Enumerable then o.each{|b| add b}
+    else add(o..o)
+    end
+
+    return self
+  end
+  alias << add
+
+  def delete(o)
+    case o
+    when Range then _delete(o)
+    when self.class, Enumerable then o.each{|s| delete s}
+    else delete(o..o)
+    end
+
+    return self
+  end
+
+  def |(enum)
+    dup.add(enum)
+  end
+  alias + |
+  alias union |
+
+  def -(enum)
+    dup.delete(enum)
+  end
+  alias difference -
+
+  def &(o)
+    ret = self.class.new
+
+    case o
+    when Range
+      @ranges.each do |r|
+        intersection = r & o
+        ret.add intersection if intersection
+      end
+      ret
+    when self.class, Enumerable
+      o.each do |i|
+        intersection = self & i
+        ret.add intersection if intersection
+      end
+      ret
+    else self&(o..o)
+    end
+  end
+  alias intersection &
+
+  def include?(elem)
+    @ranges.any?{|r| r.include? elem}
+  end
+
+  def to_a
+    @ranges.map{ |r| r.to_range }
+  end
+
+  def each
+    to_a.each{|o| yield o}
+  end
+
+  def size
+    @ranges.inject(0){|sum, n| sum + n.size}
+  end
+
+  def entries
+    @ranges.map{|r| r.to_a}.flatten
+  end
+
+  def empty?
+    @ranges.empty?
+  end
+
+  private
+
+  def _add(new_range)
+    new_range = RangeWithMath.from_range new_range
+    return if new_range.empty?
+
+    inserted = false
+
+    @ranges.each_with_index do |r, i|
+      if r.overlap?(new_range) || r.adjacent?(new_range)
+        new_range = new_range | r
+        @ranges[i] = nil
+      elsif r.first > new_range.first
+        @ranges.insert(i, new_range)
+        inserted = true
+        break
+      end
+    end
+
+    @ranges << new_range unless inserted
+    @ranges.compact!
+  end
+
+  def _delete(o)
+    @ranges.map!{|r| r - o}
+    @ranges.flatten!
+    @ranges.compact!
+  end
+end

data/lib/range_with_gaps/core_ext/range.rb

@@ -0,0 +1,5 @@
+require 'range_with_gaps/range_math'
+
+class Range
+  include RangeWithGaps::RangeMath
+end

data/lib/range_with_gaps/range_math.rb

@@ -0,0 +1,119 @@
+class RangeWithGaps
+  module RangeMath
+    # From Ruby Facets. Returns true if this range overlaps with another range.
+    def overlap?(enum)
+      include?(enum.first) or enum.include?(first)
+    end
+
+    # Returns true if this range completely covers the given range.
+    def mask?(enum)
+      higher_or_equal_rhs_as?(enum) && include?(enum.first)
+    end
+
+    # Returns a new range containing all elements that are common to both.
+    def &(enum)
+      enum.is_a?(Enumerable) or raise ArgumentError, "value must be enumerable"
+      return nil unless overlap?(enum)
+
+      first_val = [first, enum.first].max
+      hi = lower_or_equal_rhs_as?(enum) ? self : enum
+
+      self.class.new first_val, hi.last, hi.exclude_end?
+    end
+
+    # Returns a new range built by merging self and the given range. If they are
+    # non-overlapping then we return an array of ranges.
+    def |(enum)
+      if overlap?(enum) || adjacent?(enum)
+        first_val = [first, enum.first].min
+        hi = higher_or_equal_rhs_as?(enum) ? self : enum
+
+        self.class.new first_val, hi.last, hi.exclude_end?
+      else
+        return self, enum
+      end
+    end
+
+    # Return true if this range and the other range are adjacent to each other.
+    # Non-sequential ranges that exclude an end can not be adjacent.
+    def adjacent?(enum)
+      adjacent_before?(enum) || enum.adjacent_before?(self)
+    end
+
+    # Returns a new range by subtracting the given range from self. If all
+    # elements are removed then returns nil. If the subtracting range results
+    # in a split of self then we return two ranges in a sorted array. Only works
+    # on ranges that represent a sequence of values and respond to succ.
+    def -(enum)
+      return self.dup unless overlap?(enum)
+
+      if enum.mask?(self)
+        nil
+      elsif first >= enum.first
+        ltrim enum
+      elsif lower_or_equal_rhs_as?(enum)
+        rtrim enum
+      else
+        [rtrim(enum), ltrim(enum)]
+      end
+    end
+
+    # Return the physical dimension of the range. Only works with ranges that
+    # represent a sequence. This can be confusing for ranges of floats, since
+    # (0.0..42.0) will result in the same size as (0.0...42.0). Won't work with
+    # ranges that don't support the minus operator.
+    def size
+      (sequential? ? one_after_max : last) - first
+    end
+
+    # Returns true if this range has nothing. This only happens with ranges such
+    # as (0...0)
+    def empty?
+      last == first && exclude_end?
+    end
+
+    private
+
+    # Uses the given enumerable to left trim this range
+    def ltrim(enum)
+      first_val = sequential? ? enum.one_after_max : enum.last
+      self.class.new first_val, last, exclude_end?
+    end
+
+    # Uses the given enumerable to right trim this range
+    def rtrim(enum)
+      self.class.new first, enum.first, true
+    end
+
+    # Return true if this range is sequential and its elements respond to succ.
+    def sequential?
+      first.respond_to?(:succ)
+    end
+
+    # Return true if this range has a higher or equal rhs as the given range
+    def higher_or_equal_rhs_as?(enum)
+      last > enum.last || (last == enum.last && (!exclude_end? || enum.exclude_end?))
+    end
+
+    # Return true if this range has a lower or equal rhs as the given range
+    def lower_or_equal_rhs_as?(enum)
+      last < enum.last || (last == enum.last && (exclude_end? || !enum.exclude_end?))
+    end
+
+    protected
+
+    # Return the value that is one after the max value. This allows us to compare
+    # ranges with our without exclude_end? set to true.
+    def one_after_max
+      exclude_end? ? last : last.succ
+    end
+
+    def adjacent_before?(enum)
+      if sequential?
+        one_after_max == enum.first
+      else
+        last == enum.first && !exclude_end?
+      end
+    end
+  end
+end

data/lib/range_with_gaps/range_with_math.rb

@@ -0,0 +1,15 @@
+require 'range_with_gaps/range_math'
+
+class RangeWithGaps
+  class RangeWithMath < Range
+    include RangeMath
+
+    def self.from_range(range)
+      new range.begin, range.end, range.exclude_end?
+    end
+
+    def to_range
+      Range.new self.begin, self.end, exclude_end?
+    end
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification 
+name: range_with_gaps
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Timothy Elliott
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-18 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: The RangeWithGaps class lets you easily collect many ranges into one.You can perform logic operations such as union and intersection on ranges with gaps.
+email: 
+- tle@holymonkey.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/range_with_gaps.rb
+- lib/range_with_gaps/range_with_math.rb
+- lib/range_with_gaps/range_math.rb
+- lib/range_with_gaps/core_ext/range.rb
+- LICENSE
+- README.markdown
+has_rdoc: true
+homepage: http://github.com/ender672/range_with_gaps
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.3.5
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Like Ranges, but with gaps.
+test_files: []
+