extrarange 1.0.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Timothy Elliott, Alan Franzoni
+
+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,115 @@
+# Extrarange: enhancing the Ruby range experience.
+
+
+## SparseRange
+
+The SparseRange 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.
+
+The class aims at being a drop-in replacement of a standard range; it exposes the very
+same interface of the builtin ruby range. There're currently some caveats, check them below.
+
+### Usage
+
+Require and include the module
+
+    require 'extrarange'
+    include ExtraRange
+
+Initialize a range with gaps, the order doesn't matter, and overlapping values
+are folded together:
+
+    extrarange = SparseRange.new 55...900, 1..34, 22, 23
+
+Add values to a range with gaps:
+
+    extrarange << 0.4
+    extrarange.add(Time.now...(Time.now + 5000))
+
+Delete values from a range with gaps:
+
+    extrarange.delete(Date.today - 15)
+    extrarange.delete(50..3000)
+
+Fast calculation of the size of a range with gaps:
+
+    extrarange.size
+
+Use logic operations on a range with gaps:
+
+    # returns a range with gaps of all overlapping ranges
+    extrarange_one & extrarange_two
+    extrarange & ((Date.today - 30)..Date.today)
+
+    # returns a range with gaps of all ranges combined
+    extrarange_one | extrarange_two
+
+I created this class in order to simplify the calculation of billing periods in
+a rails project that uses a audit table:
+
+    require 'extrarange'
+    include ExtraRange
+
+    def get_premium_time_spans
+      premium_time_spans = SparseRange.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 = SparseRange.new disk_recovery, net_outage
+
+    puts "Outage Premium: #{(premium_time_spans & outages).size} seconds"
+
+### Caveats
+- SparseRange is currently mutable. Be careful whenever using it as an hash key as it may produce unexpected results.
+- If *any* range within the sparse range doesn't support min/max (e.g. reverse ranges like 3..1), then the sparse
+  range won't support them as well. I hope to fix such behaviour in a future version.
+- cover? is unoptimized and may take a lot of time in large sparse ranges.
+
+## Credits
+
+This is a fork of the [range_with_gaps](https://github.com/ender672/range_with_gaps) gem by Timothy Elliott.
+
+## TODO
+
+- Create an immutable version of SparseRange
+- Create another edition of Ruby builtin range, supporting an optional external succ/comparator/whatever we may need to build an
+  arbitrary range
+- Create things like cyclic ranges, etc.
+
+

data/lib/extrarange/core_ext/range.rb

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

data/lib/extrarange/range_math.rb

@@ -0,0 +1,119 @@
+module ExtraRange
+  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/extrarange/range_with_math.rb

@@ -0,0 +1,16 @@
+require 'extrarange/range_math'
+
+module ExtraRange
+    class RangeWithMath < Range
+      include ExtraRange::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

data/lib/extrarange/sparse_range.rb

@@ -0,0 +1,198 @@
+require 'extrarange/range_math'
+require 'extrarange/range_with_math'
+
+module ExtraRange
+  class SparseRange
+    include ExtraRange::RangeMath
+    include Enumerable
+
+    def initialize(*ranges)
+      @ranges = []
+      ranges.each { |r| self.add r }
+    end
+
+    def begin
+      @ranges.first().begin
+    end
+
+    alias first begin
+
+    def end
+      @ranges.last().end
+    end
+
+    alias last end
+
+    def exclude_end?
+      @ranges.last().exclude_end?
+    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 then
+          o.each_range { |b| add b }
+        when 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 then
+          o.each_range { |s| delete s }
+        when 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
+          o.each_range do |i|
+            intersection = self & i
+            ret.add intersection if intersection
+          end
+          ret
+        when Enumerable
+          o.each do |i|
+            intersection = self & i
+            ret.add intersection if intersection
+          end
+          ret
+        else
+          self&(o..o)
+      end
+    end
+
+    alias intersection &
+
+    # BEWARE! SparseRange is mutable!
+    # it would be better to change its behaviour to return new sparseranges or to
+    # create a separate ImmutableSparseRange class.
+    def hash
+      return @ranges.hash
+    end
+
+    def max(&block)
+      maxes = @ranges.collect {|r| r.max(&block)}
+      (maxes.include? nil) ? nil : maxes.max(&block)
+    end
+
+    def min(&block)
+      mins = @ranges.collect {|r| r.min(&block)}
+      (mins.include? nil) ? nil : mins.min(&block)
+    end
+
+    def include?(elem)
+      @ranges.any? { |r| r.include? elem }
+    end
+
+    alias member? include?
+
+    # currently unoptimized yet working version.
+    # TODO: optimize this method to use the builtin cover? method for ranges if
+    # they're available, i.e. we're running on Ruby 1.9.1+
+    alias cover? include?
+
+    def to_a
+      @ranges.map { |r| r.to_a }.flatten
+    end
+
+    def each
+      to_a.each{ |o| yield o }
+    end
+
+    def size
+      @ranges.inject(0) { |sum, n| sum + n.size }
+    end
+
+    def empty?
+      @ranges.empty?
+    end
+
+    def each_range
+      @ranges.map { |r| r.to_range }.each { |o| yield o }
+    end
+
+    def step(n=1, &block)
+      enumerator = to_a.select.with_index.select { |_, index| (index % n) == 0 }.collect { |x, _| x }
+      if block_given?
+        enumerator.each(&block)
+      else
+        return enumerator
+      end
+    end
+
+    private
+
+    def _add(new_range)
+      new_range = ExtraRange::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 - ExtraRange::RangeWithMath.from_range(o) }
+      @ranges.flatten!
+      @ranges.compact!
+    end
+  end
+end

data/lib/extrarange.rb

@@ -0,0 +1,2 @@
+require 'extrarange/sparse_range'
+

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: extrarange
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Alan Franzoni
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-18 00:00:00 Z
+dependencies: []
+
+description: The SparseRange class lets you easily collect many ranges into one.You can perform logic operations such as union and intersection on ranges with gaps. Can replace a standard range.
+email: 
+- username@franzoni.eu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/extrarange.rb
+- lib/extrarange/range_with_math.rb
+- lib/extrarange/range_math.rb
+- lib/extrarange/sparse_range.rb
+- lib/extrarange/core_ext/range.rb
+- LICENSE
+- README.markdown
+homepage: http://extrarange.franzoni.eu
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 17
+      segments: 
+      - 1
+      - 3
+      - 5
+      version: 1.3.5
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Extended Range functionality
+test_files: []
+